harnex 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f5551eb9f757a6028039163377a2a10bd044132513b582d50c94a5ababde1b4
-  data.tar.gz: 82a6b0e9d329c94b40c2ee79ea4bd0a153cce8e5a246c208e27d7eee702d22f4
+  metadata.gz: acc43f4432f442abd435e2ef3278ca5e2ba94802285c67a50736aae9ea40188e
+  data.tar.gz: 0437ac12e301491856ceddb176c18ab9ac334c4dab31295d55dc4203c4a0f509
 SHA512:
-  metadata.gz: cf269eb8b5bbf171154f0530d26f3135866e966e085c386326183432c4cf6b0c5cdd45f3585dd5632c7bd0db4098a54193c4d815bf4e1ab8256aa22c4f1aec9f
-  data.tar.gz: be798ec3085903e0851d7cd20b31789eed202b076774a144ed8038d23d1d61aa12ac8c9489b04370498f3108d2138672a3db2a36ba4efdb3b7c1e7763b219626
+  metadata.gz: 5f8d1d3db623e3df0a0bbeb2f5f1f9e88c18ef2b6113355ad871e9c3fc3987c1e1b7dfb32bac5b79bd32697cd3c9f80bc6163398bfd8255eb57a984a47a548bc
+  data.tar.gz: 48e51e3630cbe866ac806e30eff42aa43ed551c8e90efd16dd03675c62d91f1e62dbddcea4a13220a7a7ec4473f4d513ec3cf25be2b6080cef32ca1552abd3cc

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/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/skills.rb

@@ -3,26 +3,27 @@ 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 [--global]
+        Usage: harnex skills <subcommand> [--local]
 
         Subcommands:
-          install     Install bundled skills into the current repo
+          install     Install bundled skills (globally by default)
+          uninstall   Remove installed skills (globally by default)
 
         Options:
-          --global    Install to ~/.claude/skills and ~/.codex/skills
-                      instead of the current repo
+          --local     Target the current repo instead of global ~/.claude/
 
         Installs: #{INSTALL_SKILLS.join(', ')}
 
-        Without --global, copies each skill to .claude/skills/<skill>/
-        in the current repo and symlinks .codex/skills/<skill> to it.
+        By default, copies each skill to ~/.claude/skills/<skill>/
+        and symlinks ~/.codex/skills/<skill> to it.
 
-        With --global, symlinks both ~/.claude/skills/<skill> and
-        ~/.codex/skills/<skill> to the bundled source.
+        With --local, copies each skill to .claude/skills/<skill>/
+        in the current repo and symlinks .codex/skills/<skill> to it.
       TEXT
     end
 
@@ -34,22 +35,29 @@ module Harnex
       subcommand = @argv.shift
       case subcommand
       when "install"
-        skill_names, global, 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
 
-        skill_names.each do |skill_name|
+        remove_deprecated(local)
+
+        INSTALL_SKILLS.each do |skill_name|
           skill_source = resolve_skill_source(skill_name)
           unless skill_source
             return missing_skill(skill_name)
           end
 
-          result = global ? install_global(skill_name, skill_source) : install_local(skill_name, skill_source)
+          result = local ? install_local(skill_name, skill_source) : install_global(skill_name, skill_source)
           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
@@ -62,25 +70,25 @@ module Harnex
 
     private
 
-    def parse_install_args(args)
-      global = false
+    def parse_args(args)
+      local = false
       help = false
 
       args.each do |arg|
         case arg
-        when "--global"
-          global = true
+        when "--local"
+          local = true
         when "-h", "--help"
           help = true
         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, global, help]
+      [local, help]
     end
 
     def resolve_skill_source(skill_name)
@@ -93,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)
@@ -124,17 +138,58 @@ module Harnex
       claude_dir = File.expand_path("~/.claude/skills/#{skill_name}")
       codex_dir = File.expand_path("~/.codex/skills/#{skill_name}")
 
-      [claude_dir, codex_dir].each do |dir|
-        parent = File.dirname(dir)
-        FileUtils.mkdir_p(parent)
-        FileUtils.rm_rf(dir) if File.exist?(dir) || File.symlink?(dir)
-        File.symlink(skill_source, dir)
-        puts "symlinked #{dir} -> #{skill_source}"
+      # Copy skill to ~/.claude/skills/<skill>/
+      if Dir.exist?(claude_dir)
+        warn("harnex skills: #{claude_dir} already exists, overwriting")
+        FileUtils.rm_rf(claude_dir)
       end
+      FileUtils.mkdir_p(File.dirname(claude_dir))
+      FileUtils.cp_r(skill_source, claude_dir)
+      puts "installed #{claude_dir}"
+
+      # Symlink ~/.codex/skills/<skill> -> ~/.claude/skills/<skill>
+      codex_parent = File.dirname(codex_dir)
+      FileUtils.mkdir_p(codex_parent)
+      FileUtils.rm_rf(codex_dir) if File.exist?(codex_dir) || File.symlink?(codex_dir)
+      File.symlink(claude_dir, codex_dir)
+      puts "symlinked #{codex_dir} -> #{claude_dir}"
 
       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.2"
+  VERSION = "0.3.1"
+  RELEASE_DATE = "2026-04-19"
 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.2
+  version: 0.3.1
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-19 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.
@@ -54,9 +54,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