harnex 0.6.0 → 0.6.2

data/guides/03_buddy.md

@@ -0,0 +1,94 @@
+# Buddy Monitoring
+
+A buddy is a second harnex session that watches one or more workers and nudges
+them if they stall. Use a buddy when the work is long-running, unattended, or
+needs interpretation that simple stall policy cannot provide.
+
+For simple inactivity recovery, prefer built-in watch mode:
+
+```bash
+harnex run codex --id cx-i-NN --watch --preset impl --context "Read /tmp/task-impl-NN.md"
+```
+
+Use a buddy when you need reasoning over pane contents, semantic checks, or
+multi-session correlation.
+
+## When To Use
+
+Use a buddy for:
+
+- Overnight or multi-hour work.
+- Any dispatched task expected to run more than about 30 minutes unattended.
+- Work where a stalled prompt, permission request, or disconnect would waste a
+  long slot.
+- Monitoring multiple signals before deciding whether to nudge.
+
+## Spawn
+
+Spawn the worker first, then spawn the buddy:
+
+```bash
+harnex run codex --id cx-i-42 --tmux cx-i-42 \
+  --context "Read and execute /tmp/task-impl-42.md"
+
+harnex run claude --id buddy-42 --tmux buddy-42
+```
+
+The buddy is just another harnex session. Inspect it, stop it, and read its
+logs with the same commands as any worker.
+
+## Buddy Prompt
+
+Give the buddy an explicit polling loop, stall threshold, nudge rule, return
+channel, and cleanup rule:
+
+```text
+You are an accountability partner for harnex session `cx-i-42`.
+
+Every 5 minutes:
+- Run `harnex pane --id cx-i-42 --lines 30`.
+- Run `harnex status --id cx-i-42 --json`.
+
+If the worker appears stuck at a prompt or permission dialog for more than
+10 minutes with no progress, nudge it:
+- `harnex send --id cx-i-42 --message "You appear to have stalled. Continue with your current task."`
+
+If the worker exits or writes `/tmp/cx-i-42-done.txt`, report back:
+- `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "cx-i-42 finished. Check /tmp/cx-i-42-done.txt." Enter`
+
+Do not interfere with active work. Stop yourself after reporting completion.
+```
+
+Send it:
+
+```bash
+harnex send --id buddy-42 --message "Read and execute /tmp/buddy-42.md"
+```
+
+## Return Channel
+
+Every harnex-spawned session receives `HARNEX_SPAWNER_PANE` when the invoker is
+inside tmux. The buddy can use it to report to an invoker that is not itself a
+harnex session:
+
+```bash
+tmux capture-pane -t "$HARNEX_SPAWNER_PANE" -p
+tmux send-keys -t "$HARNEX_SPAWNER_PANE" "cx-i-42 finished" Enter
+```
+
+If no tmux return pane is available, require the buddy to write a file and tell
+the invoker where to read it.
+
+## Cleanup
+
+Stop the buddy after the worker completes:
+
+```bash
+harnex stop --id buddy-42
+```
+
+For full recipe form, use:
+
+```bash
+harnex recipes show 03
+```

data/guides/04_monitoring.md

@@ -0,0 +1,130 @@
+# Monitoring Patterns
+
+Monitoring should be based on work-level signals first and UI state second.
+Pane state is useful for interpretation, but it should not be the only proof
+that delegated work is finished.
+
+## Signal Ladder
+
+Prefer signals in this order:
+
+| Signal | Use |
+| --- | --- |
+| Expected artifact | Primary proof that a task produced its deliverable |
+| Tests and git state | Confirms work landed and the tree is not mid-edit |
+| `harnex events` | Structured runtime events, including task completion |
+| `harnex logs` | Transcript history and last output |
+| `harnex pane` | Live UI interpretation and prompt/error diagnosis |
+| `harnex status` | Session liveness and coarse state |
+
+For Codex app-server sessions, `harnex wait --until task_complete` is a strong
+turn-level fence. It still does not know your acceptance criteria; verify the
+expected artifact or tests afterward.
+
+## Completion Test
+
+For unattended work, declare done with a conjunction of work-level facts:
+
+```bash
+test -f /tmp/cx-i-NN-done.txt &&
+  test -z "$(git status --short)" &&
+  test "$(git log -1 --format=%ct)" -lt "$(($(date +%s) - 600))"
+```
+
+Adjust the artifact path and commit-age window to the task. The point is to
+avoid declaring done while a worker is between edits or between commits.
+
+## Why Pane State Alone Is Not Enough
+
+Avoid using `state=prompt` or a quiet pane as the only completion signal:
+
+- A finished agent can sit at a prompt forever.
+- Some CLIs stay in a session state while auto-fix or tool loops continue.
+- Focus changes and UI redraws can reset idle timers.
+- A prompt can also mean the agent is blocked, not done.
+
+Use `harnex pane` to understand what happened after a stronger signal tells you
+where to look.
+
+## Polling Patterns
+
+For active supervision:
+
+```bash
+harnex pane --id cx-i-NN --lines 40
+harnex events --id cx-i-NN --snapshot
+harnex logs --id cx-i-NN --lines 80
+```
+
+For continuous viewing:
+
+```bash
+harnex pane --id cx-i-NN --follow --interval 2
+harnex logs --id cx-i-NN --follow
+harnex events --id cx-i-NN
+```
+
+For task completion:
+
+```bash
+harnex wait --id cx-i-NN --until task_complete --timeout 900
+```
+
+## Background Sweeper
+
+Consumers often run a small shell loop that checks the expected done marker,
+tree state, and harnex liveness. Keep a hard wall-clock cap so an unattended
+pipeline cannot wait forever:
+
+```bash
+start=$(date +%s)
+max_wait=5400
+
+until test -f /tmp/cx-i-NN-done.txt; do
+  if test "$(($(date +%s) - start))" -gt "$max_wait"; then
+    echo "wall-clock cap hit for cx-i-NN" >&2
+    exit 2
+  fi
+
+  harnex status --id cx-i-NN --json
+  harnex pane --id cx-i-NN --lines 20
+  sleep 60
+done
+```
+
+Recommended caps:
+
+| Work type | Cap |
+| --- | --- |
+| Small single dispatch | 30 minutes |
+| Medium implementation | 90 minutes |
+| Large unattended phase | 3 hours |
+
+## Built-In Watch Mode
+
+Use `harnex run --watch` when one foreground process should launch the worker
+and apply bounded stall recovery:
+
+```bash
+harnex run codex --id cx-i-NN --watch --preset impl \
+  --context "Read /tmp/task-impl-NN.md"
+```
+
+`--watch` exits with:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Session exited |
+| `1` | Operational error |
+| `2` | Watcher escalated after bounded resumes |
+
+Use a buddy instead when the monitoring decision needs language-level
+interpretation.
+
+## Anti-Patterns
+
+- Polling `state=prompt` alone and calling it done.
+- Letting an unattended loop run with no wall-clock cap.
+- Reading raw tmux panes instead of `harnex pane`.
+- Using `--wait-for-idle` as acceptance proof.
+- Reusing a worker after a failure changes the task scope.

data/guides/05_naming.md

@@ -0,0 +1,106 @@
+# Naming Conventions
+
+Use predictable session IDs so humans, agents, tmux windows, logs, events, and
+done markers all point at the same work.
+
+## Session IDs
+
+Format:
+
+```text
+<cli>-<phase>-<number>
+```
+
+Common prefixes:
+
+| Prefix | Meaning |
+| --- | --- |
+| `cx` | Codex worker |
+| `cl` | Claude worker |
+| `buddy` | Buddy monitor |
+
+Common phases:
+
+| Code | Phase |
+| --- | --- |
+| `m` | Mapping or analysis |
+| `p` | Plan writing |
+| `r` | Plan review |
+| `f` | Plan fix |
+| `i` | Implementation |
+| `cr` | Code review |
+| `cf` | Code fix |
+
+Examples:
+
+```text
+cx-m-42      Codex maps task 42
+cx-p-42      Codex writes plan 42
+cx-r-42      Codex reviews plan 42
+cx-f-42      Codex fixes plan 42
+cx-i-42      Codex implements plan 42
+cx-cr-42     Codex reviews implementation 42
+cx-cf-42     Codex fixes implementation 42
+buddy-42     Buddy monitors task 42
+```
+
+Use names that fit your project. The important part is that the ID is stable,
+short, and present in every artifact.
+
+## Match `--id` And `--tmux`
+
+Always pass both and keep them identical:
+
+```bash
+harnex run codex --id cx-i-42 --tmux cx-i-42
+```
+
+Avoid this:
+
+```bash
+harnex run codex --tmux cx-i-42
+```
+
+If `--id` is missing, harnex generates a random session ID. The tmux window may
+look right, but `harnex status`, `harnex pane --id`, and logs need the random
+ID.
+
+## Retry Suffixes
+
+If a session fails and you dispatch a fresh attempt, append a suffix:
+
+```text
+cx-i-42      first attempt
+cx-i-42b     second attempt
+cx-i-42c     third attempt
+```
+
+Keep the old session's logs. They are useful for diagnosis.
+
+## Task Files
+
+Use human-readable file names for long instructions:
+
+```text
+/tmp/task-plan-42.md
+/tmp/task-impl-42.md
+/tmp/task-review-42.md
+/tmp/task-fix-42.md
+```
+
+The task file name does not need to duplicate the exact short phase code. It
+should be easy to scan in `/tmp` and should include the same task number as the
+session ID.
+
+## Done Markers
+
+Derive done markers from the session ID:
+
+```text
+/tmp/cx-p-42-done.txt
+/tmp/cx-i-42-done.txt
+/tmp/cx-cr-42-done.txt
+```
+
+When a brief asks for a completion marker, make it one line and include the
+highest-signal result: tests passed, review clean, or the blocking issue.

data/lib/harnex/adapters/codex_appserver.rb

@@ -34,10 +34,12 @@ module Harnex
 
       EVENTS = %w[task_complete turn_started item_completed disconnected].freeze
 
-      attr_reader :thread_id, :current_turn_id, :last_completed_at
+      attr_reader :thread_id, :current_turn_id, :last_completed_at, :initial_prompt
 
       def initialize(extra_args = [])
         super("codex", extra_args)
+        @initial_prompt = extra_args.join(" ").strip
+        @initial_prompt = nil if @initial_prompt.empty?
         @client = nil
         @thread_id = nil
         @current_turn_id = nil
@@ -55,6 +57,10 @@ module Harnex
         ["codex", "app-server"]
       end
 
+      def build_command
+        base_command
+      end
+
       def describe
         {
           transport: transport,
@@ -76,10 +82,19 @@ module Harnex
         }
       end
 
-      # The screen-based send path is not used for stdio_jsonrpc.
-      # Session#run_jsonrpc routes through #dispatch instead.
-      def build_send_payload(*)
-        raise NotImplementedError, "codex_appserver uses #dispatch, not screen-based send"
+      def build_send_payload(text:, submit:, enter_only:, screen_text:, force: false)
+        state = input_state(nil)
+        if !force && submit && !enter_only && state[:input_ready] != true
+          raise ArgumentError, blocked_message(state, enter_only: enter_only)
+        end
+        raise ArgumentError, "Codex app-server cannot stage input without submitting it" unless submit || enter_only
+        raise ArgumentError, "Codex app-server does not support submit-only input" if enter_only
+
+        {
+          dispatch: { prompt: text.to_s },
+          input_state: state,
+          force: force
+        }
       end
 
       # No-op: closing the subprocess is handled via #close.
@@ -221,6 +236,12 @@ module Harnex
         [wait_thr.pid, stdin_io, stdout_io]
       end
 
+      def blocked_message(state, enter_only:)
+        return super if enter_only
+
+        "Codex app-server is not at a prompt; wait and retry or use `harnex send --force` (state: #{state[:state]})"
+      end
+
       # Minimal JSON-RPC 2.0 client. One JSON object per line.
       # Responses keyed by id; everything else is a notification.
       class JsonRpcClient

data/lib/harnex/cli.rb

@@ -29,8 +29,8 @@ module Harnex
         Recipes.new(@argv.drop(1)).run
       when "guide"
         Guide.new.run
-      when "skills"
-        Skills.new(@argv.drop(1)).run
+      when "agents-guide"
+        AgentsGuide.new(@argv.drop(1)).run
       when "doctor"
         Doctor.new(@argv.drop(1)).run
       when "help"
@@ -71,8 +71,10 @@ module Harnex
         Recipes.usage
       when "guide"
         Guide.usage
-      when "skills"
-        Skills.usage
+      when "agents-guide"
+        AgentsGuide.usage
+      when "doctor"
+        Doctor.usage
       else
         usage
       end
@@ -89,6 +91,8 @@ module Harnex
           harnex logs --id ID [options]
           harnex events --id ID [options]
           harnex pane --id ID [options]
+          harnex agents-guide [topic]
+          harnex doctor
           harnex help [command]
 
         Commands:
@@ -102,11 +106,13 @@ module Harnex
           pane    Capture the current tmux pane for a live session
           recipes List and read workflow recipes
           guide   Show the getting started guide
-          skills  Install bundled skills into a repo or globally
+          agents-guide
+                  Show agent dispatch, chain, buddy, monitoring, and naming guides
           doctor  Run preflight checks for adapter dependencies
           help    Show command help
 
         New to harnex? Start with: harnex guide
+        Working with agents (dispatching tasks)? Read: harnex agents-guide
 
         Notes:
           CLIs with smart prompt detection: #{Adapters.known.join(', ')}
@@ -120,8 +126,9 @@ module Harnex
           harnex logs --id main --follow
           harnex events --id main --snapshot
           harnex pane --id main --lines 40
+          harnex agents-guide dispatch
+          harnex doctor
           harnex send --id main --message "Summarize current progress."
-          harnex skills install
       TEXT
     end
   end

data/lib/harnex/commands/agents_guide.rb

@@ -0,0 +1,109 @@
+module Harnex
+  class AgentsGuide
+    GUIDES_DIR = File.expand_path("../../../../guides", __FILE__)
+
+    def self.usage
+      <<~TEXT
+        Usage: harnex agents-guide [list|show <topic>|<topic>]
+
+        Subcommands:
+          list           List available agent guide topics (default)
+          show <topic>   Print a guide by name or number
+
+        Examples:
+          harnex agents-guide
+          harnex agents-guide list
+          harnex agents-guide show 01
+          harnex agents-guide show dispatch
+          harnex agents-guide monitoring
+
+        Common patterns:
+          harnex agents-guide dispatch
+          harnex agents-guide chain
+          harnex agents-guide naming
+
+        Gotchas:
+          Agent guides replace the old harnex skills install flow.
+          They are packaged with the gem and require no external project docs.
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      subcommand = @argv.shift
+      case subcommand
+      when nil, "list"
+        list_guides
+      when "show"
+        show_guide(@argv.first)
+      when "-h", "--help"
+        puts self.class.usage
+        0
+      else
+        show_guide(subcommand)
+      end
+    end
+
+    private
+
+    def list_guides
+      files = guide_files
+      if files.empty?
+        puts "No agent guides found."
+        return 0
+      end
+
+      puts "Agent guides:\n\n"
+      files.each do |file|
+        name = File.basename(file, ".md")
+        title = extract_title(file)
+        puts "  #{name}  #{title}"
+      end
+      puts "\nRun `harnex agents-guide show <topic>` to read one."
+      0
+    end
+
+    def show_guide(query)
+      unless query
+        warn("harnex agents-guide show: topic required")
+        return 1
+      end
+
+      file = find_guide(query)
+      unless file
+        warn("harnex agents-guide: no topic matching #{query.inspect}")
+        warn("Run `harnex agents-guide list` to see available topics.")
+        return 1
+      end
+
+      puts File.read(file)
+      0
+    end
+
+    def find_guide(query)
+      files = guide_files
+
+      exact = files.find { |file| File.basename(file, ".md") == query }
+      return exact if exact
+
+      prefix = files.find { |file| File.basename(file, ".md").start_with?(query) }
+      return prefix if prefix
+
+      files.find { |file| File.basename(file, ".md").include?(query) }
+    end
+
+    def guide_files
+      return [] unless Dir.exist?(GUIDES_DIR)
+
+      Dir.glob(File.join(GUIDES_DIR, "*.md")).sort
+    end
+
+    def extract_title(file)
+      first_line = File.foreach(file).first.to_s.strip
+      first_line.start_with?("#") ? first_line.sub(/^#+\s*/, "") : ""
+    end
+  end
+end

data/lib/harnex/commands/doctor.rb

@@ -12,6 +12,14 @@ module Harnex
         Currently verifies that Codex CLI is installed and at version
         >= #{MIN_CODEX_VERSION} (required for the JSON-RPC `app-server`
         adapter).
+
+        Common patterns:
+          harnex doctor
+          harnex doctor --help
+
+        Gotchas:
+          doctor validates local adapter prerequisites; it does not start sessions.
+          Run it after installing or upgrading Codex CLI.
       TEXT
     end
 

data/lib/harnex/commands/events.rb

@@ -18,6 +18,16 @@ module Harnex
           --snapshot      Print current events and exit (alias for --no-follow)
           --from TS       Replay floor (ISO-8601, inclusive)
           -h, --help      Show this help
+
+        Common patterns:
+          #{program_name} --id cx-i-42 --snapshot
+          #{program_name} --id cx-i-42
+          #{program_name} --id cx-i-42 --from 2026-05-06T10:00:00Z --snapshot
+
+        Gotchas:
+          events is structured JSONL; logs is human transcript text.
+          Default mode follows live events. Use --snapshot to print and exit.
+          Use wait --until task_complete when you only need a completion fence.
       TEXT
     end
 

data/lib/harnex/commands/guide.rb

@@ -7,6 +7,15 @@ module Harnex
         Usage: harnex guide
 
         Print the getting started guide.
+
+        Common patterns:
+          harnex guide
+          harnex agents-guide
+          harnex recipes
+
+        Gotchas:
+          guide is short human onboarding.
+          agents-guide is the deeper operational reference for dispatching agents.
       TEXT
     end
 

data/lib/harnex/commands/logs.rb

@@ -17,6 +17,16 @@ module Harnex
           --follow      Keep streaming appended output until session exit
           --lines N     Print the last N lines before following (default: #{DEFAULT_LINES})
           -h, --help    Show this help
+
+        Common patterns:
+          #{program_name} --id cx-i-42 --lines 80
+          #{program_name} --id cx-i-42 --follow
+          #{program_name} --id cx-i-42 --repo /path/to/repo --lines 200
+
+        Gotchas:
+          logs reads the persisted transcript, not the live tmux screen.
+          Use pane when you need the current TUI view or prompt text.
+          --follow streams until the live session exits.
       TEXT
     end
 

data/lib/harnex/commands/pane.rb

@@ -20,6 +20,16 @@ module Harnex
           --interval N  Refresh interval in seconds for --follow (default: #{FOLLOW_INTERVAL.to_i})
           --json        Output JSON with capture metadata
           -h, --help    Show this help
+
+        Common patterns:
+          #{program_name} --id cx-i-42 --lines 40
+          #{program_name} --id cx-i-42 --lines 40 --json
+          #{program_name} --id cx-i-42 --follow --interval 2
+
+        Gotchas:
+          pane requires a tmux-backed session.
+          Use --repo when the same ID exists in multiple repos or worktrees.
+          Do not use pane state alone as completion proof; verify artifacts/tests.
       TEXT
     end
 

data/lib/harnex/commands/recipes.rb

@@ -17,6 +17,15 @@ module Harnex
           harnex recipes list
           harnex recipes show 01
           harnex recipes show fire_and_watch
+
+        Common patterns:
+          harnex recipes show 01   # Fire and Watch
+          harnex recipes show 02   # Chain Implement
+          harnex recipes show 03   # Buddy
+
+        Gotchas:
+          Recipes are compact command walkthroughs.
+          Use `harnex agents-guide` for the deeper agent-facing guide.
       TEXT
     end
 

data/lib/harnex/commands/run.rb

@@ -48,6 +48,17 @@ module Harnex
           CLIs with smart prompt detection: #{Adapters.known.join(', ')}
           Any other CLI name is launched with generic wrapping.
           Wrapper options may appear before or after <cli>.
+
+        Common patterns:
+          #{program_name} codex --id cx-i-42 --tmux cx-i-42 --context "Read /tmp/task-impl-42.md"
+          #{program_name} codex --id cx-i-42 --watch --preset impl --context "Read /tmp/task-impl-42.md"
+          #{program_name} claude --id cl-r-42 --tmux cl-r-42 --description "Review task 42"
+
+        Gotchas:
+          Always pair --id and --tmux with the same value for delegated work.
+          Passing --tmux without --id creates a random harnex session ID.
+          --watch is foreground-only; do not combine it with --tmux or --detach.
+          Use -- before child CLI flags when a flag could be parsed by harnex.
       TEXT
     end