harnex 0.12.0 → 0.29.0

data/README.md

@@ -1,43 +1,61 @@
 # Harnex
 
-Run multiple AI coding agents from your terminal and coordinate them.
+Pi workers (GPT models by default) as tools for you and your coding agents.
 
-Harnex wraps Claude Code, OpenAI Codex, Pi, OpenCode, or any terminal CLI in a
-local harness so you can launch agents, send them tasks, inspect panes,
-transcripts, and events, and stop them cleanly -- all from the command line.
+**Website and docs: [harnex.zyt.app](https://harnex.zyt.app)** ·
+upgrading from an older release: [docs/upgrading-to-0.29.md](docs/upgrading-to-0.29.md)
+
+Harnex runs Pi workers in visible tmux windows and hands their results back
+in one call: ask another model a question, delegate a task into its own git
+worktree and land it, run several workers in parallel, and follow up with a
+worker that keeps its context. Claude Code and Pi get the same verbs as
+native MCP tools. Underneath, it is a local harness for Pi, Claude Code,
+OpenCode or any terminal CLI: launch, send, watch, inspect and stop.
 
 ```bash
 gem install harnex
+harnex doctor            # checks Pi (structured RPC needs Pi 0.80.4+) and tmux
+harnex mcp install       # optional: native tools for Claude Code and Pi
 ```
 
-Harnex itself requires **Ruby 3.x** and uses only the Ruby standard
-library. Install the CLIs you want to wrap separately; Codex JSON-RPC
-support requires Codex CLI **0.128.0 or newer**, Pi structured RPC requires
-Pi **0.80.4 or newer**, and tmux-backed workflows require `tmux`.
+Harnex itself requires **Ruby 3.x** and uses only the Ruby standard library.
 
-Then ask the CLI what to do next:
+## For agents (and people): lanes
 
 ```bash
-harnex
-harnex --help
-harnex agents-guide
-```
+harnex ask "Which module writes dispatch rows, and is the lane case tested?"
 
-Run the matching static check after installing or upgrading an agent CLI:
+harnex delegate --worktree word-count "Add TextKit.word_count(text) with a test; run bin/test"
+git diff HEAD...harnex/word-count          # review
+harnex land word-count                     # merge, remove the worktree and branch
 
-```bash
-harnex doctor --adapter codex
-harnex doctor --adapter pi
+harnex reply word-count "Also add TextKit.char_count(text)"   # same worker, same context
+
+harnex delegate --no-wait --worktree a "Task A"
+harnex delegate --no-wait --worktree b "Task B"
+harnex result                              # each result as it lands
+harnex lanes                               # what is open and what each needs
 ```
 
-These verify the local structured-transport version prerequisites without
-starting a model turn.
+Every command prints the worker's reply and a `── NAME:` footer: state, time,
+model, cost, commits and the next commands. Exit codes: 0 done, 1 failed, 124
+still working (`harnex result NAME` keeps waiting; the default wait is 9
+minutes, under a 10-minute agent tool cap).
+
+- **MCP:** `harnex mcp install` registers `harnex mcp` for Claude Code (user
+  scope) and Pi, and installs a `gpt` subagent for Claude Code. The tools
+  `ask`, `delegate`, `result`, `reply`, `land`, `discard` and `lanes` then
+  appear natively. Long calls report progress; Claude Code moves them to the
+  background after two minutes.
+- **Docs:** [lanes](docs/lanes.md), [MCP server](docs/mcp.md),
+  [coding agents](docs/agents.md); `harnex agents-guide claude` is the
+  agent-facing guide and `harnex --help` lists everything.
+
+## Low-level control
 
-`harnex agents-guide` is the agent-facing reference for dispatch, chain,
-buddy, monitoring, and naming patterns. It is packaged in the gem; no skills
-or project-local docs are required.
+Before an unattended run, `harnex preflight pi --cwd ~/repo` proves the Pi
+adapter end to end with one tiny real dispatch and prints a JSON verdict.
 
-## What it does
 
 ```bash
 # Start a visible one-shot worker, give it a task, and stop on completion
@@ -73,7 +91,7 @@ enclosing git root's `.harnex/dispatch.jsonl`; a non-git directory uses the
 global `~/.local/state/harnex/dispatch.jsonl` fallback:
 
 ```bash
-harnex run codex --cwd /tmp/leximaze_eval_run_001 \
+harnex run pi --cwd /tmp/leximaze_eval_run_001 \
   --id lm-run-001 \
   --context "Read README.md and write RESPONSES.jsonl and OUTPUT.md" \
   --auto-stop
@@ -111,28 +129,17 @@ an explicit working-directory/root selector for automation.
 
 | Agent | Support |
 |-------|---------|
+| Pi (default worker) | JSONL RPC adapter (`pi --mode rpc`, Pi >= 0.80.4) with settled completion, typed failures, tool/retry events, extension-UI auto-cancel, and session stats telemetry |
 | Claude Code | PTY adapter with prompt detection, stop sequence, workspace trust, and vim mode handling |
-| OpenAI Codex | JSON-RPC `codex app-server` adapter by default; PTY mode remains supported for TUI/interactive use via `--legacy-pty` |
-| Pi | JSONL RPC adapter (`pi --mode rpc`, Pi >= 0.80.4) with settled completion, typed failures, tool/retry events, extension-UI auto-cancel, and session stats telemetry |
 | OpenCode | PTY adapter with native Ctrl+C stop handling and OpenCode-specific prompt/readiness heuristics |
 | Any terminal CLI | Generic PTY wrapping with local API, logs, status, and best-effort prompt detection |
 
-`harnex run codex` uses JSON-RPC by default. That path provides
-structured task-completion events, approval mediation, and token usage
-capture. Default JSON-RPC Codex does not accept `-m` / `--model`; pass
-model settings as child CLI config, for example `harnex run codex -- -c model=NAME`.
-Harnex forces Codex app-server `service_tier="flex"` unless you opt into
-`service_tier="fast"` with `harnex run codex --fast`.
-Use `harnex run codex --legacy-pty` when you specifically want Codex's
-terminal UI or PTY-only Codex flags. The flag name is historical; the PTY path
-is still supported.
-
 `harnex run pi` launches `pi --mode rpc` and sends `--context` as a structured
 `prompt` command (not a CLI positional argument). Harnex `--model` / `--effort`
 flags become Pi `--model` / `--thinking` startup controls and are verified over
 RPC before the prompt; use a deterministic `provider/model` value. Pass other
 Pi startup flags after the separator, for example:
-`harnex run pi --context "Implement X" -- --model anthropic/claude-sonnet-4-5 --thinking high`.
+`harnex run pi --model openai/gpt-5.1 --effort high --context "Implement X" -- --no-approve`.
 For unattended runs, explicitly choose Pi project trust with child
 `--approve` or `--no-approve`; Harnex never auto-trusts repository code.
 See [docs/pi-rpc.md](docs/pi-rpc.md) for lifecycle, compatibility, and failure
@@ -162,6 +169,18 @@ harnex stop --id cl-review
 For delegated work, pass the same value to `--id` and `--tmux` so
 `harnex status`, `harnex pane`, logs, and the tmux window name all line up.
 
+From Claude Code, a GPT-backed Pi worker can be called like a tool:
+
+```bash
+# A read-only question; stdout is the worker's answer
+harnex ask "Which module writes dispatch rows, and is the lane case tested?"
+
+# One delegated task, one blocking call, one JSON result (the reply is
+# turn_result.final_message)
+harnex run pi --id pi-i-42 --tmux pi-i-42 --context-file /tmp/task-42.md \
+  --auto-stop --wait-done --wait-timeout 9m
+```
+
 Harnex ships CLI-readable agent guides for this pattern:
 
 - **[Dispatch](guides/01_dispatch.md)** — the fire-and-watch pattern:
@@ -173,6 +192,9 @@ Harnex ships CLI-readable agent guides for this pattern:
 - **[Monitoring](guides/04_monitoring.md)** — completion signals and
   poll/watch patterns
 - **[Naming](guides/05_naming.md)** — session IDs, task files, done markers
+- **[Claude](guides/06_claude.md)** — Claude Code sessions and subagents using
+  GPT-backed Pi workers as tools: `harnex ask`, one-call delegation, parallel
+  lanes, follow-ups
 
 Read them from the installed CLI:
 
@@ -217,14 +239,13 @@ For file-change hooks, use `--watch-file PATH`. The older
 `--watch PATH`/`--watch=PATH` form is still accepted for compatibility, while
 bare `--watch` means babysitter mode.
 
-For one-shot startup prompts, add `--auto-stop`. It requires `--context`.
-A Codex app-server turn launched from `--context` only counts as accepted
-autonomous work when structured command/tool activity or a Git delta proves
-activity. Optional receipt claims cannot satisfy this gate. An acknowledgment-only turn emits
+For one-shot startup prompts, add `--auto-stop`. It requires `--context` (or
+`--context-file`). A Pi turn is accepted when it settles. With
+`--require-artifact-report` it must also show command/tool activity or a Git
+delta; an acknowledgment-only turn then emits
 `outcome.class=completed_no_activity`, makes `watch --until done` return
-non-zero, and auto-stops with a non-zero verdict instead of reporting success.
-PTY adapters still stop on prompt return because they do not expose equivalent
-structured activity signals.
+non-zero, and auto-stops with a non-zero verdict. PTY adapters stop on prompt
+return because they do not expose structured activity signals.
 
 ## Completion and waiting
 
@@ -240,7 +261,7 @@ Choose the wait/watch predicate that matches how you launched the worker:
 - `harnex wait --id ID` waits for the wrapped process to exit. This is right
   for already-exited sessions and terminal-summary recovery, but interactive
   agents can stay open after finishing a turn.
-- For structured Pi RPC and Codex app-server sessions, use
+- For structured Pi RPC sessions, use
   `harnex wait --id ID --until task_complete --timeout SECS` when you need the
   exact successful-turn event instead of terminal-exit fallback. Use
   `--until task_failed` to wait specifically for a failed structured turn.
@@ -420,7 +441,7 @@ EOF
 
 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:
+Claude Code session, a Pi session, or any tmux pane:
 
 ```bash
 tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 finished" Enter
@@ -432,6 +453,13 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 
 | Command | What it does |
 |---------|-------------|
+| `harnex ask "QUESTION"` | A read-only answer from a Pi worker (`--write` lets it edit); `harnex reply ID` follows up |
+| `harnex delegate [--worktree NAME] TASK` | A worker does the task; prints its reply and a lane footer (`--no-wait` for parallel lanes) |
+| `harnex result [NAME...]` | Wait for lanes and print each result as it lands |
+| `harnex reply NAME MESSAGE` | Follow-up to a lane's worker, which keeps its context |
+| `harnex land NAME` / `harnex discard NAME` | Merge a worktree lane and clean up / drop it |
+| `harnex lanes` | Your lanes and the next step for each |
+| `harnex mcp [install]` | The lane verbs as MCP tools for Claude Code and Pi |
 | `harnex run <cli>` | Start an agent (`--tmux` visible, `--detach` background, `--watch` built-in monitoring) |
 | `harnex send --id <id>` | Send a message (queues if busy, `--wait-for-idle` to block until the turn returns idle) |
 | `harnex stop --id <id>` | Send the agent's native exit sequence |
@@ -444,6 +472,7 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 | `harnex wait --id <id>` | Block until process exit by default; use `--until done` for unattended work completion or `--until task_complete` for exact structured turn completion |
 | `harnex artifact-report init\|validate PATH` | Validate harness-authored `harnex.artifact_report.v1` receipts; `init` remains for legacy/manual documents |
 | `harnex doctor` | Run dependency and retention diagnostics; `--sweep` reports session drift, `--prune --dry-run` previews retention, and `--prune` applies it |
+| `harnex preflight <cli>` | One tiny real dispatch proving boot, files, command exits, receipt, completion and stop (`--commit-check` adds a scratch-repo commit); JSON verdict, non-zero on failure |
 | `harnex guide` | Getting started walkthrough |
 | `harnex agents-guide` | Agent-facing dispatch, chain, buddy, monitoring, and naming guides |
 | `harnex recipes` | List and read tested workflow patterns (`show 01`, `show buddy`) |
@@ -451,12 +480,13 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 ## Uninstalling
 
 ```bash
+harnex mcp uninstall     # if you ran harnex mcp install
 gem uninstall harnex
 ```
 
 If you installed harnex skills with an older release, those copies are no
-longer used. Remove stale `~/.claude/skills/harnex-*` or
-`~/.codex/skills/harnex-*` entries manually if you want to clean them up.
+longer used. Remove stale `~/.claude/skills/harnex-*` entries manually if you
+want to clean them up.
 
 ## Going deeper