harnex 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c56e3cb64f20e24e32b7f46c4be98b23715407f5f990f79ba1b702720a5130b
-  data.tar.gz: 1c88ad05842287252453878522baba77db4b8388fa6166d3ef7eaf8127b0eaa1
+  metadata.gz: e4d7c194ba2ba10ee075e6e53aa3eaf291cbfc08eca1d89cd291955834230c01
+  data.tar.gz: e3bafc087ae74a484be3ee121cce0d8f351c6b381ce244d5da032e48c85da4db
 SHA512:
-  metadata.gz: 281b2f232bddcaf24d391a68fc331c73f7d43809d2f40d18848e417da9e50b999c330105a474f99ffa080528ccbeb6139da31c785604cffaab6ce76f4fe16584
-  data.tar.gz: 4e36010a2d17c5541e95c75179941b9fa282d2093237aabd0d1748d5b5c5c374eb4e67852d1d06b674ab039cdc7106c8f71de9bf64b9a99a737ec6e861b58fc6
+  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)
@@ -503,19 +559,21 @@ and `Inbox` classes use `ConditionVariable` for signaling.
 
 ## Skill Files
 
-Harnex ships a skill file that teaches AI agents how to use
-harnex commands. The file lives at:
+Harnex ships bundled skills that teach agents the orchestration workflow and
+dispatch discipline. The canonical collaboration skill is:
 
 ```
-skills/harnex/SKILL.md
+skills/harnex-dispatch/SKILL.md
 ```
 
 ### What's in the skill
 
-The skill tells agents:
+The dispatch skill tells agents:
 
 - How to detect they're inside a harnex session (env vars)
-- How to send messages, check status, spawn workers
+- How to define return channels before delegation
+- How to send short, file-referenced tasks with explicit reply instructions
+- How to send messages, check status, spawn workers, and stop safely
 - How to use `--context`, `--force`, `--no-wait`
 - Relay header format and behavior
 - Collaboration patterns (reply, supervisor, file watch)
@@ -531,8 +589,8 @@ Skill files use YAML frontmatter:
 
 ```yaml
 ---
-name: harnex
-description: Collaborate with other AI agents...
+name: harnex-dispatch
+description: Fire & Watch dispatch pattern...
 allowed-tools: Bash(harnex *)
 ---
 ```
@@ -540,41 +598,36 @@ allowed-tools: Bash(harnex *)
 The `allowed-tools` field grants the agent permission to run
 `harnex` commands without asking for approval each time.
 
-### Symlinking the skill
+### Installing bundled skills
 
-To make the skill available globally (not just in the harnex
-repo), symlink it into each agent's skill directory:
+Use the installer command instead of manual symlinks:
 
 ```bash
-# For Claude Code
-ln -s /path/to/harnex/skills/harnex \
-      ~/.claude/skills/harnex
-
-# For Codex
-ln -s /path/to/harnex/skills/harnex \
-      ~/.codex/skills/harnex
+harnex skills install            # all canonical skills
+harnex skills install harnex     # compatibility alias -> harnex-dispatch
+harnex skills install --local    # install into current repo only
 ```
 
-After symlinking, any Claude or Codex session — in any repo —
-can use harnex commands. The skill activates automatically
-when the user mentions agent collaboration or when a relay
-message arrives.
+Compatibility aliases accepted by the installer:
+
+- `harnex` -> `harnex-dispatch`
+- `dispatch` -> `harnex-dispatch`
+- `chain-implement` -> `harnex-chain`
 
 ### Skill directory structure
 
 ```
  ~/.claude/skills/
-   └── harnex -> /path/to/harnex/skills/harnex
+   └── harnex-dispatch
          └── SKILL.md
 
  ~/.codex/skills/
-   └── harnex -> /path/to/harnex/skills/harnex
+   └── harnex-dispatch -> ~/.claude/skills/harnex-dispatch
          └── SKILL.md
 ```
 
-The symlink points to the `skills/harnex/` directory (not the
-file directly), so updates to `SKILL.md` in the repo are
-picked up immediately.
+Deprecated installed names (`harnex`, `dispatch`, `chain-implement`) are
+cleaned automatically during install and uninstall.
 
 ## Known Limitations
 

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