harnex 0.12.0 → 0.29.0

data/lib/harnex/commands/wait.rb

@@ -1,6 +1,7 @@
 require "json"
 require "net/http"
 require "optparse"
+require "stringio"
 require "uri"
 
 module Harnex
@@ -19,7 +20,10 @@ module Harnex
     DONE_EXIT_FAILED = 1
     DONE_EXIT_REJECTED_PROOF = 2
     DONE_EXIT_NO_SESSION = 3
+    DONE_EXIT_STALLED = 4
     DONE_EXIT_TIMEOUT = 124
+    # Stall checks poll the live status API; detection lags by at most this.
+    STALL_POLL_MAX_INTERVAL = 15.0
 
     # Outcome classes where the process completed but the work was not
     # accepted: proof was missing, invalid, rejected, or nothing happened.
@@ -45,14 +49,30 @@ module Harnex
                                              "prompt", "busy")
                           Without --until, waits for session exit (default).
           --repo PATH     Resolve session using PATH's repo root (default: current repo)
-          --timeout SECS  Maximum time to wait in seconds (default: unlimited)
+          --timeout DUR   Hard observer cap (seconds, or suffix s/m/h; default: unlimited)
+          --max-wait DUR  Alias for --timeout
+          --heartbeat DUR  Flush observed progress to stderr at this interval (default: off)
+          --after-seq N   With --until done/task_complete/task_failed: ignore every
+                          event at or before events-log seq N (the after_seq that
+                          `harnex send` reports), so the wait covers the turn that
+                          message started or joined, not an earlier result.
+          --since TIME    With --until done: ignore events before TIME (ISO 8601),
+                          e.g. an earlier launch of a lane relaunched under the
+                          same id (each launch restarts the events-log seq)
+          --stall-after DUR
+                          With --until done: exit 4 when the live session shows no
+                          progress for DUR (Pi/structured: model, tool or turn
+                          events during an active turn; PTY: transcript idle).
+                          Never nudges or stops the worker.
           -h, --help      Show this help
 
         Common patterns:
-          #{program_name} --id cx-i-42 --until done --timeout 900
-          #{program_name} --id cx-i-42 --until task_complete --timeout 900
-          #{program_name} --id cx-i-42 --until prompt --timeout 120
-          #{program_name} --id cx-i-42
+          #{program_name} --id pi-i-42 --until done --timeout 900
+          #{program_name} --id pi-i-42 --until done --stall-after 25m --timeout 4h
+          #{program_name} --id pi-i-42 --until done --after-seq 812 --timeout 9m
+          #{program_name} --id pi-i-42 --until task_complete --timeout 900
+          #{program_name} --id pi-i-42 --until prompt --timeout 120
+          #{program_name} --id pi-i-42
 
         Exit codes for --until done:
           0    completed with accepted work
@@ -60,10 +80,13 @@ module Harnex
           2    completed but proof rejected (completed_no_activity,
                report_missing, report_invalid, report_rejected)
           3    no such session (no live, start, event, or terminal signal)
-          124  --timeout elapsed while the session was still running
+          4    stalled: no progress for --stall-after (worker left running)
+          124  observer deadline elapsed (does not stop the worker)
 
         Gotchas:
           done is the safest work-level fence for monitors.
+          A bare wait returns only on process exit; sessions without
+          --auto-stop stay alive after their turn (stderr notes say so).
           While the session's pid is alive, --until done blocks (up to
           --timeout); "no signal yet" from a live worker is never terminal.
           task_complete/task_failed are event predicates; prompt/busy are live state polls.
@@ -74,26 +97,72 @@ module Harnex
       TEXT
     end
 
-    def initialize(argv)
+    # Reuse the shared duration grammar while preserving wait's numeric
+    # timeout syntax and guarding numeric fallback/forwarded Float values.
+    def self.duration(value, option_name:)
+      seconds = begin
+        Harnex.parse_duration_seconds(value, option_name: option_name)
+      rescue OptionParser::InvalidArgument => invalid_duration
+        # Preserve wait --timeout's former Float syntax (e.g. .5 or 1e-3),
+        # also used by Float#to_s when watch forwards very small intervals.
+        begin
+          Float(value)
+        rescue ArgumentError, TypeError
+          raise invalid_duration
+        end
+      end
+      unless seconds.finite? && seconds.positive?
+        raise OptionParser::InvalidArgument, "#{option_name} must be a finite positive duration"
+      end
+      seconds
+    end
+
+    def initialize(argv, out: nil, err: nil)
       @argv = argv.dup
+      @out = out
+      @err = err
       @options = {
         id: nil,
         until_state: nil,
         repo_path: Dir.pwd,
         timeout: nil,
+        heartbeat: nil,
+        stall_after: nil,
+        after_seq: nil,
+        since: nil,
         help: false
       }
     end
 
     def run
+      @out ||= $stdout
+      @err ||= $stderr
       parser.parse!(@argv)
       if @options[:help]
-        puts self.class.usage
+        @out.puts self.class.usage
         return 0
       end
 
       raise "--id is required for harnex wait" unless @options[:id]
+      if @options[:stall_after] && @options[:until_state] != "done"
+        raise OptionParser::InvalidOption, "--stall-after requires --until done"
+      end
+      if @options[:after_seq] && !(["done"] + EVENT_PREDICATES).include?(@options[:until_state])
+        raise OptionParser::InvalidOption, "--after-seq requires --until done, task_complete, or task_failed"
+      end
 
+      @started_at = monotonic
+      @observation = { "state" => "unknown", "last_event" => "unknown", "seq" => nil }
+      if @options[:timeout] || @options[:heartbeat]
+        observe_in_child
+      else
+        wait
+      end
+    end
+
+    private
+
+    def wait
       if @options[:until_state]
         case @options[:until_state]
         when "done"
@@ -108,14 +177,180 @@ module Harnex
       end
     end
 
-    private
+    # Only the read-side observer runs in this child, never the session or any
+    # stop/marker action. A process boundary lets the parent enforce its cap
+    # during blocking Ruby/HTTP probes, even probes with slow ensure clauses or
+    # broad rescue handlers. No asynchronous Ruby exception crosses a probe.
+    # The private process group also contains repo-resolution subprocesses.
+    def observe_in_child
+      reader, writer = IO.pipe
+      writer.sync = true
+      pid = fork do
+        exit_code = 1
+        begin
+          Process.setpgid(0, 0)
+          reader.close
+          @observation_writer = writer
+          @out = StringIO.new
+          @err = DiagnosticStream.new { |text| send_observation_message(["warning", text]) }
+          code = wait
+          send_observation_message(["result", @out.string, code])
+          exit_code = 0
+        rescue Exception => error # transport errors too; never run inherited at_exit hooks
+          begin
+            send_observation_message(["error", error.class.name, error.message, error.backtrace])
+          rescue IOError, SystemCallError
+            nil # the caller may already have closed the pipe
+          end
+        ensure
+          exit! exit_code
+        end
+      end
+      writer.close
+      deadline = @options[:timeout] && @started_at + @options[:timeout]
+      next_heartbeat = @options[:heartbeat] && @started_at + @options[:heartbeat]
+      buffer = +""
+
+      loop do
+        now = monotonic
+        return emit_timeout if deadline && now >= deadline
+
+        # Drain complete records without blocking on a partial pipe write.
+        if (newline = buffer.index("\n"))
+          message = JSON.parse(buffer.slice!(0..newline))
+          case message[0]
+          when "observation" then @observation = message[1]
+          when "warning" then @err.write(message[1])
+          when "result"
+            return emit_timeout if deadline && monotonic >= deadline
+
+            @out.write(message[1])
+            return message[2]
+          when "error"
+            raise RuntimeError, "harnex wait observer: #{message[1]}: #{message[2]}", message[3]
+          end
+          next
+        end
+
+        if next_heartbeat && now >= next_heartbeat
+          emit_heartbeat
+          # Do not burst missed heartbeats after a scheduler pause.
+          next_heartbeat = now + @options[:heartbeat]
+        end
+        wake_at = [deadline, next_heartbeat].compact.min
+        # Clamp even finite enormous durations to an OS-safe select timeout.
+        pause = [[wake_at - monotonic, 0].max, POLL_INTERVAL].min
+        IO.select([reader], nil, nil, pause)
+        chunk = reader.read_nonblock(16_384, exception: false)
+        raise "harnex wait: observer exited without a result" if chunk.nil?
+
+        buffer << chunk unless chunk == :wait_readable
+      end
+    ensure
+      reader&.close unless reader&.closed?
+      writer&.close unless writer&.closed?
+      reap_observer(pid) if pid
+    end
+
+    # SIGKILL bypasses slow Ruby ensure handlers. Reap without an unbounded
+    # wait/join. Uninterruptible kernel I/O or a descheduled OS cannot be given
+    # a universal preemption guarantee; no helper thread is left waiting on it.
+    def reap_observer(pid)
+      begin
+        Process.kill("KILL", -pid)
+      rescue Errno::ESRCH
+        nil
+      end
+      begin
+        Process.kill("KILL", pid)
+      rescue Errno::ESRCH
+        nil
+      end
+      cleanup_deadline = monotonic + EVENT_POLL_INTERVAL
+      loop do
+        return if Process.waitpid(pid, Process::WNOHANG)
+        break if monotonic >= cleanup_deadline
+
+        sleep 0.005
+      end
+      @err.puts("harnex wait: OS has not reaped the cancelled observer yet")
+    rescue Errno::ECHILD
+      nil
+    end
+
+    class DiagnosticStream
+      def initialize(&write)
+        @write = write
+      end
+
+      def write(text)
+        @write.call(text)
+      end
+
+      def puts(text)
+        write("#{text}\n")
+      end
+    end
+
+    def send_observation_message(message)
+      @observation_writer.write(JSON.generate(message) + "\n")
+    end
+
+    def observe(**fields)
+      updated = @observation.merge(fields.transform_keys(&:to_s))
+      return if updated == @observation
+
+      @observation = updated
+      send_observation_message(["observation", updated]) if @observation_writer
+    end
+
+    def emit_heartbeat
+      # These are observations, not model/tool activity or a log-age proxy.
+      values = %w[state last_event seq].map do |key|
+        value = @observation[key] || "unknown"
+        "#{key}=#{value.to_s.gsub(/[[:space:][:cntrl:]]/, '_')[0, 128]}"
+      end
+      @err.puts("harnex wait: id=#{@options[:id]} waited=#{(monotonic - @started_at).round(1)}s #{values.join(' ')}")
+      @err.flush
+    end
+
+    def emit_timeout
+      payload = { ok: false, id: @options[:id], status: "timeout",
+                  waited_seconds: (monotonic - @started_at).round(1) }
+      case @options[:until_state]
+      when "done"
+        payload.merge!(wait_result: "timeout", done: false,
+                       work_state: @observation["live"] ? "running" : "unknown")
+      when *EVENT_PREDICATES
+        # Event waits retain their existing timeout payload shape.
+      when nil
+        payload[:pid] = @observation["pid"] if @observation["pid"]
+      else
+        payload[:state] = @observation["state"]
+      end
+      @out.puts JSON.generate(payload)
+      DONE_EXIT_TIMEOUT
+    end
+
+    # All output goes through per-instance streams, including legacy wait
+    # diagnostics. Resolve defaults in run so callers can still capture IO.
+    def puts(text)
+      @out.puts(text)
+    end
+
+    def warn(text)
+      @err.puts(text)
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
 
     def wait_until_event(predicate)
       repo_root = Harnex.resolve_repo_root(@options[:repo_path])
       events_path = Harnex.events_log_path(repo_root, @options[:id])
       registry = Harnex.read_registry(repo_root, @options[:id])
-      start_time = Time.now
-      deadline = @options[:timeout] ? start_time + @options[:timeout] : nil
+      start_time = @started_at
 
       unless registry || File.exist?(events_path)
         warn("harnex wait: no session found with id #{@options[:id].inspect}")
@@ -131,21 +366,17 @@ module Harnex
       return status if status
 
       target_pid = registry && registry["pid"]
+      observe(state: "running", pid: target_pid) if target_pid
 
       loop do
         status, offset, task_complete_seen = scan_events(events_path, offset, predicate, task_complete_seen, start_time)
         return status if status
 
-        if deadline && Time.now >= deadline
-          waited = (Time.now - start_time).round(1)
-          puts JSON.generate(ok: false, id: @options[:id], status: "timeout", waited_seconds: waited)
-          return 124
-        end
-
         if target_pid && !Harnex.alive_pid?(target_pid)
-          final_event_deadline ||= Time.now + FINAL_EVENT_GRACE_SECONDS
-          if Time.now >= final_event_deadline
-            waited = (Time.now - start_time).round(1)
+          observe(state: "exited")
+          final_event_deadline ||= monotonic + FINAL_EVENT_GRACE_SECONDS
+          if monotonic >= final_event_deadline
+            waited = (monotonic - start_time).round(1)
             puts JSON.generate(ok: false, id: @options[:id], state: "exited", waited_seconds: waited)
             return 1
           end
@@ -168,7 +399,10 @@ module Harnex
           event = parse_event(line)
           next unless event
           next if stale_event?(event, min_ts)
+          next if before_after_seq?(event)
 
+          observe(last_event: event_type(event), seq: event["seq"])
+          observe(state: event["state"]) if event_type(event) == "agent_state" && event["state"]
           task_complete_seen = true if %w[task_complete task_failed].include?(event_type(event))
           if matches?(event, predicate, task_complete_seen)
             return [emit_event_match(event, start_time, predicate), f.pos, task_complete_seen]
@@ -180,6 +414,15 @@ module Harnex
       [nil, offset, task_complete_seen]
     end
 
+    # #81: events at or before --after-seq belong to an earlier turn. An event
+    # without a seq cannot be placed after it, so it never matches either.
+    def before_after_seq?(event)
+      return false unless @options[:after_seq]
+
+      seq = event["seq"]
+      !seq.is_a?(Integer) || seq <= @options[:after_seq]
+    end
+
     def stale_event?(event, min_ts)
       return false unless min_ts
 
@@ -235,7 +478,7 @@ module Harnex
     end
 
     def emit_event_match(event, start_time, predicate)
-      waited = (Time.now - start_time).round(1)
+      waited = (monotonic - start_time).round(1)
       payload = {
         ok: true,
         id: @options[:id],
@@ -243,30 +486,48 @@ module Harnex
         seq: event["seq"],
         waited_seconds: waited
       }
+      payload[:turn] = event["turn"] if event["turn"]
+      payload[:follow_ups] = event["follow_ups"] if event["follow_ups"]
+      %w[end_sha commits turn_commits model final_message final_message_path final_message_truncated].each do |key|
+        payload[key.to_sym] = event[key] if event.key?(key)
+      end
       exit_code = 0
       if predicate == "done"
         failed = done_event_failed?(event)
-        exit_code = failed ? done_failure_exit_code(event["outcome_class"]) : DONE_EXIT_DONE
+        outcome_class = event["outcome_class"] || stop_outcome_class(event["stop"])
+        exit_code = failed ? done_failure_exit_code(outcome_class) : DONE_EXIT_DONE
+        # A session seen gone by now has exited; one never observed stays
+        # "running", the historical event-match default.
+        exited = @observation["live"] == false
         payload.merge!(
           ok: !failed,
           status: failed ? "failed" : "done",
           wait_result: done_wait_result(exit_code),
-          state: "running",
-          process_state: "running",
-          terminal: false,
+          state: exited ? "exited" : "running",
+          process_state: exited ? "exited" : "running",
+          terminal: exited,
           task_complete: !failed,
           task_failed: failed,
           done: !failed,
           work_state: failed ? "failed" : "completed",
-          outcome_class: event["outcome_class"],
+          outcome_class: outcome_class,
           artifact_report_status: event["artifact_report_status"]
         )
         payload[:last_error] = event["message"] || event["error"] if failed
+        payload[:stop] = event["stop"] if event["stop"].is_a?(Hash)
       end
       puts JSON.generate(payload)
       exit_code
     end
 
+    # A turn failed by a caller's stop or the runtime budget carries the
+    # stop provenance, not a class; name it as the dispatch row will.
+    def stop_outcome_class(stop)
+      return nil unless stop.is_a?(Hash)
+
+      { "manual" => "stopped_by_caller", "runtime_budget" => "timeout" }[stop["reason"].to_s]
+    end
+
     def done_failure_exit_code(outcome_class)
       REJECTED_PROOF_CLASSES.include?(outcome_class.to_s) ? DONE_EXIT_REJECTED_PROOF : DONE_EXIT_FAILED
     end
@@ -288,25 +549,32 @@ module Harnex
       repo_root = Harnex.resolve_repo_root(@options[:repo_path])
       events_path = Harnex.events_log_path(repo_root, @options[:id])
       exit_path = Harnex.exit_status_path(repo_root, @options[:id])
-      start_time = Time.now
-      deadline = @options[:timeout] ? start_time + @options[:timeout] : nil
+      start_time = @started_at
 
       offset = 0
       task_complete_seen = false
       observed_live = nil
       session_started_at = nil
+      next_stall_check = nil
 
       loop do
         live = live_session(repo_root)
+        observe(state: live ? "running" : "unknown", pid: live && live["pid"], live: !!live)
         if live
           observed_live = live
           session_started_at ||= parse_wait_time(live["started_at"])
         end
 
         status, offset, task_complete_seen =
-          scan_events(events_path, offset, "done", task_complete_seen, start_time, min_ts: session_started_at)
+          scan_events(events_path, offset, "done", task_complete_seen, start_time, min_ts: done_min_ts(session_started_at))
         return status if status
 
+        if @options[:stall_after] && live && (next_stall_check.nil? || monotonic >= next_stall_check)
+          next_stall_check = monotonic + stall_poll_interval
+          stall = Harnex::Stall.stalled(fetch_status_payload(live), @options[:stall_after])
+          return emit_stall(stall, start_time) if stall
+        end
+
         unless live
           if observed_live
             return resolve_after_exit(repo_root, events_path, exit_path, offset,
@@ -328,18 +596,45 @@ module Harnex
           end
         end
 
-        if deadline && Time.now >= deadline
-          waited = (Time.now - start_time).round(1)
-          puts JSON.generate(ok: false, id: @options[:id], status: "timeout", wait_result: "timeout",
-                             waited_seconds: waited, done: false,
-                             work_state: live ? "running" : "unknown")
-          return DONE_EXIT_TIMEOUT
-        end
-
         sleep EVENT_POLL_INTERVAL
       end
     end
 
+    def done_min_ts(session_started_at)
+      [session_started_at, @options[:since]].compact.max
+    end
+
+    def stall_poll_interval
+      [[@options[:stall_after] / 4.0, 0.5].max, STALL_POLL_MAX_INTERVAL].min
+    end
+
+    # Only a registry row has the live API; start-record liveness cannot be
+    # probed, so a stall stays unobserved there rather than guessed.
+    def fetch_status_payload(live)
+      return nil unless live["host"] && live["port"]
+
+      uri = URI("http://#{live['host']}:#{live['port']}/status")
+      request = Net::HTTP::Get.new(uri)
+      request["Authorization"] = "Bearer #{live['token']}" if live["token"]
+      response = Net::HTTP.start(uri.host, uri.port, open_timeout: 1, read_timeout: 2) { |http| http.request(request) }
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body)
+    rescue StandardError
+      nil
+    end
+
+    # The worker is left running: this is an observer verdict, like a timeout.
+    def emit_stall(stall, start_time)
+      waited = (monotonic - start_time).round(1)
+      warn("harnex wait: #{@options[:id]} shows no progress for #{stall['idle_s'].round}s " \
+           "(clock=#{stall['clock']}, threshold #{stall['threshold_s'].round}s); worker left running")
+      puts JSON.generate(ok: false, id: @options[:id], status: "stalled", wait_result: "stalled",
+                         state: "running", process_state: "running", terminal: false, task_complete: false,
+                         done: false, work_state: "running", stall: stall, waited_seconds: waited)
+      DONE_EXIT_STALLED
+    end
+
     # Registry row first; when it is not visible from this context, an
     # uncompleted dispatch-start row with an alive pid still proves liveness.
     def live_session(repo_root)
@@ -357,7 +652,7 @@ module Harnex
       await_exit_status(exit_path)
 
       status, _offset, _seen =
-        scan_events(events_path, offset, "done", task_complete_seen, start_time, min_ts: session_started_at)
+        scan_events(events_path, offset, "done", task_complete_seen, start_time, min_ts: done_min_ts(session_started_at))
       return status if status
 
       if File.exist?(exit_path) && fresh_exit_status?(exit_path, observed_live, session_started_at)
@@ -367,7 +662,7 @@ module Harnex
       terminal = done_status(repo_root, min_started_at: session_started_at)
       return emit_done_terminal_status(terminal) if terminal
 
-      waited = (Time.now - start_time).round(1)
+      waited = (monotonic - start_time).round(1)
       puts JSON.generate(ok: false, id: @options[:id], state: "exited", process_state: "exited",
                          terminal: true, task_complete: false, done: false, work_state: "unknown",
                          wait_result: "failed", waited_seconds: waited)
@@ -399,8 +694,7 @@ module Harnex
     def wait_until_state
       repo_root = Harnex.resolve_repo_root(@options[:repo_path])
       target_state = @options[:until_state]
-      start_time = Time.now
-      deadline = @options[:timeout] ? start_time + @options[:timeout] : nil
+      start_time = @started_at
 
       registry = Harnex.read_registry(repo_root, @options[:id])
       unless registry
@@ -417,31 +711,25 @@ module Harnex
 
       loop do
         unless Harnex.alive_pid?(target_pid)
-          waited = (Time.now - start_time).round(1)
+          waited = (monotonic - start_time).round(1)
           puts JSON.generate(ok: false, id: @options[:id], state: "exited", waited_seconds: waited)
           return 1
         end
 
         state = fetch_agent_state(host, port, token)
+        observe(state: state || "unknown", pid: target_pid)
         if state == target_state
-          waited = (Time.now - start_time).round(1)
+          waited = (monotonic - start_time).round(1)
           puts JSON.generate(ok: true, id: @options[:id], state: state, waited_seconds: waited)
           return 0
         end
 
-        if deadline && Time.now >= deadline
-          waited = (Time.now - start_time).round(1)
-          puts JSON.generate(ok: false, id: @options[:id], state: state || "unknown", waited_seconds: waited, status: "timeout")
-          return 124
-        end
-
         sleep POLL_INTERVAL
       end
     end
 
     def wait_until_exit
       repo_root = Harnex.resolve_repo_root(@options[:repo_path])
-      deadline = @options[:timeout] ? Time.now + @options[:timeout] : nil
       exit_path = Harnex.exit_status_path(repo_root, @options[:id])
 
       registry = Harnex.read_registry(repo_root, @options[:id])
@@ -458,7 +746,9 @@ module Harnex
       end
 
       target_pid = registry["pid"]
+      observe(state: "running", pid: target_pid)
       warn("harnex wait: watching session #{@options[:id]} (pid #{target_pid})")
+      hint = exit_wait_hint(repo_root, registry)
 
       loop do
         unless Harnex.alive_pid?(target_pid)
@@ -473,22 +763,75 @@ module Harnex
           return 1
         end
 
-        if deadline && Time.now >= deadline
-          puts JSON.generate(ok: false, id: @options[:id], status: "timeout", pid: target_pid)
-          return 124
+        if hint && (settled = settled_event_type(hint))
+          warn("harnex wait: note: #{@options[:id]} reached #{settled} but is still alive; " \
+               "this wait still returns only on process exit. Use --until done for a work-level fence.")
+          hint = nil
         end
 
         sleep POLL_INTERVAL
       end
     end
 
+    # A bare wait fences process exit, but an interactive session stays alive
+    # at its prompt after a turn. Say so on entry, and once more if the turn
+    # settles mid-wait, so a waiter on the wrong predicate learns it before
+    # its timeout (#49). --auto-stop sessions exit on their own: no hint.
+    # Returns the event-scan cursor for the mid-wait check, or nil when done.
+    def exit_wait_hint(repo_root, registry)
+      return nil if registry["auto_stop"] == true
+
+      cursor = {
+        path: Harnex.events_log_path(repo_root, @options[:id]),
+        offset: 0,
+        min_ts: parse_wait_time(registry["started_at"])
+      }
+      if (settled = settled_event_type(cursor))
+        warn("harnex wait: note: #{@options[:id]} already reached #{settled} and stays alive at its prompt; " \
+             "this wait returns only on process exit. Use --until done for a work-level fence.")
+        return nil
+      end
+
+      reason =
+        if registry["auto_stop"] == false
+          "was not started with --auto-stop, so it stays alive after its turn"
+        else
+          "may stay alive at its prompt after its turn unless started with --auto-stop"
+        end
+      warn("harnex wait: note: #{@options[:id]} #{reason}; this wait returns only on process exit. " \
+           "Use --until done for a work-level fence.")
+      cursor
+    end
+
+    def settled_event_type(cursor)
+      path = cursor[:path]
+      return nil unless File.exist?(path) && File.size(path) > cursor[:offset]
+
+      File.open(path, "r") do |f|
+        f.seek(cursor[:offset])
+        f.each_line do |line|
+          # Only whole lines advance the cursor; a partial tail is re-read.
+          break unless line.end_with?("\n")
+
+          cursor[:offset] = f.pos
+          event = parse_event(line)
+          next unless event
+          next if stale_event?(event, cursor[:min_ts])
+
+          type = event_type(event)
+          return type if %w[task_complete task_failed].include?(type)
+        end
+      end
+      nil
+    end
+
     # Subprocess death races the parent's DISPATCH-row write; the exit-status
     # file is written *after* the row, so polling it bounds the race.
     def await_exit_status(exit_path)
       return if File.exist?(exit_path)
 
-      grace_deadline = Time.now + exit_status_grace_seconds
-      until File.exist?(exit_path) || Time.now >= grace_deadline
+      grace_deadline = monotonic + exit_status_grace_seconds
+      until File.exist?(exit_path) || monotonic >= grace_deadline
         sleep EXIT_STATUS_GRACE_POLL_INTERVAL
       end
     end
@@ -622,6 +965,8 @@ module Harnex
         work_state: work_state,
         outcome_class: status["outcome_class"],
         artifact_report_status: status["artifact_report_status"],
+        stop: status["stop"],
+        runtime_budget: status["runtime_budget"],
         exit: status["exit"],
         exit_code: status["exit_code"],
         ended_at: status["ended_at"],
@@ -635,7 +980,27 @@ module Harnex
         opts.on("--id ID", "Session ID to wait for") { |value| @options[:id] = Harnex.normalize_id(value) }
         opts.on("--until STATE", "Wait until session reaches STATE") { |value| @options[:until_state] = value }
         opts.on("--repo PATH", "Resolve session using PATH's repo root") { |value| @options[:repo_path] = value }
-        opts.on("--timeout SECONDS", Float, "Maximum time to wait") { |value| @options[:timeout] = value }
+        opts.on("--timeout DUR", "Hard observer cap") do |value|
+          @options[:timeout] = self.class.duration(value, option_name: "--timeout")
+        end
+        opts.on("--max-wait DUR", "Alias for --timeout") do |value|
+          @options[:timeout] = self.class.duration(value, option_name: "--max-wait")
+        end
+        opts.on("--heartbeat DUR", "Flush progress to stderr") do |value|
+          @options[:heartbeat] = self.class.duration(value, option_name: "--heartbeat")
+        end
+        opts.on("--after-seq N", Integer, "Ignore events at or before events-log seq N") do |value|
+          raise OptionParser::InvalidArgument, "--after-seq must be 0 or greater" if value.negative?
+
+          @options[:after_seq] = value
+        end
+        opts.on("--since TIME", "With --until done: ignore events before TIME") do |value|
+          @options[:since] = parse_wait_time(value) ||
+                             raise(OptionParser::InvalidArgument, "--since must be an ISO 8601 time")
+        end
+        opts.on("--stall-after DUR", "With --until done: exit 4 after DUR without progress") do |value|
+          @options[:stall_after] = self.class.duration(value, option_name: "--stall-after")
+        end
         opts.on("-h", "--help", "Show help") { @options[:help] = true }
       end
     end