harnex 0.2.0

data/lib/harnex/watcher/polling.rb

@@ -0,0 +1,92 @@
+module Harnex
+  module Polling
+    POLL_INTERVAL = 0.5
+
+    class << self
+      def available?
+        true
+      end
+
+      def directory_io(path, _events)
+        PollingIO.new(path)
+      end
+    end
+
+    class PollingIO
+      EVENT_HEADER_SIZE = 16
+
+      def initialize(dir_path)
+        @dir_path = dir_path
+        @snapshots = take_snapshot
+        @closed = false
+      end
+
+      def readpartial(_maxlen)
+        raise IOError, "closed stream" if @closed
+
+        loop do
+          sleep POLL_INTERVAL
+          raise IOError, "closed stream" if @closed
+
+          current = take_snapshot
+          changed = detect_changes(@snapshots, current)
+          @snapshots = current
+          next if changed.empty?
+
+          return encode_events(changed)
+        end
+      end
+
+      def close
+        @closed = true
+      end
+
+      def closed?
+        @closed
+      end
+
+      private
+
+      def take_snapshot
+        entries = {}
+        Dir.foreach(@dir_path) do |name|
+          next if name == "." || name == ".."
+
+          path = File.join(@dir_path, name)
+          stat = File.stat(path)
+          entries[name] = { mtime: stat.mtime, size: stat.size }
+        rescue Errno::ENOENT, Errno::EACCES
+          nil
+        end
+        entries
+      rescue Errno::ENOENT, Errno::EACCES
+        {}
+      end
+
+      def detect_changes(old_snap, new_snap)
+        changed = []
+        new_snap.each do |name, info|
+          prev = old_snap[name]
+          if prev.nil? || prev[:mtime] != info[:mtime] || prev[:size] != info[:size]
+            changed << name
+          end
+        end
+        changed
+      end
+
+      def encode_events(names)
+        buf = +""
+        buf.force_encoding(Encoding::BINARY)
+        names.each do |name|
+          name_bytes = name.encode(Encoding::BINARY)
+          padded_len = (name_bytes.bytesize + 4) & ~3
+          # inotify event header: wd(int) + mask(uint) + cookie(uint) + len(uint)
+          buf << [0, Harnex::Inotify::IN_CLOSE_WRITE, 0, padded_len].pack("iIII")
+          buf << name_bytes
+          buf << ("\0" * (padded_len - name_bytes.bytesize))
+        end
+        buf
+      end
+    end
+  end
+end

data/lib/harnex/watcher.rb

@@ -0,0 +1,24 @@
+require_relative "watcher/inotify"
+require_relative "watcher/polling"
+
+module Harnex
+  module Watcher
+    module_function
+
+    def available?
+      true
+    end
+
+    def directory_io(path, events)
+      if Inotify.available?
+        Inotify.directory_io(path, events)
+      else
+        Polling.directory_io(path, events)
+      end
+    end
+
+    def backend
+      Inotify.available? ? :inotify : :polling
+    end
+  end
+end

data/lib/harnex.rb

@@ -0,0 +1,25 @@
+require "fileutils"
+require "json"
+require "open3"
+
+require_relative "harnex/version"
+require_relative "harnex/core"
+require_relative "harnex/watcher"
+require_relative "harnex/adapters"
+require_relative "harnex/runtime/session_state"
+require_relative "harnex/runtime/message"
+require_relative "harnex/runtime/inbox"
+require_relative "harnex/runtime/file_change_hook"
+require_relative "harnex/runtime/api_server"
+require_relative "harnex/runtime/session"
+require_relative "harnex/commands/run"
+require_relative "harnex/commands/send"
+require_relative "harnex/commands/wait"
+require_relative "harnex/commands/stop"
+require_relative "harnex/commands/status"
+require_relative "harnex/commands/logs"
+require_relative "harnex/commands/pane"
+require_relative "harnex/commands/recipes"
+require_relative "harnex/commands/guide"
+require_relative "harnex/commands/skills"
+require_relative "harnex/cli"

data/recipes/01_fire_and_watch.md

@@ -0,0 +1,82 @@
+# Recipe: Fire and Watch
+
+This is the core harnex recipe.
+
+Spawn a fresh worker, send it one task, watch its screen until it
+is done, capture the result, stop it. Compose bigger workflows by
+repeating this pattern with file handoffs between steps.
+
+## Steps
+
+### 1. Spawn the worker
+
+```bash
+harnex run codex --id cx-23 --tmux
+```
+
+### 2. Send the task
+
+If the plan file is self-contained, reference it directly:
+
+```bash
+harnex send --id cx-23 --message "Implement koder/plans/plan_23.md. Run tests when done." --wait-for-idle --timeout 1200
+```
+
+For tasks that need structured output, tell the worker to write a
+file and inspect the screen separately:
+
+```bash
+cat > /tmp/task-cx-23.md <<'EOF'
+Implement koder/plans/plan_23.md.
+Run the full test suite when done.
+Write a short summary to /tmp/impl-23.md.
+EOF
+
+harnex send --id cx-23 --message "Read and execute /tmp/task-cx-23.md" --wait-for-idle --timeout 1200
+```
+
+### 3. Watch until done
+
+Use `--wait-for-idle` as the fence, then read the worker's screen:
+
+```bash
+harnex pane --id cx-23 --lines 25
+```
+
+If you prefer to watch while it runs:
+
+```bash
+harnex pane --id cx-23 --follow
+```
+
+When the worker looks idle, capture a larger snapshot:
+
+```bash
+harnex pane --id cx-23 --lines 80
+```
+
+### 4. Stop the worker
+
+```bash
+harnex stop --id cx-23
+```
+
+Start a fresh worker for the next step instead of reusing this one.
+
+## Common step types
+
+Use the same pattern for every role:
+
+- Codex planning: "Write the plan to `/tmp/plan-23.md`. Do not change code."
+- Codex implementation: "Read `/tmp/plan-23.md`, implement it, run tests, write `/tmp/impl-23.md`."
+- Claude review: "Review current changes against `/tmp/plan-23.md` and write findings to `/tmp/review-23.md`."
+- Codex fix: "Read `/tmp/review-23.md`, fix the issues, run tests, write `/tmp/fix-23.md`."
+
+## Rationale
+
+This is the dependable path because it minimizes the fragile parts:
+
+- Fresh worker per step avoids context bleed and stale inbox state
+- File artifacts are easier to pass between steps than callback messages
+- `harnex pane` shows the truth even when the worker ignores reply instructions
+- Stopping the worker after each step keeps the workflow disposable

data/recipes/02_chain_implement.md

@@ -0,0 +1,115 @@
+# Recipe: Chain Implement
+
+This is repeated fire-and-watch for a batch of jobs.
+
+Process plans in series. For each plan, use fresh instances for
+every step:
+
+- Codex plans or implements
+- Claude reviews
+- Codex fixes
+- Repeat review and fix until clean, then move to the next plan
+
+## Trigger
+
+User says something like:
+- "implement plans 23 to 27, review each, fix issues"
+- "implement plans 23 to 27, use fresh Codex for implementation
+  and fresh Claude for review on every plan"
+
+## Procedure
+
+For each plan in the batch:
+
+### Step 1: Plan or confirm the plan
+
+If the plan file does not already exist or needs refinement, spawn a
+fresh Codex planner and tell it to write a plan artifact.
+
+```bash
+harnex run codex --id cx-plan-23 --tmux
+harnex send --id cx-plan-23 --message "Write a concrete implementation plan for plan 23 to /tmp/plan-23.md. Do not change code." --wait-for-idle --timeout 600
+```
+
+Inspect with `harnex pane --id cx-plan-23 --lines 60`, then stop it.
+
+If the plan is already written and trusted, skip this step and use the
+existing plan file directly.
+
+### Step 2: Implement
+
+Spawn a fresh Codex worker, send it the plan, watch it, stop it.
+
+```bash
+harnex run codex --id cx-impl-23-r1 --tmux
+harnex send --id cx-impl-23-r1 --message "Read /tmp/plan-23.md, implement it, run tests, and write a summary to /tmp/impl-23-r1.md." --wait-for-idle --timeout 1200
+```
+
+Inspect with `harnex pane --id cx-impl-23-r1 --lines 80`, then stop it.
+
+### Step 3: Review
+
+Spawn a fresh Claude reviewer. Claude is only used for reviews in this
+recipe.
+
+```bash
+harnex run claude --id cl-rev-23-r1 --tmux
+harnex send --id cl-rev-23-r1 --message "Review the current changes against /tmp/plan-23.md. Write findings to /tmp/review-23-r1.md. If there are no issues, say clean." --wait-for-idle --timeout 900
+```
+
+Inspect with `harnex pane --id cl-rev-23-r1 --lines 80`, then stop it.
+
+### Step 4: Fix and repeat if needed
+
+If the review is clean, move to the next plan.
+
+If the review finds issues, spawn a fresh Codex fixer:
+
+```bash
+harnex run codex --id cx-fix-23-r1 --tmux
+harnex send --id cx-fix-23-r1 --message "Read /tmp/review-23-r1.md, fix every issue, run tests, and write a summary to /tmp/fix-23-r1.md." --wait-for-idle --timeout 1200
+```
+
+Inspect with `harnex pane --id cx-fix-23-r1 --lines 80`, then stop it.
+
+Then spawn another fresh Claude reviewer and repeat the review and fix
+loop until clean or until you decide the plan needs manual attention.
+
+### Step 5: Next plan
+
+Move to plan 24. Repeat from step 1.
+
+## Naming convention
+
+Use the plan number in every worker ID so you can tell them apart in
+`harnex status`:
+
+ | Step      | ID pattern        | Example          |
+ | ---       | ---               | ---              |
+ | Plan      | `cx-plan-NN`      | `cx-plan-23`     |
+ | Implement | `cx-impl-NN-rM`   | `cx-impl-23-r1`  |
+ | Review    | `cl-rev-NN-rM`    | `cl-rev-23-r1`   |
+ | Fix       | `cx-fix-NN-rM`    | `cx-fix-23-r1`   |
+
+## Notes
+
+- Each step uses a fresh instance. Don't reuse a worker across
+  steps or rounds. A clean context avoids bleed between plan,
+  implement, review, and fix.
+- The batch is serial. Finish plan 23 completely before starting
+  plan 24. Plans often build on each other.
+- Claude only reviews. Do not use Claude as the planner or fixer in
+  this recipe.
+- Pass artifacts between steps as files (`/tmp/plan-23.md`,
+  `/tmp/review-23-r1.md`), not as harnex reply messages.
+- If the review finds no issues, skip the fix step and move on.
+
+## Rationale
+
+This recipe is not a different control model. It is just
+fire-and-watch repeated with stronger discipline:
+
+- one worker per step
+- one artifact per handoff
+- one reviewer role, always Claude
+- one serial job stream, so later plans see earlier fixes

data/skills/chain-implement/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: chain-implement
+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.
+---
+
+# Chain Implement
+
+Take an issue from design through to shipped code via harnex agents. Designed
+so the user can walk away after triggering the chain.
+
+## Guiding Principle
+
+Keep each agent invocation inside its **safe context zone** (< 40% of context
+window). Agents produce their smartest work when they aren't overloaded. Large
+issues get split into smaller plans because massive plans degrade agent output.
+
+**Scale the process to the work:**
+- Small issue, one coherent change → skip mapping, write one plan, implement
+- Medium issue, a few moving parts → one plan with phases is fine
+- Large issue, many files/seams/sequencing → mapping plan + extracted plans
+
+The phases below describe the **full** workflow. Skip phases that aren't needed.
+
+## Workflow Overview
+
+```
+Issue (user + agent chat)
+  ↓
+[Mapping Plan] → [Map Review] → [Fix Map]     ← skip if scope is small
+  ↓
+[Plan Extraction] → thin-layer plans           ← skip if one plan suffices
+  ↓
+Per plan (serial):
+  Plan (codex) → Plan Review (claude) → Fix Plan (codex)
+    → Implement (codex) → Code Review (claude) → Fix Code (codex)
+    → Commit → next plan
+```
+
+### Why two review phases?
+
+The plan review catches design problems before code is written. The code review
+catches implementation problems after. Skipping plan review leads to wasted
+implementation cycles when the plan itself is flawed. This was validated in
+production — adversarial plan/review cycles consistently produce better outcomes
+than jumping straight to implementation.
+
+## Phase 1: Issue
+
+The user and the agent have a detailed design chat. From that, a structured
+issue is filed (e.g., `koder/issues/NN_label/INDEX.md`).
+
+The issue captures:
+- The problem and motivation
+- Design decisions and trade-offs
+- Acceptance criteria
+- Known open questions
+
+This phase is interactive — the user is present and driving.
+
+## Phase 2: Mapping Plan (optional — for large issues)
+
+Skip if the issue is small enough for a single implementation plan. Use when
+the scope crosses many files, involves sequencing constraints, or has open
+design questions that would block an away user.
+
+A **mapping plan** doesn't produce code. It produces a detailed technical map:
+- Exact files, functions, and seams involved
+- Sequencing constraints (what depends on what)
+- Questions that need user input before implementation
+
+### Why mapping is its own phase
+
+- **Surfaces blockers early** — user-blocking decisions come out here, not
+  halfway through implementation
+- **Creates shared context** — the mapping plan becomes the reference for all
+  subsequent plans
+- **Separates research from decomposition** — mapping agent focuses on
+  understanding, extraction focuses on scoping
+
+### Dispatch
+
+```bash
+harnex run codex --id cx-map-NN --tmux cx-map-NN \
+  --context "Write a mapping plan for koder/issues/NN_label/INDEX.md. \
+Produce a detailed technical map: files, seams, sequencing, open questions. \
+Write to koder/plans/NN_mapping.md."
+```
+
+Poll every 30s with `harnex pane --id cx-map-NN --lines 20`.
+
+### Map Review
+
+```bash
+harnex run claude --id cl-rev-map-NN --tmux cl-rev-map-NN \
+  --context "Review koder/plans/NN_mapping.md. Check: unresolved user questions? \
+Accurate file/function analysis? Sequencing constraints identified? \
+Write review to koder/reviews/NN_mapping.md"
+```
+
+**If user-blocking questions exist**, stop the chain and surface them.
+
+## Phase 3: Plan Extraction (optional)
+
+Skip if the mapping plan describes one coherent change, or if you skipped
+mapping entirely.
+
+Extract thin-layer implementation plans from the mapping plan. Each plan is:
+- **One capability** — testable independently
+- **Self-contained** — the implementing agent reads only that plan file
+- **Ordered** — respects sequencing constraints from the mapping plan
+
+```bash
+harnex run codex --id cx-extract-NN --tmux cx-extract-NN \
+  --context "Read koder/plans/NN_mapping.md. Extract thin-layer plans. \
+Each plan is one independently testable capability. Write to koder/plans/."
+```
+
+## Phase 4: Serial Plan Loop
+
+Each plan goes through the full cycle. This is the walk-away part.
+
+### Per-plan cycle
+
+```
+1. Plan (codex)        — write/refine the plan if not already extracted
+2. Plan Review (claude) — check plan against codebase, flag issues
+3. Fix Plan (codex)    — address review findings
+4. Implement (codex)   — write code, run tests, commit per phase
+5. Code Review (claude) — review implementation against plan
+6. Fix Code (codex)    — address review findings if needed
+7. Commit              — final state on master
+8. → next plan
+```
+
+Steps 1-3 can be skipped if the plan was already extracted and reviewed during
+the mapping phase, or if the issue is simple enough that the plan is obviously
+correct.
+
+### Dispatch pattern
+
+For each plan NN, use the Fire & Watch pattern from the `dispatch` skill:
+
+```bash
+# Steps 1-3: Plan convergence (skip if plan already extracted and reviewed)
+harnex run codex --id cx-plan-NN --tmux cx-plan-NN \
+  --context "Refine koder/plans/NN_label.md based on current codebase state."
+# Poll every 30s: harnex pane --id cx-plan-NN --lines 20
+# When done: harnex stop --id cx-plan-NN
+
+harnex run claude --id cl-rev-plan-NN --tmux cl-rev-plan-NN \
+  --context "Review koder/plans/NN_label.md. Check: accurate file/function refs? \
+Sequencing correct? Acceptance criteria testable? \
+Write review to koder/reviews/NN_label.md"
+# Poll → stop → if NEEDS FIXES, dispatch cx-fix-plan-NN
+
+# Step 4: Implement
+harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
+  --context "Implement koder/plans/NN_label.md. Run tests when done. Commit after each phase."
+# Poll every 30s: harnex pane --id cx-impl-NN --lines 20
+# When done: harnex stop --id cx-impl-NN
+
+# Steps 5-6: Code review + fix
+harnex run claude --id cl-rev-NN --tmux cl-rev-NN \
+  --context "Review implementation of plan NN against koder/plans/NN_label.md. \
+Write review to koder/reviews/NN_label.md"
+# Poll every 30s: harnex pane --id cl-rev-NN --lines 20
+# When done: harnex stop --id cl-rev-NN
+# If NEEDS FIXES → dispatch cx-fix-NN
+# If PASS → next plan
+
+# Fix (if needed)
+harnex run codex --id cx-fix-NN --tmux cx-fix-NN \
+  --context "Fix findings in koder/reviews/NN_label.md for plan NN. Run tests. Commit."
+# Poll, stop, re-review if needed
+```
+
+### Poll cadence
+
+Checking is cheap — 20 lines is a few hundred bytes:
+
+| Elapsed | Interval | Rationale |
+|---------|----------|-----------|
+| 0–2 min | 30s | Catch fast completions and early errors |
+| 2–10 min | 60s | Steady state for typical work |
+| 10+ min | 120s | Long-running, reduce noise |
+
+```bash
+harnex pane --id cx-impl-NN --lines 20
+```
+
+### Naming conventions
+
+| Step | ID pattern | Example |
+|------|-----------|---------|
+| Mapping plan | `cx-map-NN` | `cx-map-42` |
+| Map review | `cl-rev-map-NN` | `cl-rev-map-42` |
+| Plan extraction | `cx-extract-NN` | `cx-extract-42` |
+| Plan write/refine | `cx-plan-NN` | `cx-plan-184` |
+| Plan review | `cl-rev-plan-NN` | `cl-rev-plan-184` |
+| Plan fix | `cx-fix-plan-NN` | `cx-fix-plan-184` |
+| Implement | `cx-impl-NN` | `cx-impl-184` |
+| Code review | `cl-rev-NN` | `cl-rev-184` |
+| Code fix | `cx-fix-NN` | `cx-fix-184` |
+
+**Rule**: Fresh instance per step. Don't reuse agents across steps — clean
+context avoids bleed.
+
+## Worktree Option
+
+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.
+
+## When Things Go Wrong
+
+**Plan review finds user-blocking question**: Stop the chain. Surface the
+question. Resume after the user answers. This is exactly what the plan review
+phase is for — catching these before implementation begins.
+
+**Plan review finds P1**: Dispatch a plan fix agent (`cx-fix-plan-NN`).
+Re-review the plan. Do not proceed to implementation with unresolved P1s.
+
+**Code review finds P1**: Dispatch a code fix agent (`cx-fix-NN`). Re-review
+after fix. Do not skip to the next plan with unresolved P1s.
+
+**Implementation diverges from plan**: The implementer may discover the plan
+is wrong. If the divergence is minor (P3), note it and continue. If major,
+stop and re-plan.
+
+**Agent gets stuck**: Check `harnex pane --lines 20`. If blocked on a
+permission prompt or trust dialog, intervene. If confused, stop the agent and
+dispatch a fresh one with clearer instructions.

data/skills/close/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: close
+description: Close a work session in this repo — update koder/STATE.md with what changed and the next step, clean up accidental or temporary repo artifacts, and leave a clear handoff. Use when the user says "close session", "wrap up", "end session", "handoff", or invokes "/close".
+---
+
+# Close Session Workflow
+
+When the user asks to wrap up or close the current session, run this sequence:
+
+## 1. Review the session changes
+
+- Check `git status --short` and `git diff --stat`
+- Separate the work from this session from unrelated user changes
+- Do not revert unrelated changes you did not make
+
+## 2. Update `koder/STATE.md`
+
+- Update the `Updated:` date
+- Add or adjust concise lines in `Current snapshot` for completed work
+- Update test count if it changed
+- Update issue or plan statuses only when work was actually completed or a new blocker was clearly discovered
+- Rewrite `Next step` so the next agent can resume without reconstructing context
+
+## 3. Clean up repo artifacts
+
+- Remove temporary files, scratch notes, or mistaken tracking docs created during the session
+- Keep durable artifacts that are part of the intended result
+- If cleanup would discard ambiguous work, ask the user instead of guessing
+
+## 4. Commit and clean the repo
+
+- Stage all session changes (code, docs, STATE.md updates) and commit with a clear message summarizing the session's work
+- Do NOT stage files that look like secrets, credentials, or large binaries — flag them to the user
+- After committing, run `git status --short` to confirm a clean working tree
+- If unrelated uncommitted changes remain, leave them alone — do not revert or commit work you did not produce
+
+## 5. Verify the handoff
+
+- Run the relevant tests or verification commands if code or docs changed
+- Give the user a concise summary of what changed, the commit, and any remaining follow-up
+- The goal: the next `/open` should see a clean repo and an accurate `koder/STATE.md`
+
+## Notes
+
+- Do NOT create or close issue docs unless the user explicitly asks
+- Do NOT build, install, or publish anything unless the user explicitly asks
+- If `koder/STATE.md` is already accurate, keep the update minimal rather than churning it