harnex 0.2.3 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ef69aafbfe0af98bf7e56fe9dfc0a8c320095a44bea1d682a5c582f9b6569f6
-  data.tar.gz: 9a3ac05697910d91beeb66f7abd463ad2b51c2e9355d5ddc6a60a8687a66472d
+  metadata.gz: 3c56e3cb64f20e24e32b7f46c4be98b23715407f5f990f79ba1b702720a5130b
+  data.tar.gz: 1c88ad05842287252453878522baba77db4b8388fa6166d3ef7eaf8127b0eaa1
 SHA512:
-  metadata.gz: 00315bc8e09e631799a76ce8a3569f8ff4ed512cd62cae5b9cf8ac9092c173f5636893ffe2cfd8ee0ed06305509dba240d0272489d1949c3b7f141268f8f0043
-  data.tar.gz: 0e3425f79503c76e7d0e09edad5782efc784806cdc93cc096071be851782e27f73bf8a0ca7704330f9d45f86a0cc9684262da230650078152e556e4017888d93
+  metadata.gz: 281b2f232bddcaf24d391a68fc331c73f7d43809d2f40d18848e417da9e50b999c330105a474f99ffa080528ccbeb6139da31c785604cffaab6ce76f4fe16584
+  data.tar.gz: 4e36010a2d17c5541e95c75179941b9fa282d2093237aabd0d1748d5b5c5c374eb4e67852d1d06b674ab039cdc7106c8f71de9bf64b9a99a737ec6e861b58fc6

data/GUIDE.md

@@ -161,9 +161,18 @@ After the worker finishes, inspect the screen:
 harnex pane --id review --lines 60
 ```
 
-Optional: if you're inside a harnex-managed session yourself and
-really want a callback, you can still use `$HARNEX_ID` as the return
-address. Treat that as secondary, not the main control flow.
+**Return channel for any tmux pane:** Every spawned session gets
+`$HARNEX_SPAWNER_PANE` — the tmux pane ID of whoever ran `harnex run`.
+The spawned agent can report back via `tmux send-keys`, even if the
+invoker isn't a harnex session:
+
+```bash
+tmux send-keys -t "$HARNEX_SPAWNER_PANE" "done — results in /tmp/result.md" Enter
+```
+
+If you're inside a harnex-managed session, you can also use
+`$HARNEX_ID` as the return address with `harnex send`. But file
+handoffs remain the preferred primary control flow.
 
 ## Stopping agents
 
@@ -205,21 +214,21 @@ an updated summary. Then review again with a fresh Claude instance.
 
 ## Teaching your agents about harnex
 
-Harnex ships a skill file that tells AI agents how to use harnex
-commands. To make it available globally:
+Harnex ships skill files that tell AI agents how to use harnex
+commands. Install them globally so every session picks them up:
 
 ```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
 ```
 
-After this, any Claude or Codex session — in any repo — can use
-harnex commands without being taught how. The skill activates
+This copies the bundled skills (harnex-dispatch, harnex-chain,
+harnex-buddy) to `~/.claude/skills/` and symlinks `~/.codex/skills/`
+to them. After this, any Claude or Codex session — in any repo — can
+use harnex commands without being taught how. The skills activate
 automatically when agent collaboration is needed.
 
+For repo-local installs instead, use `--local`.
+
 ## Recipes
 
 Tested workflows for common multi-agent patterns. Read them
@@ -235,6 +244,9 @@ harnex recipes show 01     # read one
 - **Chain Implement** (`harnex recipes show 02`) — process a
   batch as repeated fire-and-watch: Codex plan/implement,
   Claude review, Codex fix, then review again if needed.
+- **Buddy** (`harnex recipes show 03`) — spawn an accountability
+  partner for overnight or long-running work. The buddy polls the
+  worker's screen and nudges it if it stalls.
 
 ## What's next
 

data/README.md

@@ -18,8 +18,8 @@ Then install workflow skills into your repo so agents can use them:
 harnex skills install
 ```
 
-This adds orchestration skills (dispatch, chain-implement) that Claude
-Code and Codex pick up automatically.
+This adds orchestration skills (harnex-dispatch, harnex-chain, harnex-buddy)
+that Claude Code and Codex pick up automatically.
 
 ## What it does
 
@@ -92,17 +92,78 @@ harnex stop --id cl-review
 
 Harnex ships workflow skills that automate this pattern:
 
-- **[Dispatch](skills/dispatch/SKILL.md)** — the fire-and-watch pattern:
+- **[Dispatch](skills/harnex-dispatch/SKILL.md)** — the fire-and-watch pattern:
   spawn an agent, poll its screen, stop it when done
-- **[Chain Implement](skills/chain-implement/SKILL.md)** — end-to-end
-  issue-to-code workflow: plan, review plan, implement, review code, fix
+- **[Chain](skills/harnex-chain/SKILL.md)** — end-to-end issue-to-code
+  workflow: plan, review plan, implement, review code, fix
+- **[Buddy](skills/harnex-buddy/SKILL.md)** — spawn an accountability partner
+  for long-running or overnight work
 
-Install skills into your repo so agents can use them:
+Install skills so agents can use them:
 
 ```bash
 harnex skills install
 ```
 
+## 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.
+
+### Example: keep a worker from stalling
+
+Spawn a buddy alongside a long-running implementation worker:
+
+```bash
+harnex run codex --id worker-42 --tmux
+harnex run claude --id buddy-42 --tmux
+harnex send --id buddy-42 --message "$(cat <<'EOF'
+Watch harnex session worker-42.
+Every 5 minutes: run `harnex pane --id worker-42 --lines 30`.
+If it looks stuck at a prompt with no progress for 10+ minutes,
+nudge it: `harnex send --id worker-42 --message "Continue your task."`.
+When it exits, report back:
+  tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 done" Enter
+EOF
+"
+```
+
+### Example: watch for doc drift during implementation
+
+A buddy that checks whether a worker's code changes have left
+docs out of date:
+
+```bash
+harnex run codex --id worker-99 --tmux
+harnex run claude --id buddy-99 --tmux
+harnex send --id buddy-99 --message "$(cat <<'EOF'
+Watch harnex session worker-99.
+Every 5 minutes: run `harnex pane --id worker-99 --lines 30`.
+When the worker goes idle after making changes, run `git diff --name-only`
+and check whether any changed code has corresponding docs (README, GUIDE,
+inline comments) that are now stale. If so, nudge the worker:
+  harnex send --id worker-99 --message "Docs may be stale — check README
+  sections related to <specific area>."
+When the worker exits, report a summary to the invoker:
+  tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-99 done. Doc drift: <yes/no>" Enter
+EOF
+"
+```
+
+### The invoker doesn't need to be a harnex session
+
+Every spawned session gets `$HARNEX_SPAWNER_PANE` — the tmux pane ID
+of whoever ran `harnex run`. The buddy can report back to a plain
+Claude Code session, a Codex session, or any tmux pane:
+
+```bash
+tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 finished" Enter
+```
+
+See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
+
 ## All commands
 
 | Command | What it does |
@@ -117,6 +178,17 @@ harnex skills install
 | `harnex guide` | Getting started walkthrough |
 | `harnex recipes` | Tested workflow patterns |
 | `harnex skills install` | Install bundled skills for Claude/Codex |
+| `harnex skills uninstall` | Remove installed skills |
+
+## Uninstalling
+
+```bash
+harnex skills uninstall   # remove skills from ~/.claude/ and ~/.codex/
+gem uninstall harnex
+```
+
+Run `harnex skills uninstall` before removing the gem — installed skills
+persist in `~/.claude/skills/` and won't be cleaned up by `gem uninstall`.
 
 ## Going deeper
 

data/bin/gem-push

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+GEM_FILE="${1:?Usage: bin/gem-push <gemfile>}"
+ENV_FILE="$(dirname "$0")/../.env"
+
+if [[ ! -f "$ENV_FILE" ]]; then
+  echo "Error: .env not found" >&2
+  exit 1
+fi
+
+KEY=$(grep '^RUBYGEMS_TOTP_KEY=' "$ENV_FILE" | cut -d'"' -f2)
+
+if [[ -z "$KEY" ]]; then
+  echo "Error: RUBYGEMS_TOTP_KEY not found in .env" >&2
+  exit 1
+fi
+
+OTP=$(echo "$KEY" | otp)
+gem push "$GEM_FILE" --otp "$OTP"

data/lib/harnex/adapters/base.rb

@@ -124,8 +124,9 @@ module Harnex
       end
 
       def normalized_screen_text(screen_text)
-        text = screen_text.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "")
+        text = screen_text.to_s.dup.force_encoding(Encoding::UTF_8).scrub("")
         text = text.gsub(/\e\][^\a]*?(?:\a|\e\\)/, "")
+        text = text.gsub(/\e\[\d*(?:;1)?H/, "\n")
         text = text.gsub(/\e(?:[@-Z\\-_]|\[[0-?]*[ -\/]*[@-~])/, "")
         text.gsub(/\r\n?/, "\n")
       end

data/lib/harnex/adapters/codex.rb

@@ -7,6 +7,7 @@ module Harnex
 
       def initialize(extra_args = [])
         super("codex", extra_args)
+        @banner_seen = false
       end
 
       def base_command
@@ -37,7 +38,10 @@ module Harnex
 
       def input_state(screen_text)
         lines = recent_lines(screen_text)
-        return super unless lines.any? { |line| line.include?("OpenAI Codex") || line.include?("gpt-") }
+        if lines.any? { |line| line.include?("OpenAI Codex") || line.include?("gpt-") }
+          @banner_seen = true
+        end
+        return super unless @banner_seen
 
         if lines.any? { |line| prompt_line?(line) }
           {

data/lib/harnex/cli.rb

@@ -32,6 +32,9 @@ module Harnex
       when "help"
         puts help(@argv[1])
         0
+      when "-v", "--version", "version"
+        puts "harnex #{Harnex::VERSION} (#{Harnex::RELEASE_DATE})"
+        0
       when "-h", "--help"
         puts usage
         0

data/lib/harnex/commands/run.rb

@@ -340,6 +340,7 @@ module Harnex
     def tmux_name_arg?(argv, index, cli_name)
       value = argv[index + 1]
       return false if value.nil? || value == "--" || wrapper_option_token?(value)
+      return false if value.start_with?("--")
       return true if cli_name
 
       cli_candidate_after?(argv, index + 2)

data/lib/harnex/commands/skills.rb

@@ -3,17 +3,19 @@ require "fileutils"
 module Harnex
   class Skills
     SKILLS_ROOT = File.expand_path("../../../../skills", __FILE__)
-    INSTALL_SKILLS = %w[dispatch chain-implement].freeze
+    INSTALL_SKILLS = %w[harnex-dispatch harnex-chain harnex-buddy].freeze
+    DEPRECATED_SKILLS = %w[dispatch chain-implement].freeze
 
     def self.usage
       <<~TEXT
-        Usage: harnex skills install [--local]
+        Usage: harnex skills <subcommand> [--local]
 
         Subcommands:
           install     Install bundled skills (globally by default)
+          uninstall   Remove installed skills (globally by default)
 
         Options:
-          --local     Install to the current repo instead of globally
+          --local     Target the current repo instead of global ~/.claude/
 
         Installs: #{INSTALL_SKILLS.join(', ')}
 
@@ -33,13 +35,12 @@ module Harnex
       subcommand = @argv.shift
       case subcommand
       when "install"
-        skill_names, local, help = parse_install_args(@argv)
-        if help
-          puts self.class.usage
-          return 0
-        end
+        local, help = parse_args(@argv)
+        return (puts self.class.usage; 0) if help
+
+        remove_deprecated(local)
 
-        skill_names.each do |skill_name|
+        INSTALL_SKILLS.each do |skill_name|
           skill_source = resolve_skill_source(skill_name)
           unless skill_source
             return missing_skill(skill_name)
@@ -49,6 +50,14 @@ module Harnex
           return result unless result == 0
         end
         0
+      when "uninstall"
+        local, help = parse_args(@argv)
+        return (puts self.class.usage; 0) if help
+
+        (INSTALL_SKILLS + DEPRECATED_SKILLS).each do |skill_name|
+          local ? uninstall_local(skill_name) : uninstall_global(skill_name)
+        end
+        0
       when "-h", "--help", nil
         puts self.class.usage
         0
@@ -61,7 +70,7 @@ module Harnex
 
     private
 
-    def parse_install_args(args)
+    def parse_args(args)
       local = false
       help = false
 
@@ -74,12 +83,12 @@ module Harnex
         when /\A-/
           raise "harnex skills: unknown option #{arg.inspect}"
         else
-          warn("harnex skills install: unexpected argument #{arg.inspect}")
-          raise "harnex skills install takes no positional arguments"
+          warn("harnex skills: unexpected argument #{arg.inspect}")
+          raise "harnex skills takes no positional arguments"
         end
       end
 
-      [INSTALL_SKILLS, local, help]
+      [local, help]
     end
 
     def resolve_skill_source(skill_name)
@@ -92,6 +101,12 @@ module Harnex
       1
     end
 
+    def remove_deprecated(local)
+      DEPRECATED_SKILLS.each do |skill_name|
+        local ? uninstall_local(skill_name) : uninstall_global(skill_name)
+      end
+    end
+
     def install_local(skill_name, skill_source)
       repo_root = Harnex.resolve_repo_root(Dir.pwd)
       claude_dir = File.join(repo_root, ".claude", "skills", skill_name)
@@ -142,6 +157,39 @@ module Harnex
       0
     end
 
+    def uninstall_local(skill_name)
+      repo_root = Harnex.resolve_repo_root(Dir.pwd)
+      claude_dir = File.join(repo_root, ".claude", "skills", skill_name)
+      codex_dir = File.join(repo_root, ".codex", "skills", skill_name)
+
+      removed = false
+      if File.exist?(codex_dir) || File.symlink?(codex_dir)
+        FileUtils.rm_rf(codex_dir)
+        removed = true
+      end
+      if File.exist?(claude_dir) || File.symlink?(claude_dir)
+        FileUtils.rm_rf(claude_dir)
+        removed = true
+      end
+      puts "removed #{skill_name}" if removed
+    end
+
+    def uninstall_global(skill_name)
+      claude_dir = File.expand_path("~/.claude/skills/#{skill_name}")
+      codex_dir = File.expand_path("~/.codex/skills/#{skill_name}")
+
+      removed = false
+      if File.exist?(codex_dir) || File.symlink?(codex_dir)
+        FileUtils.rm_rf(codex_dir)
+        removed = true
+      end
+      if File.exist?(claude_dir) || File.symlink?(claude_dir)
+        FileUtils.rm_rf(claude_dir)
+        removed = true
+      end
+      puts "removed #{skill_name}" if removed
+    end
+
     def relative_path(from:, to:)
       from_parts = File.expand_path(from).split("/")
       to_parts = File.expand_path(to).split("/")

data/lib/harnex/runtime/session.rb

@@ -192,6 +192,7 @@ module Harnex
         "HARNEX_SESSION_REPO_ROOT" => repo_root
       }
       env["HARNEX_DESCRIPTION"] = description if description
+      env["HARNEX_SPAWNER_PANE"] = ENV["TMUX_PANE"] if ENV["TMUX_PANE"]
       env
     end
 

data/lib/harnex/version.rb

@@ -1,3 +1,4 @@
 module Harnex
-  VERSION = "0.2.3"
+  VERSION = "0.3.3"
+  RELEASE_DATE = "2026-04-23"
 end

data/recipes/03_buddy.md

@@ -0,0 +1,101 @@
+# Recipe: Buddy
+
+Spawn an accountability partner for a long-running session.
+
+The buddy is a separate harnex agent whose only job is to periodically
+check on the worker and nudge it if it stalls. The buddy is an LLM, so
+it has intelligence for free — it can read the worker's screen, reason
+about whether it's stuck, and compose a meaningful nudge.
+
+No special monitoring code, no configuration. Just another harnex
+session using existing primitives.
+
+## When to use
+
+- Overnight or multi-hour pipelines
+- Any work where you won't be watching and want recovery from stalls
+- When the invoking agent (you) dispatches a worker and wants assurance
+  it won't die silently
+
+## Steps
+
+### 1. Spawn the worker
+
+```bash
+harnex run codex --id worker-42 --tmux worker-42
+harnex send --id worker-42 --message "Read and execute /tmp/task-42.md"
+```
+
+### 2. Spawn its buddy
+
+```bash
+harnex run claude --id buddy-42 --tmux buddy-42
+```
+
+### 3. Give the buddy its instructions
+
+```bash
+cat > /tmp/buddy-42.md <<'EOF'
+You are an accountability partner for harnex session `worker-42`.
+
+Your job:
+1. Every 5 minutes, check on the worker:
+   - `harnex pane --id worker-42 --lines 30`
+   - `harnex status --id worker-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."`
+3. If the worker has exited (status shows no session), report back:
+   - `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-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.
+EOF
+
+harnex send --id buddy-42 --message "Read and execute /tmp/buddy-42.md"
+```
+
+## Return channel
+
+The buddy can reach its invoker (your raw Claude session) via
+`$HARNEX_SPAWNER_PANE` — the tmux pane ID of whoever ran `harnex run`.
+This works even if the invoker is not a harnex session:
+
+```bash
+# Buddy reads the invoker's screen
+tmux capture-pane -t "$HARNEX_SPAWNER_PANE" -p
+
+# Buddy types into the invoker
+tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 finished, all tests pass" Enter
+```
+
+## 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.
+
+## Cleanup
+
+Stop the buddy after the worker finishes:
+
+```bash
+harnex stop --id buddy-42
+```
+
+Or tell the buddy to self-stop in its instructions: "When the worker
+exits, run `harnex stop --id buddy-42` on yourself."
+
+## Notes
+
+- The buddy is a regular harnex session. Inspect it with `harnex pane`,
+  stop it with `harnex stop`, check it with `harnex status`.
+- For multiple workers, spawn one buddy per worker or one buddy that
+  watches several sessions.
+- The buddy's intelligence comes from being an LLM. It doesn't
+  pattern-match — it reads the screen and reasons about what to do.
+- Tune the polling interval and stall threshold in the buddy's prompt,
+  not in harnex configuration.

data/skills/harnex/SKILL.md

@@ -24,10 +24,23 @@ Check environment variables to understand your role:
 | `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
@@ -284,6 +297,37 @@ 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

data/skills/harnex-buddy/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: harnex-buddy
+description: Spawn an accountability partner for long-running harnex sessions. Use when the user asks to run something overnight, unattended, or for any work expected to take more than 30 minutes without supervision.
+---
+
+# Buddy — Accountability Partner for Long-Running Work
+
+For any long-running or unattended work, spawn a **buddy** — a second harnex
+agent that watches the worker and nudges it if it stalls.
+
+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.
+
+## When to activate
+
+- User says "do this overnight" or "run this while I'm away"
+- Task is expected to take more than 30 minutes unattended
+- User explicitly asks for a buddy, accountability partner, or monitoring
+- User asks to "keep an eye on" a dispatched worker
+
+## Spawn the buddy
+
+After dispatching the worker, spawn a buddy alongside it:
+
+```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
+```
+
+## Write the buddy prompt
+
+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`.
+
+Your job:
+1. Every 5 minutes, check on the worker:
+   - `harnex pane --id worker-42 --lines 30`
+   - `harnex status --id worker-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."`
+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`
+4. Keep watching until the worker finishes or is stopped.
+
+Do not interfere with work in progress. Only nudge when clearly stalled.
+EOF
+
+harnex send --id buddy-42 --message "Read and execute /tmp/buddy-42.md"
+```
+
+Adjust the polling interval (5 min), stall threshold (10 min), and nudge
+message to match the workload.
+
+## Return channel
+
+The buddy can reach back to the invoker (your raw Claude session) via
+`$HARNEX_SPAWNER_PANE` — the stable tmux pane ID set automatically by
+harnex at spawn time:
+
+```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" "worker-42 finished" Enter
+```
+
+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.
+
+## Cleanup
+
+Stop the buddy after the worker finishes:
+
+```bash
+harnex stop --id buddy-42
+```
+
+## Notes
+
+- 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
+- See `recipes/03_buddy.md` for the full recipe

data/skills/{chain-implement → harnex-chain}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: chain-implement
+name: harnex-chain
 description: End-to-end workflow from issue to shipped plans via harnex agents. Covers mapping, plan extraction, and the serial plan → review → implement → review → fix loop.
 ---
 
@@ -138,7 +138,7 @@ correct.
 
 ### Dispatch pattern
 
-For each plan NN, use the Fire & Watch pattern from the `dispatch` skill:
+For each plan NN, use the Fire & Watch pattern from the `harnex-dispatch` skill:
 
 ```bash
 # Steps 1-3: Plan convergence (skip if plan already extracted and reviewed)
@@ -211,7 +211,7 @@ By default, all work happens serially on master. Use worktrees only when:
 - The user explicitly requests isolation
 - You need to work on something else while a plan is being implemented
 
-See the `dispatch` skill for worktree setup and caveats.
+See the `harnex-dispatch` skill for worktree setup and caveats.
 
 ## When Things Go Wrong
 

data/skills/{dispatch → harnex-dispatch}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: dispatch
+name: harnex-dispatch
 description: Fire & Watch — the standard pattern for launching and monitoring harnex agent sessions. Use when dispatching implementation, review, or fix agents.
 ---
 
@@ -161,6 +161,23 @@ harnex status           # current repo sessions
 harnex status --all     # all repos
 ```
 
+## Buddy for Long-Running Dispatches
+
+If the dispatched work is expected to take a long time (overnight, multi-hour)
+or the user asks for unattended execution, spawn a buddy alongside the worker:
+
+```bash
+# Worker
+harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
+  --context "Implement koder/plans/NN_name.md. Run tests when done."
+
+# Buddy to watch it
+harnex run claude --id buddy-NN --tmux buddy-NN
+harnex send --id buddy-NN --message "Watch session cx-impl-NN. Poll every 5 min with harnex pane --id cx-impl-NN --lines 20. Nudge with harnex send if stuck for >10 min. Report back to \$HARNEX_SPAWNER_PANE when done."
+```
+
+The buddy replaces manual Fire & Watch polling. See `recipes/03_buddy.md`.
+
 ## What NOT to Do
 
 - **Never** launch agents with raw `tmux send-keys` or `tmux new-window`

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.3
 platform: ruby
 authors:
 - Jikku Jose
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-23 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.
@@ -23,6 +23,7 @@ files:
 - LICENSE
 - README.md
 - TECHNICAL.md
+- bin/gem-push
 - bin/harnex
 - lib/harnex.rb
 - lib/harnex/adapters.rb
@@ -54,9 +55,11 @@ files:
 - lib/harnex/watcher/polling.rb
 - recipes/01_fire_and_watch.md
 - recipes/02_chain_implement.md
-- skills/chain-implement/SKILL.md
+- recipes/03_buddy.md
 - skills/close/SKILL.md
-- skills/dispatch/SKILL.md
+- skills/harnex-buddy/SKILL.md
+- skills/harnex-chain/SKILL.md
+- skills/harnex-dispatch/SKILL.md
 - skills/harnex/SKILL.md
 - skills/open/SKILL.md
 homepage: https://github.com/jikkuatwork/harnex
@@ -66,7 +69,7 @@ metadata:
   homepage_uri: https://github.com/jikkuatwork/harnex
   source_code_uri: https://github.com/jikkuatwork/harnex
   bug_tracker_uri: https://github.com/jikkuatwork/harnex/issues
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -82,7 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.5.3
-signing_key:
+signing_key: 
 specification_version: 4
 summary: PTY harness for terminal AI agents
 test_files: []