harnex 0.3.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5db22a80eebc5f0441437c96a2f949f0dd117cf78a2cc0810f24172c7af7cd4
-  data.tar.gz: 3ad9ed119b373258b1e8c56ea80b27ea49dad028031e19bd4ee0697996a45046
+  metadata.gz: 2b38fbca70a1ec608f414f362bb16bff85bdb5c279a5c562c4dc7048fa6acb41
+  data.tar.gz: 7a9048de3efb9461489ab0678683e0d245e60e2ac3a1dd7e617d868fce927a51
 SHA512:
-  metadata.gz: 1dd3ad5ef1cf5bb17d6a92ea6b27b746ef47a8e1a8e58b1e2a98936946f63f58d8d297d7493ffc3ab3968e25ac26415ae73c44524423a83f36c5951b4e729813
-  data.tar.gz: 39cf0ed49b278a10ff57767d6cc166232e7c30ca9eed31853d079a2a437dcd0ee4709a8a13959e91bd106d8ce7b1e1b043b64a6df0fd24988a925266c488769a
+  metadata.gz: a222bd5df7a1e02e7b6cebb2e0a63649b4433baef17be35a3dd03b4128e9b406af52ae71e9c063a6912dbb9af04b187072a693271fb72f24e4d61de462a7bf1c
+  data.tar.gz: eb2ca6564d079b0e162e72e9d07d01239ba2ce0c5b118fbd4360671d555c452571b2c64cb0f5a4be3c0b23c13e57b606d7ca98632d345f7570d5c69caacc9ad8

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/adapters/base.rb

@@ -39,6 +39,10 @@ module Harnex
         }
       end
 
+      def parse_session_summary(_transcript_tail)
+        {}
+      end
+
       def send_wait_seconds(submit:, enter_only:)
         0.0
       end

data/lib/harnex/adapters/codex.rb

@@ -56,6 +56,25 @@ module Harnex
         end
       end
 
+      def parse_session_summary(transcript_tail)
+        summary = empty_session_summary
+        text = transcript_tail.to_s
+
+        if (match = text.match(/Token usage:\s+total=([\d,]+)\s+input=([\d,]+)(?:\s+\(\+\s+([\d,]+)\s+cached\))?\s+output=([\d,]+)(?:\s+\(reasoning\s+([\d,]+)\))?/))
+          summary[:total_tokens] = parse_token_count(match[1])
+          summary[:input_tokens] = parse_token_count(match[2])
+          summary[:cached_tokens] = parse_token_count(match[3])
+          summary[:output_tokens] = parse_token_count(match[4])
+          summary[:reasoning_tokens] = parse_token_count(match[5])
+        end
+
+        if (match = text.match(/codex resume\s+([0-9a-f-]{36})/))
+          summary[:agent_session_id] = match[1]
+        end
+
+        summary
+      end
+
       def send_wait_seconds(submit:, enter_only:)
         return 0.0 unless submit
         return 0.0 if enter_only
@@ -101,6 +120,23 @@ module Harnex
 
       protected
 
+      def empty_session_summary
+        {
+          input_tokens: nil,
+          output_tokens: nil,
+          reasoning_tokens: nil,
+          cached_tokens: nil,
+          total_tokens: nil,
+          agent_session_id: nil
+        }
+      end
+
+      def parse_token_count(value)
+        return nil if value.nil?
+
+        Integer(value.delete(","))
+      end
+
       def submit_delay_ms(text)
         extra = (text.to_s.bytesize / 1024.0 * SUBMIT_DELAY_PER_KB_MS).ceil
         SUBMIT_DELAY_MS + extra

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