harnex 0.3.3 → 0.4.0

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.3"
-  RELEASE_DATE = "2026-04-23"
+  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/SKILL.md

@@ -1,348 +1,20 @@
 ---
 name: harnex
-description: Collaborate with other AI agents (Codex, Claude) via harnex. Use when the user asks to send a message to another agent, check agent sessions, spawn workers, relay instructions, or coordinate multi-agent work. Also activates when incoming messages contain "[harnex relay" headers.
-allowed-tools: Bash(harnex *)
+description: Deprecated alias for harnex-dispatch. Use harnex-dispatch for active harnex collaboration guidance.
 ---
 
-# Harnex — Cross-Agent Collaboration
+# Deprecated Skill Alias
 
-If this is your first time using harnex, run `harnex guide` for the full
-getting started walkthrough, and `harnex recipes` for tested workflow patterns.
+`harnex` is deprecated.
 
-Harnex wraps interactive terminal agents (Claude Code, Codex) and opens a local
-control plane so they can discover and message each other. You use it to **send
-messages to a peer agent**, **check session status**, **spawn worker sessions**,
-and **wait for them to finish**.
+Use `harnex-dispatch` as the canonical skill for harnex collaboration,
+Fire & Watch dispatching, relay handling, and return-channel discipline.
 
-## Detect your context
-
-Check environment variables to understand your role:
-
-| Variable | Meaning |
-|----------|---------|
-| `HARNEX_SESSION_CLI` | Which CLI you are (`claude` or `codex`) |
-| `HARNEX_ID` | Your session ID |
-| `HARNEX_SESSION_REPO_ROOT` | Repo root this session is scoped to |
-| `HARNEX_SESSION_ID` | Internal instance identifier |
-| `HARNEX_SPAWNER_PANE` | Tmux pane ID (`%N`) of whoever spawned this session |
-
-If these are set, you are **inside a harnex session** and can send messages to
-peer sessions or spawn new worker sessions.
-
-`HARNEX_SPAWNER_PANE` is the stable tmux pane ID of the invoker — use it to
-reach back to the session that launched you, even if that session is not
-harnex-managed:
-
-```bash
-# Read the invoker's screen
-tmux capture-pane -t "$HARNEX_SPAWNER_PANE" -p
-
-# Type into the invoker
-tmux send-keys -t "$HARNEX_SPAWNER_PANE" "done — results in /tmp/result.md" Enter
-```
-
-## Mode preference
-
-When starting another agent session for the user, default to a visible tmux
-session via `harnex run <cli> --tmux`. That is the preferred interactive mode
-because the user can watch the peer's work live.
-
-Use other modes only when the user asks for them or when visibility is not
-wanted:
-
-- prefer `--tmux` over a hidden foreground PTY for peer-agent work
-- use plain foreground `harnex run` only when the current terminal is meant to
-  become that peer's UI
-- use `--detach` only for explicitly headless/background workflows
-
-## Return channel first
-
-Before you start a peer session or send it work, decide how the result will get
-back to you.
-
-Preferred pattern when you are inside harnex:
-- Use your own `HARNEX_ID` as the return address
-- Tell the peer to send its final result back with `harnex send --id <YOUR_ID>`
-- Wait for the peer's reply; do not rely on scraping logs or tmux panes as the
-  primary way to collect the answer
-
-Fallback when you are not inside harnex:
-- Define another explicit return channel before delegating, such as a known file
-  path in the repo
-
-Do not launch a worker/reviewer without an explicit completion contract.
-
-## Two rules for every send
-
-**1. Keep messages short — use file references for long prompts.**
-Long inline prompts can stall delivery (PTY buffer limits) and break shell
-quoting. Instead, write the full task to a file and tell the peer to read it:
-
-```bash
-# Write the task to a file
-cat > /tmp/task-impl1.md <<'EOF'
-Implement phase 2 from koder/plans/03_output_streaming.md.
-... detailed instructions ...
-EOF
-
-# Send a short message pointing to it
-harnex send --id impl-1 --message "Read and execute /tmp/task-impl1.md. When done, send results back: harnex send --id $HARNEX_ID --message '<summary>'"
-```
-
-If the task is already written down (a plan file, issue, koder doc), just
-reference it directly — no need for a temp file.
-
-**2. Always tell the peer how to reply.**
-Every delegated task must include a return path. Without it, the peer finishes
-silently and you have no way to collect the result:
-
-```bash
-# Always end with the reply instruction
-harnex send --id impl-1 --message "Review src/auth.rb. When done: harnex send --id $HARNEX_ID --message '<your findings>'"
-```
-
-## Core commands
-
-### Send a message to a peer agent
-
-```bash
-harnex send --id <ID> --message "<text>"
-```
-
-- `--id` targets a specific session by its unique ID
-- `--message` is the prompt text injected into the peer's terminal
-- Message is auto-submitted (peer receives it as a prompt)
-- `--no-submit` types without pressing Enter
-- `--force` sends even if peer UI is not at a prompt (bypasses queue)
-- `--submit-only` sends only Enter (submit what's already in the input box)
-- `--wait-for-idle` blocks until the agent finishes processing (prompt→busy→prompt)
-- `--no-wait` returns immediately with a message_id (don't wait for delivery)
-- `--cli` filters by CLI type when multiple sessions share resolution scope
-
-When the target agent is busy, the message is **queued** (HTTP 202) and
-delivered automatically when the agent returns to a prompt. The sender polls
-until delivery completes using one overall `--timeout` budget (default 120s).
-
-### Atomic send+wait (recommended for orchestration)
-
-Use `--wait-for-idle` instead of separate `send` + `sleep` + `wait` commands:
+If you are installing skills, use:
 
 ```bash
-# Instead of:
-harnex send --id cx-1 --message "implement the plan"
-sleep 5
-harnex wait --id cx-1 --until prompt --timeout 600
-
-# Use:
-harnex send --id cx-1 --message "implement the plan" --wait-for-idle --timeout 600
-```
-
-This eliminates the race condition where `wait --until prompt` sees the stale
-prompt state before the agent starts working. The `--timeout` budget covers
-the entire lifecycle (lookup + send + idle wait).
-
-**Multi-line messages** (when a file reference isn't practical): use a heredoc:
-
-```bash
-harnex send --id worker-1 --message "$(cat <<'EOF'
-Line one of the message.
-Line two of the message.
-EOF
-)"
-```
-
-### Check session status
-
-```bash
-harnex status            # sessions for current repo
-harnex status --all      # sessions across all repos
-```
-
-Shows live sessions with their ID, CLI, port, PID, age, and input state.
-
-### Inspect a specific session
-
-```bash
-harnex status --id <ID> --json
-```
-
-Returns JSON with input state, agent state, inbox stats, description,
-watch config, and timestamps.
-
-### Only when explicitly requested: spawn a detached worker session
-
-```bash
-# Headless (no terminal)
-harnex run codex --id impl-1 --detach -- --cd /path/to/worktree
-
-# In a tmux window (observable)
-harnex run codex --id impl-1 --tmux cx-p1 -- --cd /path/to/worktree
+harnex skills install harnex-dispatch
 ```
 
-- `--detach` starts the session in the background, returns JSON with pid/port
-- `--tmux` creates a tmux window (implies `--detach`)
-- `--tmux NAME` sets a custom window title (keep names terse: `cx-p3`, `cl-r3`)
-- `--context TEXT` sets an initial prompt with session ID auto-included
-- `--description TEXT` stores a short session description in the registry/API
-- Returns immediately; use `harnex send` to inject work, `harnex wait` to block
-
-Do this only if the user explicitly asks for detached/background execution.
-
-#### Using `--context` to orient spawned agents
-
-`--context` prepends a context string as the agent's initial prompt, with the
-session ID automatically included as `[harnex session id=<ID>]`. The spawner
-decides what context to provide — harnex only adds the session ID.
-
-```bash
-# Fire-and-forget: give the task upfront
-harnex run codex --id impl-1 --tmux cx-p1 \
-  --context "Implement the feature in koder/plans/03_auth.md. Commit when done." \
-  -- --cd /path/to/worktree
-
-# Fire-and-wait: give context, then send work separately
-harnex run codex --id reviewer --tmux cx-rv \
-  --context "You are a code reviewer. Wait for instructions via harnex relay messages." \
-  -- --cd /path/to/repo
-harnex send --id reviewer --message "Review the changes in src/auth.rb"
-harnex wait --id reviewer
-```
-
-The context string is the spawner's responsibility — tailor it to the use case.
-
-### Wait for a session to exit
-
-```bash
-harnex wait --id impl-1
-harnex wait --id impl-1 --timeout 300
-```
-
-Blocks until the session process exits. Returns JSON with exit code and timing.
-Exit code 124 on timeout.
-
-## Relay headers
-
-When you send from inside a harnex session to a **different** session, harnex
-automatically prepends a relay header:
-
-```
-[harnex relay from=claude id=supervisor at=2026-03-14T12:00:00+04:00]
-<your message>
-```
-
-The peer sees this header and knows the message came from another agent. When
-you **receive** a message with a `[harnex relay ...]` header, treat it as a
-prompt from the peer agent — read the body and respond to it.
-
-Control relay behavior:
-- `--relay` forces the header even outside a session
-- `--no-relay` suppresses the header
-
-## Collaboration patterns
-
-### Reply to a peer
-
-When the user (or a relay message) asks you to reply to the other agent:
-
-```bash
-harnex send --id <TARGET_ID> --message "Your response here"
-```
-
-### Delegate work and get the answer back
-
-When you ask a peer agent to do work, include the return path in the task
-itself.
-
-Preferred when you are inside harnex:
-
-```bash
-harnex send --id reviewer --message "$(cat <<EOF
-Review the current working tree.
-
-Return your final findings to me with:
-harnex send --id $HARNEX_ID --message '<findings>'
-
-Use findings-first format with file paths and line numbers where possible.
-EOF
-)"
-```
-
-Then wait for the peer to answer you. Do not assume you can reconstruct the
-result later from detached logs or tmux capture.
-
-### Supervisor pattern
-
-Use this only when the user explicitly wants detached/background workers.
-
-A supervisor session spawns workers, sends them tasks, and waits for completion:
-
-```bash
-# Spawn workers
-harnex run codex --id impl-1 --tmux cx-p1 -- --cd ~/repo/wt-feature-a
-harnex run codex --id impl-2 --tmux cx-p2 -- --cd ~/repo/wt-feature-b
-
-# Send work and wait for completion (atomic)
-harnex send --id impl-1 --message "implement plan 150" --wait-for-idle --timeout 600
-harnex send --id impl-2 --message "implement plan 151" --wait-for-idle --timeout 600
-
-# Review phase
-harnex run claude --id review-1 --tmux cl-r1
-harnex send --id review-1 --message "review changes in wt-feature-a"
-harnex wait --id review-1
-```
-
-### File watch hook
-
-Sessions can watch a shared file (e.g. `--watch ./tmp/tick.jsonl`). When the
-file changes, harnex injects a `file-change-hook: read <path>` message. If you
-receive this hook, read the file and act on its contents.
-
-## Buddy pattern — accountability for long-running work
-
-For any work that will take a long time (overnight pipelines, multi-hour
-implementations, unattended batch jobs), spawn a **buddy** — a second harnex
-session that watches the worker and nudges it if it stalls.
-
-```bash
-# Spawn the worker
-harnex run codex --id worker-42 --tmux worker-42
-harnex send --id worker-42 --message "Read and execute /tmp/task-42.md"
-
-# Spawn a buddy to watch it
-harnex run claude --id buddy-42 --tmux buddy-42
-harnex send --id buddy-42 --message "Read and execute /tmp/buddy-42.md"
-```
-
-The buddy's prompt tells it: poll `harnex pane` and `harnex status` every N
-minutes, nudge with `harnex send` if the worker stalls, report back to
-`$HARNEX_SPAWNER_PANE` when done.
-
-See `recipes/03_buddy.md` for the full pattern.
-
-**When to spawn a buddy:**
-- The user says "do this overnight" or "run this while I'm away"
-- The task is expected to take more than 30 minutes unattended
-- The user explicitly asks for a buddy or accountability partner
-
-**When NOT to spawn a buddy:**
-- Short tasks you're actively watching
-- The user hasn't asked for long-running autonomy
-
-## Important rules
-
-1. **Always confirm with the user before sending** unless they explicitly asked
-   you to send a specific message. Sending injects a prompt into the peer's
-   terminal — it's an action visible to others.
-2. **Never auto-loop** relay conversations. One send per user request unless
-   told otherwise.
-3. **Check status first** if unsure whether a peer is running: `harnex status`
-4. **Use `--force` sparingly** — it bypasses the inbox queue and adapter
-   readiness checks. Can corrupt peer input if it's mid-response.
-5. **Relay headers are automatic** when sending from inside a session. Don't
-   manually prepend them.
-6. When composing a message to send, be concise and actionable — the peer agent
-   receives it as a prompt and will act on it.
-7. Do not spawn detached or tmux-backed sessions unless the user explicitly
-   asked for detached/background execution.
-8. Before delegating work, define the result return path. Prefer a reply back to
-   your own `HARNEX_ID` over logs, pane capture, or other indirect collection.
+Compatibility note: `harnex skills install harnex` remains supported and
+installs `harnex-dispatch`.

data/skills/harnex-buddy/SKILL.md

@@ -8,9 +8,17 @@ 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.
 
+Dispatch workers via `harnex-dispatch` first. This skill owns only buddy
+behavior after the worker is already running.
+
 ## When to activate
 
 - User says "do this overnight" or "run this while I'm away"
@@ -20,12 +28,11 @@ screen, reasons about whether it's stuck, and composes a meaningful nudge.
 
 ## Spawn the buddy
 
-After dispatching the worker, spawn a buddy alongside it:
+After dispatching the worker with `harnex-dispatch`, spawn a buddy alongside
+it. Keep ID/tmux naming consistent with `harnex-dispatch` (`--tmux` matches
+`--id`):
 
 ```bash
-# Worker already running
-harnex run codex --id worker-42 --tmux worker-42
-
 # Spawn its buddy
 harnex run claude --id buddy-42 --tmux buddy-42
 ```
@@ -36,17 +43,17 @@ Write a task file with the watching instructions, then send it:
 
 ```bash
 cat > /tmp/buddy-42.md <<'EOF'
-You are an accountability partner for harnex session `worker-42`.
+You are an accountability partner for harnex session `cx-impl-42`.
 
 Your job:
 1. Every 5 minutes, check on the worker:
-   - `harnex pane --id worker-42 --lines 30`
-   - `harnex status --id worker-42 --json`
+   - `harnex pane --id cx-impl-42 --lines 20`
+   - `harnex status --id cx-impl-42 --json`
 2. If the worker appears stuck at a prompt for more than 10 minutes
    with no progress, nudge it:
-   - `harnex send --id worker-42 --message "You appear to have stalled. Continue with your current task."`
+   - `harnex send --id cx-impl-42 --message "You appear to have stalled. Continue with your current task."`
 3. If the worker has exited, report back to the invoker:
-   - `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 has exited. Check results." Enter`
+   - `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "cx-impl-42 has exited. Check results." Enter`
 4. Keep watching until the worker finishes or is stopped.
 
 Do not interfere with work in progress. Only nudge when clearly stalled.
@@ -76,12 +83,8 @@ The invoker does NOT need to be a harnex session. It just needs to be in tmux.
 
 ## Naming convention
 
-| Role | ID pattern | Example |
-|------|-----------|---------|
-| Worker | `worker-NN` | `worker-42` |
-| Buddy | `buddy-NN` | `buddy-42` |
-
-Match the buddy ID to the worker it watches.
+Use naming from `harnex-dispatch`: set `--tmux <same-as-id>` for every
+session and keep the buddy ID paired with the worker step ID.
 
 ## Cleanup
 
@@ -93,6 +96,8 @@ harnex stop --id buddy-42
 
 ## Notes
 
+- For chain orchestration, phase gates, and the 5-concurrent parallel planning
+  cap, see `harnex-chain`.
 - One buddy per worker, or one buddy watching multiple sessions
 - The buddy is a regular harnex session — stop, inspect, log it like any other
 - Tune polling and thresholds in the buddy's prompt, not in harnex config