harnex 0.5.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b38fbca70a1ec608f414f362bb16bff85bdb5c279a5c562c4dc7048fa6acb41
-  data.tar.gz: 7a9048de3efb9461489ab0678683e0d245e60e2ac3a1dd7e617d868fce927a51
+  metadata.gz: d7c3f452ed6de7b0468cbafff82c603beb7f880458168a9acf433d4f2747bbd9
+  data.tar.gz: 24ff11cfd9f02d509e7f0720589dc4658c7acff5eefea78029146f292b3010e7
 SHA512:
-  metadata.gz: a222bd5df7a1e02e7b6cebb2e0a63649b4433baef17be35a3dd03b4128e9b406af52ae71e9c063a6912dbb9af04b187072a693271fb72f24e4d61de462a7bf1c
-  data.tar.gz: eb2ca6564d079b0e162e72e9d07d01239ba2ce0c5b118fbd4360671d555c452571b2c64cb0f5a4be3c0b23c13e57b606d7ca98632d345f7570d5c69caacc9ad8
+  metadata.gz: 7d401086cf7cc01a563a34901076175c769ceb06165ef5d875dc5f1ebb722b241ec02b43d7d086575ef2fb78186f30ba3f427fc8dcd0984d44c8ce5accf13527
+  data.tar.gz: 10927dc8202b920ef3cdd5dd0a9e728c56e6673bc19cf5fac58f3aea85a52a6ac4b5cabd8a11f856152c3f492241c17e11e1b7a155809283554894784eb301a5

data/CHANGELOG.md

@@ -0,0 +1,154 @@
+# Changelog
+
+## [0.6.2] — 2026-05-06
+
+### Fixed
+
+- App-server adapter: `--context` delivery and `harnex send` mid-session
+  now succeed without `--legacy-pty`. Previously both raised
+  `NotImplementedError` from `build_send_payload` on the stdio_jsonrpc
+  transport — `--context` boot fired a `disconnected source=transport`
+  event and the session never registered; `harnex send` timed out at
+  120s with `delivery timed out`. Closes #29.
+
+### Notes
+
+- `--legacy-pty` is no longer required for any normal dispatch flow.
+  Removal still scheduled for 0.7.0 per the 0.6.1 deprecation note.
+
+## [0.6.1] — 2026-05-06
+
+### Added
+
+- `harnex agents-guide [topic]` exposes dispatch, chain, buddy,
+  monitoring, and naming guidance from the installed CLI.
+- `harnex --help` now points agents to `harnex agents-guide`.
+- `harnex help <command>` entries now include common patterns and gotchas for
+  agent dispatch workflows.
+
+### Removed
+
+- `harnex skills install` and `harnex skills uninstall`.
+- Bundled `skills/` sources and repo-local skill symlinks. Agents now discover
+  guidance through `harnex --help` and `harnex agents-guide`.
+
+### Notes
+
+- `--legacy-pty` removal is still scheduled for 0.7.0.
+- `man harnex` was deferred; the CLI-native `agents-guide` path satisfies the
+  agent-discovery acceptance test without adding a man-page build dependency.
+
+## 0.6.0 — 2026-05-06
+
+### Architectural pivot: Codex on JSON-RPC
+
+harnex now speaks `codex app-server` JSON-RPC over stdio for the
+Codex adapter. Pane-scraping is retired for Codex. Closed by
+construction:
+
+- #22 (Codex side; `--watch --stall-after` still applies to
+  claude/generic)
+- #24 (disconnect detection — `error` notifications and JSON-RPC
+  error responses replace screen-text regex)
+- #25 (first-class completion signal — `turn/completed` is it)
+
+### New
+
+- `harnex wait --until task_complete` — block until a turn completes.
+  Example: `harnex wait --id cx-i-242 --until task_complete`.
+  Adapter-agnostic; tails the events JSONL.
+- `harnex status --json` includes `last_completed_at`, `model`,
+  `effort`, `auto_disconnects`.
+- `harnex doctor` preflight checks Codex CLI ≥ 0.128.0.
+- `Adapter#transport` and `Adapter#describe` extension points so
+  callers can introspect adapter contracts. Default is
+  `:pty` for backward compatibility.
+
+### Migration
+
+- Codex CLI ≥ 0.128.0 required.
+- Existing `harnex run codex ...` invocations work unchanged.
+- Emergency fallback: `harnex run codex --legacy-pty ...` (the
+  pre-0.6.0 PTY adapter). Deprecated; will be removed in 0.7.0.
+
+### Cross-repo
+
+- Resolves holm #201 from the harnex side. holm #271 (substrate v2
+  meta) tracks the broader pivot.
+
+## 0.5.0 — 2026-05-01
+
+### Added
+
+- `harnex run --meta '<JSON>'` — per-dispatch metadata intake captured into
+  the `started` event for downstream telemetry analysis.
+- `harnex run --summary-out PATH` — appends one consolidated dispatch
+  telemetry record per session (`meta` + `predicted` + `actual` blocks) to
+  a project-local file. Default target is `<repo>/koder/DISPATCH.jsonl`.
+- Token usage + git telemetry capture: new `usage`, `git`, and `summary`
+  events emitted on session end with input/output/reasoning/cached tokens,
+  wall time, cost, LOC changed, files changed, and commits made.
+
+### Notes
+
+- Closes #23 (dispatch telemetry capture). Additive — `events`
+  `schema_version` stays at `1`.
+- Authoritative DISPATCH record schema is maintained in the consumer
+  project (holm `koder/DISPATCH.schema.md`); harnex implements what is
+  required and leaves non-extractable fields explicitly `null`.
+
+## 0.4.0 — 2026-04-30
+
+### Added — Built-in dispatch monitoring (#22, Layers 1–4)
+
+- **Layer 1**: `log_mtime` and `log_idle_s` exposed in `harnex status`
+  payloads, with an `IDLE` column in text mode.
+- **Layer 2**: `harnex run --watch --stall-after DUR --max-resumes N`
+  blocking babysitter for fire-and-watch workflows. Auto-resumes a
+  stalled session up to `N` times. Legacy file-hook mode preserved via
+  the renamed `--watch-file` flag.
+- **Layer 3**: `harnex run --preset impl|plan|gate` resolves
+  stall/resume defaults; explicit `--stall-after` / `--max-resumes`
+  flags still override.
+- **Layer 4**: `harnex events --id <session>` JSONL stream with v1
+  schema (envelope: `schema_version`, `seq`, `ts`, `id`, `type`); emits
+  `started`, `send`, `exited` events. `send.msg` truncated to 200 chars
+  with `msg_truncated` flag. File transport at
+  `~/.local/state/harnex/events/<repo>--<id>.jsonl`. Stability promise:
+  `schema_version: 1` means additive-only changes.
+
+### Notes
+
+- Layer 5 (codex stream-disconnect detection) was deferred at 0.4.0
+  close to avoid regex-heuristic stalls. Later closed by construction
+  in 0.6.0 via the Codex app-server adapter (#24, #27).
+
+## 0.3.4 — 2026-04-24
+
+### Changed
+
+- Skill catalogue collapsed: `harnex` orchestrator skill merged into
+  `dispatch`; `chain-implement` rewritten as a cohesive set;
+  cross-references audited end-to-end. Closes #21.
+
+### Notes
+
+- The bundled skills system was later removed entirely in 0.6.1
+  (superseded by CLI-discoverable `harnex agents-guide`).
+
+## 0.3.3 — 2026-04-23
+
+### Fixed
+
+- `--tmux` no longer greedily consumes the next flag as the window
+  name. Previously `harnex run codex --tmux --id foo` was parsed as
+  `--tmux="--id"`, dropping the explicit session ID. Closes #20.
+
+## 0.3.2 — 2026-04-19
+
+### Fixed
+
+- State detection for cursor-addressed TUIs (Codex v0.121+). The
+  cursor-positioning escape sequences emitted by newer Codex versions
+  were confusing the prompt detector, leaving sessions stuck in
+  `unknown` state.

data/GUIDE.md

@@ -223,22 +223,21 @@ If the review finds issues, spawn another fresh Codex worker and tell
 it to read `/tmp/review-13.md`, fix the findings, run tests, and write
 an updated summary. Then review again with a fresh Claude instance.
 
-## Teaching your agents about harnex
+## Teaching agents about harnex
 
-Harnex ships skill files that tell AI agents how to use harnex
-commands. Install them globally so every session picks them up:
+Harnex ships its agent guidance in the CLI. No skill install or
+project-local docs are required:
 
 ```bash
-harnex skills install
+harnex agents-guide             # list all agent guide topics
+harnex agents-guide dispatch    # Fire and Watch lifecycle
+harnex agents-guide monitoring  # completion signals and polling
+harnex agents-guide naming      # session IDs and artifact names
 ```
 
-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`.
+Tell an agent to run `harnex --help` and then `harnex agents-guide`.
+The guides cover dispatch, chain implementation, buddies, monitoring,
+and naming conventions.
 
 ## Recipes
 
@@ -248,6 +247,7 @@ from the CLI:
 ```bash
 harnex recipes             # list all recipes
 harnex recipes show 01     # read one
+harnex agents-guide        # deeper agent-facing guidance
 ```
 
 - **Fire and Watch** (`harnex recipes show 01`) — send work to a

data/README.md

@@ -12,14 +12,17 @@ gem install harnex
 
 Requires **Ruby 3.x**. No other dependencies.
 
-Then install workflow skills into your repo so agents can use them:
+Then ask the CLI what to do next:
 
 ```bash
-harnex skills install
+harnex
+harnex --help
+harnex agents-guide
 ```
 
-This adds orchestration skills (harnex-dispatch, harnex-chain, harnex-buddy)
-that Claude Code and Codex pick up automatically.
+`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.
 
 ## What it does
 
@@ -90,19 +93,23 @@ harnex send --id cl-review --message "Review changes against /tmp/plan.md, write
 harnex stop --id cl-review
 ```
 
-Harnex ships workflow skills that automate this pattern:
+Harnex ships CLI-readable agent guides for this pattern:
 
-- **[Dispatch](skills/harnex-dispatch/SKILL.md)** — the fire-and-watch pattern:
+- **[Dispatch](guides/01_dispatch.md)** — the fire-and-watch pattern:
   spawn an agent, poll its screen, stop it when done
-- **[Chain](skills/harnex-chain/SKILL.md)** — end-to-end issue-to-code
+- **[Chain](guides/02_chain.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
+- **[Buddy](guides/03_buddy.md)** — spawn an accountability partner
   for long-running or overnight work
+- **[Monitoring](guides/04_monitoring.md)** — completion signals and
+  poll/watch patterns
+- **[Naming](guides/05_naming.md)** — session IDs, task files, done markers
 
-Install skills so agents can use them:
+Read them from the installed CLI:
 
 ```bash
-harnex skills install
+harnex agents-guide dispatch
+harnex agents-guide monitoring
 ```
 
 ## Built-in dispatch monitoring
@@ -110,7 +117,7 @@ harnex skills install
 For unattended dispatches, use `--watch` instead of writing a bash poll loop:
 
 ```bash
-harnex run codex --id cx-impl-42 --tmux cx-impl-42 --watch --preset impl \
+harnex run codex --id cx-impl-42 --watch --preset impl \
   --context "Implement koder/plans/42_plan.md. Run tests and commit when done."
 ```
 
@@ -208,19 +215,18 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 | `harnex events --id <id>` | Stream structured session events (`--snapshot` for non-blocking dump) |
 | `harnex wait --id <id>` | Block until exit or a target state |
 | `harnex guide` | Getting started walkthrough |
+| `harnex agents-guide` | Agent-facing dispatch, chain, buddy, monitoring, and naming guides |
 | `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`.
+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.
 
 ## Going deeper
 

data/TECHNICAL.md

@@ -321,7 +321,25 @@ The adapter reads the screen and returns a state hash:
 | `confirmation`           | `false`       | Modal confirmation    |
 | `unknown`                | `nil`         | Can't determine       |
 
-### Codex Adapter
+### Codex Adapter (default — JSON-RPC `app-server`)
+
+- `transport :stdio_jsonrpc` — speaks JSON-RPC 2.0 over the
+  subprocess's stdin/stdout, one JSON object per line.
+- Launches `codex app-server` (Codex CLI ≥ 0.128.0; verify with
+  `harnex doctor`).
+- Notifications (`turn/started`, `turn/completed`, `item/completed`,
+  `error`, `thread/compacted`, …) fan into the events log.
+  `task_complete` is the harnex-side event for `turn/completed`.
+- Disconnect is detected from JSON-RPC error responses, subprocess
+  EOF, parse errors, or a server `error` notification — no screen
+  regex required.
+- Synthesized transcript: `item/completed` text payloads stream to
+  both the output log and STDOUT so tmux/pane workflows continue to
+  work without a real PTY.
+- See `docs/codex-appserver.md` for the full mapping table and
+  troubleshooting.
+
+#### Codex Adapter (legacy PTY — `--legacy-pty`, removal in 0.7.0)
 
 - Launches with `--no-alt-screen` for inline screen output
 - Detects prompt by looking for `›` prefix in recent lines
@@ -557,77 +575,43 @@ Harnex uses Ruby threads, not processes:
 All shared state is protected by `Mutex`. The `SessionState`
 and `Inbox` classes use `ConditionVariable` for signaling.
 
-## Skill Files
+## Agent Guides
 
-Harnex ships bundled skills that teach agents the orchestration workflow and
-dispatch discipline. The canonical collaboration skill is:
+Harnex ships agent-facing guidance as Markdown files packaged inside the gem:
 
 ```
-skills/harnex-dispatch/SKILL.md
+guides/01_dispatch.md
+guides/02_chain.md
+guides/03_buddy.md
+guides/04_monitoring.md
+guides/05_naming.md
 ```
 
-### What's in the skill
-
-The dispatch skill tells agents:
-
-- How to detect they're inside a harnex session (env vars)
-- How to define return channels before delegation
-- How to send short, file-referenced tasks with explicit reply instructions
-- How to send messages, check status, spawn workers, and stop safely
-- How to use `--context`, `--force`, `--no-wait`
-- Relay header format and behavior
-- Collaboration patterns (reply, supervisor, file watch)
-- Safety rules (confirm before sending, no auto-loops)
-
-### How agents load skills
-
-Claude and Codex both support a `skills/` directory. When a
-skill is present, the agent can use harnex commands without
-being told how — the skill provides the instructions.
-
-Skill files use YAML frontmatter:
-
-```yaml
----
-name: harnex-dispatch
-description: Fire & Watch dispatch pattern...
-allowed-tools: Bash(harnex *)
----
-```
-
-The `allowed-tools` field grants the agent permission to run
-`harnex` commands without asking for approval each time.
-
-### Installing bundled skills
-
-Use the installer command instead of manual symlinks:
+The files are exposed through the CLI:
 
 ```bash
-harnex skills install            # all canonical skills
-harnex skills install harnex     # compatibility alias -> harnex-dispatch
-harnex skills install --local    # install into current repo only
+harnex agents-guide
+harnex agents-guide dispatch
+harnex agents-guide monitoring
 ```
 
-Compatibility aliases accepted by the installer:
-
-- `harnex` -> `harnex-dispatch`
-- `dispatch` -> `harnex-dispatch`
-- `chain-implement` -> `harnex-chain`
+### What's in the guides
 
-### Skill directory structure
+The agent guides cover:
 
-```
- ~/.claude/skills/
-   └── harnex-dispatch
-         └── SKILL.md
-
- ~/.codex/skills/
-   └── harnex-dispatch -> ~/.claude/skills/harnex-dispatch
-         └── SKILL.md
-```
+- Detecting harnex session context through environment variables
+- Defining return channels before delegation
+- Short prompts that reference task files
+- Relay header behavior for harnex-to-harnex messages
+- Fire and Watch dispatch lifecycle
+- Chain implementation phase gates
+- Buddy monitoring for unattended work
+- Completion signals, event/log/pane monitoring, and wall-clock caps
+- Session ID, task file, and done marker naming conventions
 
-Deprecated installed names (`harnex`, `dispatch`, `chain-implement`) are
-cleaned automatically during install and uninstall.
+Older releases shipped `harnex skills install`; that installer was removed in
+0.6.1. Agents now discover harnex directly with `harnex --help` and
+`harnex agents-guide`.
 
 ## Known Limitations
 

data/guides/01_dispatch.md

@@ -0,0 +1,139 @@
+# Dispatch: Fire and Watch
+
+Fire and Watch is the base harnex workflow for agent dispatch:
+
+1. Spawn one fresh worker.
+2. Send one scoped task.
+3. Watch for progress with harnex primitives.
+4. Verify the result.
+5. Stop the worker.
+
+Use this pattern for implementation, review, fix, mapping, and planning
+sessions. Compose larger workflows by repeating it with file handoffs.
+
+## Detect Your Context
+
+Inside a harnex-managed session, these environment variables are available:
+
+| Variable | Meaning |
+| --- | --- |
+| `HARNEX_SESSION_CLI` | Wrapped CLI name, such as `codex` or `claude` |
+| `HARNEX_ID` | Current harnex session ID |
+| `HARNEX_SESSION_REPO_ROOT` | Repo root for the session |
+| `HARNEX_SESSION_ID` | Internal harnex instance ID |
+| `HARNEX_SPAWNER_PANE` | Tmux pane ID of the invoker |
+
+Use `harnex send`, `harnex status`, `harnex wait`, `harnex pane`, and
+`harnex logs` to coordinate with peers. If you are not inside harnex,
+use a concrete return artifact such as a file path or a tmux pane message.
+
+## Return Channel First
+
+Decide how results come back before you delegate work.
+
+Inside harnex, instruct the peer to reply to your own session:
+
+```bash
+harnex send --id cx-i-NN --message "Read /tmp/task-impl-NN.md. When done, send one summary line back to harnex id $HARNEX_ID."
+```
+
+Outside harnex, require a file or another explicit return path:
+
+```bash
+harnex send --id cx-i-NN --message "Read /tmp/task-impl-NN.md. Write final status to /tmp/cx-i-NN-done.txt."
+```
+
+Do not delegate work without an explicit completion contract.
+
+## Spawn
+
+Launch worker sessions in tmux when a user or orchestrator may need to inspect
+them live:
+
+```bash
+harnex run codex --id cx-i-NN --tmux cx-i-NN \
+  --context "Implement the project plan in /tmp/task-impl-NN.md. Run tests when done."
+```
+
+For long prompts, write the details into a file and reference it. PTYs are more
+reliable with short injected messages.
+
+```bash
+harnex run codex --id cx-i-NN --tmux cx-i-NN \
+  --context "Read and execute /tmp/task-impl-NN.md"
+```
+
+Rule: when you use `--tmux`, pass the same name as `--id`. If you pass only
+`--tmux NAME`, harnex creates a random session ID and the pane name no longer
+matches `harnex status` or `harnex pane --id`.
+
+## Send
+
+Use `--message` for short instructions and file references:
+
+```bash
+harnex send --id cx-i-NN --message "Continue with /tmp/task-impl-NN.md. Report final status to $HARNEX_ID."
+```
+
+Use `--wait-for-idle` only as a turn fence. It proves that one send returned to
+an idle state; it is not a full work-completion signal.
+
+```bash
+harnex send --id cx-i-NN --message "Run the acceptance test." --wait-for-idle --timeout 900
+```
+
+Messages sent from one harnex session to another include a relay header:
+
+```text
+[harnex relay from=<cli> id=<sender_id> at=<timestamp>]
+<message body>
+```
+
+Treat relay messages as actionable prompts. Reply with `harnex send --id
+<sender_id> ...` unless the sender provided a different return path.
+
+## Watch
+
+Use the lightest primitive that gives the signal you need:
+
+| Need | Command |
+| --- | --- |
+| Current live screen | `harnex pane --id cx-i-NN --lines 40` |
+| Continuous pane view | `harnex pane --id cx-i-NN --follow` |
+| Transcript tail | `harnex logs --id cx-i-NN --lines 80` |
+| Structured events | `harnex events --id cx-i-NN --snapshot` |
+| Native turn completion | `harnex wait --id cx-i-NN --until task_complete` |
+
+For unattended policy-only stall recovery, use built-in watch mode:
+
+```bash
+harnex run codex --id cx-i-NN --watch --preset impl --context "Read /tmp/task-impl-NN.md"
+```
+
+`--watch` is foreground-blocking. Use it when a single process should launch
+and monitor the worker. Use pane/log/event polling or a buddy when you need
+interpretation, multiple sessions, or a separate watcher.
+
+## Verify And Stop
+
+Before stopping a worker, verify the expected artifact, test result, commit,
+or review output exists:
+
+```bash
+harnex pane --id cx-i-NN --lines 60
+git status --short
+git log --oneline -5
+harnex stop --id cx-i-NN
+```
+
+Stop completed sessions promptly. Fresh workers are easier to reason about
+than reused workers with stale context.
+
+## Recipes
+
+For compact command recipes, use:
+
+```bash
+harnex recipes show 01
+harnex recipes show fire
+```

data/guides/02_chain.md

@@ -0,0 +1,113 @@
+# Chain Implementation
+
+Chain implementation is Fire and Watch repeated with phase gates. It takes an
+issue or request through planning, review, implementation, review, fixes, and
+release without reusing long-lived worker context.
+
+## Roles
+
+Keep roles explicit:
+
+| Role | Responsibility |
+| --- | --- |
+| Orchestrator | Dispatches sessions, watches progress, enforces gates |
+| Worker | Performs scoped production work in a fresh session |
+| Reviewer | Reviews one artifact or change set and writes findings |
+| Fixer | Addresses review findings in a fresh session |
+
+The orchestrator may be a human or an agent. It should not quietly skip review
+gates, guess around user-blocking questions, or keep piling work into one
+worker after the scope changes.
+
+## Default Serial Flow
+
+Use this serial flow for most work:
+
+```text
+Issue or request
+  -> optional mapping
+  -> plan
+  -> plan review
+  -> plan fix if needed
+  -> implement
+  -> code review
+  -> code fix if needed
+  -> verify
+  -> release or handoff
+```
+
+Each arrow is a fresh harnex worker when delegated. Pass state through files:
+the issue, plan, review file, fix summary, test log, or done marker.
+
+## Per-Plan Loop
+
+For each independently testable plan:
+
+1. Start a planner only if the plan does not already exist or needs revision.
+2. Start a reviewer for the plan.
+3. Start a fixer if the review finds blocking issues.
+4. Start an implementation worker.
+5. Start a code reviewer.
+6. Start a code fixer if needed.
+7. Verify tests and state.
+8. Commit or tag only after the gate passes.
+
+Do not start implementation with unresolved blocking plan-review findings. Do
+not advance to the next plan with unresolved blocking code-review findings.
+
+## Parallel Variant
+
+Parallelism is safest in planning and review phases, because those steps can
+write separate artifacts. Keep implementation serial on the main working tree
+unless the user explicitly asks for parallel implementation and you create
+isolated worktrees.
+
+Recommended limits:
+
+| Lane | Default |
+| --- | --- |
+| Planning | Parallel allowed |
+| Plan review | Parallel allowed |
+| Implementation | Serial unless worktrees are explicit |
+| Code review/fix | Serial per implementation |
+
+When parallelizing, cap the number of active workers to what the machine and
+CLI provider can handle. A practical upper bound is five Codex sessions across
+all active lanes unless the user requested more.
+
+## Worktrees
+
+Use worktrees only when they solve a real isolation problem. Commit or otherwise
+make every needed artifact available before creating the worktree, because
+untracked files do not carry over.
+
+```bash
+git worktree add ../project-plan-NN -b plan/NN main
+cd ../project-plan-NN
+harnex run codex --id cx-i-NN --tmux cx-i-NN \
+  --context "Read the project plan and implement this isolated lane."
+```
+
+Launch and manage the harnex session from the same repo root or pass `--repo`
+when needed. Use `harnex status --all` to inspect sessions across worktrees.
+
+## Failure And Escalation
+
+Escalate instead of guessing when:
+
+- A review asks a user-blocking question.
+- A worker diverges materially from the plan.
+- The working tree is dirty in unexpected files.
+- The same gate fails repeatedly.
+- Monitoring hits the wall-clock cap.
+
+Fix loops are useful only while the review finding is concrete and the worker
+has enough context to address it.
+
+## Recipe
+
+For a compact command walkthrough, use:
+
+```bash
+harnex recipes show 02
+```