harnex 0.5.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/base.rb

@@ -20,6 +20,16 @@ module Harnex
         @extra_args = extra_args.dup
       end
 
+      # Default transport. Adapters speaking JSON-RPC override to
+      # :stdio_jsonrpc; Session#run uses this to pick the I/O path.
+      def transport
+        :pty
+      end
+
+      def describe
+        { transport: transport }
+      end
+
       def build_command
         base_command + @extra_args
       end