harnex 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5db22a80eebc5f0441437c96a2f949f0dd117cf78a2cc0810f24172c7af7cd4
-  data.tar.gz: 3ad9ed119b373258b1e8c56ea80b27ea49dad028031e19bd4ee0697996a45046
+  metadata.gz: e4d7c194ba2ba10ee075e6e53aa3eaf291cbfc08eca1d89cd291955834230c01
+  data.tar.gz: e3bafc087ae74a484be3ee121cce0d8f351c6b381ce244d5da032e48c85da4db
 SHA512:
-  metadata.gz: 1dd3ad5ef1cf5bb17d6a92ea6b27b746ef47a8e1a8e58b1e2a98936946f63f58d8d297d7493ffc3ab3968e25ac26415ae73c44524423a83f36c5951b4e729813
-  data.tar.gz: 39cf0ed49b278a10ff57767d6cc166232e7c30ca9eed31853d079a2a437dcd0ee4709a8a13959e91bd106d8ce7b1e1b043b64a6df0fd24988a925266c488769a
+  metadata.gz: e3737c2aa49fb223c75cfc0d997a52bb72029b4c1a7a11affdd05a16c685e4edc42384ff0cfc03e63e4b4abcc9228c7f1d37c408c074538392c75d13be4e1e5e
+  data.tar.gz: 0b096fb9d95f22b812fc43fc69b4f8546e090d76c669383b8d71b34a048aa8eed46510f7ce9be27e0da3eab449a610c13fd6a338d8e1c202649d235df7052154

data/GUIDE.md

@@ -49,6 +49,17 @@ automatically when the agent is ready. You don't have to wait
 or retry. Queueing exists, but the default workflow should still be
 one task per fresh worker.
 
+For unattended dispatch, prefer built-in monitoring over external poll loops:
+
+```bash
+harnex run codex --id impl --tmux impl --watch --preset impl
+```
+
+This adds a foreground watcher that checks idle activity and performs bounded
+force-resume nudges. For full flag behavior and event-stream consumers, see
+[TECHNICAL.md](TECHNICAL.md) and the built-in monitoring section in
+[README.md](README.md).
+
 ## Seeing what's running
 
 ```bash

data/README.md

@@ -105,12 +105,43 @@ Install skills so agents can use them:
 harnex skills install
 ```
 
+## Built-in dispatch monitoring
+
+For unattended dispatches, use `--watch` instead of writing a bash poll loop:
+
+```bash
+harnex run codex --id cx-impl-42 --tmux cx-impl-42 --watch --preset impl \
+  --context "Implement koder/plans/42_plan.md. Run tests and commit when done."
+```
+
+`--watch` runs a foreground babysitter that checks session activity every 60s,
+force-resumes on stall up to a cap, and exits when the target session exits or
+the resume cap is reached.
+
+Presets map to stall policy defaults:
+
+- `impl` -> `--stall-after 8m --max-resumes 1`
+- `plan` -> `--stall-after 3m --max-resumes 2`
+- `gate` -> `--stall-after 15m --max-resumes 0`
+
+Explicit `--stall-after` and `--max-resumes` flags override preset defaults.
+
+For structured subscriptions, stream JSONL events:
+
+```bash
+harnex events --id cx-impl-42 | jq -c '.'
+```
+
+Schema details and compatibility policy are documented in
+[docs/events.md](docs/events.md).
+
 ## Long-running and overnight work
 
-A **buddy** is a second agent that watches something and acts on it.
-It's just another harnex session — no special monitoring code, no
-configuration. The buddy is an LLM, so it reasons about what it sees
-rather than pattern-matching.
+For plain "force-resume on stall" recovery, use
+`harnex run --watch --preset impl`.
+
+A **buddy** is for richer reasoning: doc drift checks, semantic sanity checks,
+and multi-session correlation. It's still just another harnex session.
 
 ### Example: keep a worker from stalling
 
@@ -168,12 +199,13 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 
 | Command | What it does |
 |---------|-------------|
-| `harnex run <cli>` | Start an agent (`--tmux` for a visible window, `--detach` for background) |
+| `harnex run <cli>` | Start an agent (`--tmux` visible, `--detach` background, `--watch` built-in monitoring) |
 | `harnex send --id <id>` | Send a message (queues if busy, `--wait-for-idle` to block until done) |
 | `harnex stop --id <id>` | Send the agent's native exit sequence |
 | `harnex status` | List running sessions (`--json` for full payloads) |
 | `harnex pane --id <id>` | Capture the agent's tmux screen (`--follow` for live) |
 | `harnex logs --id <id>` | Read session transcript (`--follow` to tail) |
+| `harnex events --id <id>` | Stream structured session events (`--snapshot` for non-blocking dump) |
 | `harnex wait --id <id>` | Block until exit or a target state |
 | `harnex guide` | Getting started walkthrough |
 | `harnex recipes` | Tested workflow patterns |

data/TECHNICAL.md

@@ -14,17 +14,21 @@ harnex run claude --id review
 harnex run codex -- --cd ~/other/repo
 ```
 
-| Flag            | What it does                          |
-|-----------------|---------------------------------------|
-| `--id ID`       | Name this session (default: random)   |
-| `--description` | Store a short session description     |
-| `--detach`      | Run in background, no terminal        |
-| `--tmux [NAME]` | Run in a tmux window you can watch    |
-| `--host HOST`   | Bind a specific API host              |
-| `--port PORT`   | Force a specific API port             |
-| `--context TXT` | Give the agent a task on startup      |
-| `--watch PATH`  | Notify agent when a file changes      |
-| `--timeout SEC` | Wait budget for detached registration |
+| Flag                | What it does                                                        |
+|---------------------|---------------------------------------------------------------------|
+| `--id ID`           | Name this session (default: random)                                 |
+| `--description`     | Store a short session description                                   |
+| `--detach`          | Run in background, no terminal                                      |
+| `--tmux [NAME]`     | Run in a tmux window you can watch                                  |
+| `--host HOST`       | Bind a specific API host                                            |
+| `--port PORT`       | Force a specific API port                                           |
+| `--watch`           | Enable blocking babysitter mode (foreground only)                   |
+| `--stall-after DUR` | Idle threshold before force-resume (default: `480s`)                |
+| `--max-resumes N`   | Max forced resumes before escalation (default: `1`)                 |
+| `--preset NAME`     | Watch preset (`impl`, `plan`, `gate`), requires `--watch`           |
+| `--watch-file PATH` | Auto-send a file-change hook (`--watch PATH`/`--watch=PATH` legacy) |
+| `--context TXT`     | Give the agent a task on startup                                    |
+| `--timeout SEC`     | Wait budget for detached registration                               |
 
 ### `harnex send` — Talk to a running agent
 
@@ -61,12 +65,20 @@ failures for up to the given timeout.
 ### `harnex status` — See running agents
 
 ```
-  ID       CLI     AGE      STATE
-  worker   codex   36s ago  prompt
-  review   claude   8s ago  busy
+ID      CLI    PID    PORT   AGE  IDLE  STATE   REPO   DESC
+worker  codex  12345  43123  36s  12s   prompt  ~/...  -
+review  claude 12346  43124   8s  -     busy    ~/...  -
 ```
 
-Use `--json` for full payloads. Use `--all` for all repos.
+Text mode includes an `IDLE` column derived from `log_idle_s` (`-` means no
+transcript activity yet).
+
+Use `--json` for full payloads. JSON includes:
+
+- `log_mtime` (ISO8601 or `null`) — transcript file mtime
+- `log_idle_s` (Integer or `null`) — seconds since last transcript write
+
+Use `--all` for all repos.
 
 ### `harnex wait` — Wait for an agent to finish
 
@@ -160,12 +172,54 @@ harnex run codex --id impl-1 --tmux cx-p1 \
 ### File watching
 
 ```bash
-harnex run codex --id worker --watch ./tmp/status.jsonl
+harnex run codex --id worker --watch-file ./tmp/status.jsonl
 ```
 
 Agent gets notified when the file changes. File doesn't need to
 exist at startup.
 
+Legacy compatibility: `--watch PATH` and `--watch=PATH` still configure
+file-hook mode.
+
+## harnex events
+
+`harnex events` streams structured per-session JSONL for orchestrators and
+monitoring tooling.
+
+```bash
+harnex events --id worker
+harnex events --id worker --snapshot
+harnex events --id worker --from 2026-04-29T10:00:00Z
+harnex events --id worker | jq -c '.'
+```
+
+| Flag | What it does |
+|------|---------------|
+| `--id ID` | Session ID to inspect (required) |
+| `--[no-]follow` | Stream appended events (default: follow) |
+| `--snapshot` | Print current event file and exit (`--no-follow`) |
+| `--from TS` | Replay floor (ISO-8601, inclusive; `ts >= from`) |
+| `--repo PATH` | Resolve ID from a specific repo root |
+| `--cli CLI` | Filter active-session resolution by CLI |
+
+Exit codes:
+
+- `0` — snapshot completed, or follow mode observed `type: "exited"`
+- `1` — operational error (missing stream/session, invalid `--from`,
+  stream truncated/disappeared, lookup failure)
+
+Transport file (append-only JSONL):
+
+```
+~/.local/state/harnex/events/<repo_hash>--<id>.jsonl
+```
+
+Each row uses schema v1 with envelope fields `schema_version`, `seq`, `ts`,
+`id`, and `type`. Emitted today: `started`, `send`, `exited`. `send.msg` is a
+200-character preview with `msg_truncated` when shortened.
+
+Schema details and compatibility guarantees are in [docs/events.md](docs/events.md).
+
 ## Architecture
 
 ```
@@ -218,6 +272,8 @@ When you run `harnex run codex --id worker`:
       ~/.local/state/harnex/sessions/<repo_hash>--<id>.json
       and open transcript file:
       ~/.local/state/harnex/output/<repo_hash>--<id>.log
+      and open events file:
+      ~/.local/state/harnex/events/<repo_hash>--<id>.jsonl
  8. Start background threads:
       - PTY reader (screen buffer)
       - State machine (adapter parses screen for state)

data/lib/harnex/cli.rb

@@ -21,6 +21,8 @@ module Harnex
         Status.new(@argv.drop(1)).run
       when "logs"
         Logs.new(@argv.drop(1)).run
+      when "events"
+        Events.new(@argv.drop(1)).run
       when "pane"
         Pane.new(@argv.drop(1)).run
       when "recipes"
@@ -59,6 +61,8 @@ module Harnex
         Status.usage
       when "logs"
         Logs.usage
+      when "events"
+        Events.usage
       when "pane"
         Pane.usage
       when "recipes"
@@ -81,6 +85,7 @@ module Harnex
           harnex stop --id ID [options]
           harnex status [options]
           harnex logs --id ID [options]
+          harnex events --id ID [options]
           harnex pane --id ID [options]
           harnex help [command]
 
@@ -91,6 +96,7 @@ module Harnex
           stop    Send the adapter stop sequence to a session
           status  List live sessions
           logs    Read session output transcripts
+          events  Stream per-session JSONL runtime events
           pane    Capture the current tmux pane for a live session
           recipes List and read workflow recipes
           guide   Show the getting started guide
@@ -109,6 +115,7 @@ module Harnex
           harnex run codex -- --cd /path/to/repo
           harnex status
           harnex logs --id main --follow
+          harnex events --id main --snapshot
           harnex pane --id main --lines 40
           harnex send --id main --message "Summarize current progress."
           harnex skills install

data/lib/harnex/commands/events.rb

@@ -0,0 +1,212 @@
+require "json"
+require "optparse"
+require "time"
+
+module Harnex
+  class Events
+    POLL_INTERVAL = 0.1
+
+    def self.usage(program_name = "harnex events")
+      <<~TEXT
+        Usage: #{program_name} [options]
+
+        Options:
+          --id ID         Session ID to inspect (required)
+          --repo PATH     Resolve using PATH's repo root (default: current repo)
+          --cli CLI       Filter the active session by CLI
+          --[no-]follow   Keep streaming appended events (default: true)
+          --snapshot      Print current events and exit (alias for --no-follow)
+          --from TS       Replay floor (ISO-8601, inclusive)
+          -h, --help      Show this help
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+      @options = {
+        id: nil,
+        repo_path: Dir.pwd,
+        cli: nil,
+        follow: true,
+        from: nil,
+        help: false
+      }
+      @tail_buffer = +""
+    end
+
+    def run
+      parser.parse!(@argv)
+      if @options[:help]
+        puts self.class.usage
+        return 0
+      end
+
+      raise "--id is required for harnex events" unless @options[:id]
+
+      target = resolve_target
+      return 1 unless target
+
+      offset = print_snapshot(target.fetch(:path))
+      return 0 unless @options[:follow] && target[:live]
+
+      follow(target.fetch(:path), offset)
+    end
+
+    private
+
+    def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = "Usage: harnex events [options]"
+        opts.on("--id ID", "Session ID to inspect") { |value| @options[:id] = Harnex.normalize_id(value) }
+        opts.on("--repo PATH", "Resolve using PATH's repo root") { |value| @options[:repo_path] = value }
+        opts.on("--cli CLI", "Filter the active session by CLI") { |value| @options[:cli] = value }
+        opts.on("--[no-]follow", "Keep streaming appended events") { |value| @options[:follow] = value }
+        opts.on("--snapshot", "Print current events and exit") { @options[:follow] = false }
+        opts.on("--from TS", "Replay floor (ISO-8601, inclusive)") { |value| @options[:from] = parse_from(value) }
+        opts.on("-h", "--help", "Show help") { @options[:help] = true }
+      end
+    end
+
+    def parse_from(value)
+      Time.iso8601(value.to_s)
+    rescue ArgumentError
+      raise OptionParser::InvalidArgument, "--from must be an ISO-8601 timestamp"
+    end
+
+    def resolve_target
+      repo_root = Harnex.resolve_repo_root(@options[:repo_path])
+      session = Harnex.read_registry(repo_root, @options[:id], cli: @options[:cli])
+
+      if session
+        path = session["events_log_path"].to_s
+        path = Harnex.events_log_path(repo_root, @options[:id]) if path.empty?
+        return event_target(path, live: true, repo_root: repo_root)
+      end
+
+      if cli_filter_mismatch?(repo_root)
+        warn("harnex events: no active session found with id #{@options[:id].inspect} and cli #{@options[:cli].inspect}")
+        return nil
+      end
+
+      event_target(Harnex.events_log_path(repo_root, @options[:id]), live: false, repo_root: repo_root)
+    end
+
+    def cli_filter_mismatch?(repo_root)
+      return false unless @options[:cli]
+
+      session = Harnex.read_registry(repo_root, @options[:id])
+      return false unless session
+
+      Harnex.cli_key(Harnex.session_cli(session)) != Harnex.cli_key(@options[:cli])
+    end
+
+    def event_target(path, live:, repo_root:)
+      return { path: path, live: live, repo_root: repo_root } if File.file?(path)
+
+      if live
+        warn("harnex events: stream not found at #{path}")
+      else
+        warn("harnex events: no session or event stream found with id #{@options[:id].inspect} for #{repo_root}")
+      end
+      nil
+    end
+
+    def print_snapshot(path)
+      offset = 0
+      File.open(path, "rb") do |file|
+        file.each_line do |line|
+          next unless emit_line?(line)
+
+          $stdout.write(line)
+        end
+        offset = file.pos
+      end
+      $stdout.flush
+      offset
+    end
+
+    def follow(path, offset)
+      current_offset = offset
+
+      loop do
+        streamed = stream_growth(path, current_offset)
+        return streamed.fetch(:code) if streamed[:code]
+
+        current_offset = streamed.fetch(:offset)
+        sleep POLL_INTERVAL
+      end
+    end
+
+    def stream_growth(path, offset)
+      unless File.file?(path)
+        warn("harnex events: stream source disappeared at #{path}")
+        return { code: 1, offset: offset }
+      end
+
+      size = File.size(path)
+      if size < offset
+        warn("harnex events: stream source was truncated at #{path}")
+        return { code: 1, offset: size }
+      end
+      return { offset: offset } if size == offset
+
+      chunk = +""
+      File.open(path, "rb") do |file|
+        file.seek(offset)
+        chunk = file.read(size - offset).to_s
+      end
+
+      @tail_buffer << chunk
+      lines = @tail_buffer.split("\n", -1)
+      @tail_buffer = lines.pop || +""
+      wrote = false
+
+      lines.each do |line|
+        json_line = "#{line}\n"
+        event = parse_event(json_line)
+        if emit_line?(json_line, parsed: event)
+          $stdout.write(json_line)
+          wrote = true
+        end
+        return { code: 0, offset: size } if target_exited?(event)
+      end
+
+      $stdout.flush if wrote
+      { offset: size }
+    end
+
+    def emit_line?(line, parsed: nil)
+      return true unless @options[:from]
+
+      event = parsed || parse_event(line)
+      return false unless event
+
+      timestamp = event_timestamp(event)
+      return false unless timestamp
+
+      timestamp >= @options[:from]
+    end
+
+    def parse_event(line)
+      JSON.parse(line)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def event_timestamp(event)
+      value = event["ts"].to_s
+      return nil if value.empty?
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def target_exited?(event)
+      return false unless event
+      return false unless event["type"] == "exited"
+
+      Harnex.id_key(event["id"].to_s) == Harnex.id_key(@options[:id])
+    end
+  end
+end

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

data/lib/harnex/runtime/session.rb

@@ -6,7 +6,7 @@ module Harnex
   class Session
     OUTPUT_BUFFER_LIMIT = 64 * 1024
 
-    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, :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)
       @adapter = adapter
@@ -19,17 +19,21 @@ module Harnex
       @description = nil if @description.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
       @writer = nil
       @pid = nil
       @term_signal = nil
@@ -60,8 +64,10 @@ 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_event("started", pid: @pid)
 
       install_signal_handlers
       sync_window_size
@@ -78,6 +84,7 @@ module Harnex
       _, status = Process.wait2(pid)
       @term_signal = status.signaled? ? status.termsig : nil
       @exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
+      emit_exit_event
 
       output_thread.join(1)
       input_thread&.kill
@@ -91,6 +98,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 +117,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 +178,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 +338,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 +383,60 @@ 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_exit_event
+      payload = { code: @exit_code }
+      payload[:signal] = @term_signal if @term_signal
+      emit_event("exited", **payload)
+    end
+
+    def emit_event(type, **payload)
+      @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.4.0"
+  RELEASE_DATE = "2026-04-30"
 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.4.0
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-24 00:00:00.000000000 Z
+date: 2026-04-29 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