harnex 0.6.5 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 297484ce749d268b7582afd226d617c79fed80a12928ced5daa8df2c3bd4f763
-  data.tar.gz: 554528411e6bca5c6037ca579067f37b4b58626b88ed5c263fe95debe4517f70
+  metadata.gz: 315057f04a626949bd270491616595e98d3d298a4b49aa7d70d23aa0cda0501d
+  data.tar.gz: 06c539f5911aa58fa427c80570ca7998ce382d6077a015ae8dc4d181cf05a00f
 SHA512:
-  metadata.gz: 1aa029fe0d4177ef1a9043c863935655df9b636b48bedaad3f84d35e6d02d0b9255b16ce2c08a5220f2eb4b89930fe0002b2926c47039b7cb1eeab2a6e333b07
-  data.tar.gz: ab908f0f299a9a0ae286cf629202fa26d518f59658518515818c388f21daadbd42a4a839417878a99c3f863439df5d11dd51cdf7c3675b737638293b5c739832
+  metadata.gz: 15b5c96adb86810626229e9d037992cce4566d8aee83856870735f9e28c8e61b63f567d6af18a946b98f9696b2387f9e6b1b77d65659989c749db5eb7de6ef1b
+  data.tar.gz: cdf1b6b3ce3c1934fd768b983df7db3e7aa296abd83e3c926d0a1b7760a5ff1cb9d433742b8edd15740ced1c0dc735d8027c6849eb474fa5049d73ae4246c5b2

data/CHANGELOG.md

@@ -2,6 +2,144 @@
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-05-13 | 01:43 PM | IST
+
+### Added
+
+- `harnex run codex --fast` now opts Codex app-server runs into
+  `service_tier="fast"`. Default Codex runs now inject
+  `service_tier="flex"` unless the child CLI args already supply an
+  explicit `service_tier` config.
+- First-class `opencode` PTY adapter. `harnex run opencode` now uses
+  `Harnex::Adapters::Opencode` instead of the generic fallback, with
+  an OpenCode-specific stop sequence (double Ctrl+C), repo path
+  inference (`--dir` or positional project path), and session-id
+  extraction from transcript tails (`Continue opencode -s ...`).
+
+### Changed
+
+- `harnex run` now rejects unknown long flags before spawning the
+  agent process, with a clear error pointing at `harnex run --help`.
+  Anything past the `--` separator continues to forward unchanged
+  to the agent CLI. Closes the trigger that correlated with the F23
+  auto-stop teardown leak. Closes harnex issue #38.
+- Codex app-server contract fixtures are refreshed against
+  `codex-cli 0.130.0`; response builders now include the required
+  `thread.sessionId` field.
+- Internal Codex app-server code now has the extracted
+  `Harnex::Codex::AppServer::Client` namespace and the subprocess
+  restart primitive needed by the deployment-fallback plan. No
+  public fallback CLI flag is exposed yet.
+
+### Fixed
+
+- `harnex run` now defaults dispatch summaries to
+  `<repo>/.harnex/dispatch.jsonl` for every resolved repo, regardless
+  of whether a legacy `koder/` directory exists. Closes harnex issue
+  #39.
+- `harnex run` with `--auto-stop` now exits within a bounded grace
+  (default 5s, override via `HARNEX_AUTOSTOP_TEARDOWN_GRACE_SECONDS`)
+  after `task_complete`. Closes a leak where the wrapping Ruby parent
+  process could sleep on `futex_wait_queue` indefinitely during
+  teardown, surviving as `orphan_tmux` until manually swept (F09
+  detected; F23 remediates). Closes harnex issue #37.
+
+## [0.7.2] - 2026-05-08
+
+### Fixed
+
+- `harnex run` now resolves the repo-local
+  `<repo>/.harnex/dispatch.jsonl` write path from the supervisor's
+  launch cwd (captured at invocation time), not from the agent's
+  runtime cwd. Closes a regression where cross-repo dispatches
+  (supervisor in repo A, agent `cd`'s into repo B) wrote their
+  terminal row only to the global fallback, never to repo A.
+
+### Added
+
+- `harnex doctor --sweep` reports read-only harnex/tmux session drift,
+  including active registry rows, matching `cx-*` tmux windows, orphan
+  tmux windows, and stale session log files whose owning pid is gone.
+
+## [0.7.1] - 2026-05-08
+
+### Fixed
+
+- `harnex run --auto-stop` now observes the terminal `task_complete`
+  event after the agent subprocess exits before tearing down, closing
+  a race where one-shot dispatches could report `timeout` even when
+  the agent finished the task cleanly. Adds a regression test that
+  exercises the post-exit event drain path.
+
+- `harnex wait` predicates now classify dispatch progress by
+  structured event-record fields instead of regex-matching the
+  human-readable transcript, with the prior exact-marker text as a
+  legacy fallback. Eliminates a class of spurious matches where
+  prose containing a marker word was misread as a state transition.
+
+### Added
+
+- Dispatch summaries now preserve declared brief budget metadata
+  (`read_budget_lines`, `output_ceiling_lines`) from `--meta` and
+  record rough terminal measurements (`lines_changed`, `output_lines`,
+  `output_bytes`, `event_records`) for downstream budget enforcement.
+
+## [0.7.0] - 2026-05-08
+
+### Added
+
+- `harnex run` now appends one terminal dispatch record to
+  `<repo>/.harnex/dispatch.jsonl`, falling back to
+  `~/.local/state/harnex/dispatch.jsonl` outside git repos. New
+  `harnex history` reads that log with `--limit`, `--since`, `--id`,
+  `--global`, `--json`, and `--all` filters.
+- DISPATCH row `actual` now includes `turn_count`, `tool_calls`,
+  `commands_executed`, `rate_limits`, `output_log_path`, and
+  `events_log_path` — surfacing data harnex already tracked but did
+  not persist. `meta.parent_dispatch_id` now auto-derives from
+  `$HARNEX_ID` when not supplied via `--meta`. (#35 Tier 2)
+- DISPATCH row `meta.agent_provider` and `meta.agent_version` now
+  populated. `provider` is a per-adapter constant
+  (claude → `anthropic`, codex → `openai`, generic → nil).
+  `agent_version` lazily probes `<base_command.first> --version`
+  with a 2s timeout, memoizes per adapter, and falls back to nil if
+  the binary is missing or stalls. (#35 Tier 3)
+
+### Removed
+
+- DISPATCH row dropped four always-null fields with no code path
+  populating them: `actual.cost_usd`, `actual.tests_run`,
+  `actual.tests_passed`, `actual.tests_failed`, and
+  `meta.agent_deployment`. Cost computation belongs to downstream
+  consumers (per-model rate tables change frequently); test-result
+  aggregation belongs to CI integrations, not the harness; and the
+  `agent_deployment` concept had no source of truth. JSON Lines
+  consumers should update column readers — schema is now stable but
+  smaller. (#35 Tier 3)
+
+### Fixed
+
+- `harnex wait` (default exit-watch mode) now blocks until the
+  exit-status file is on disk after the agent subprocess dies, with
+  a 5s grace bound (override via `HARNEX_EXIT_STATUS_GRACE_SECONDS`).
+  The exit-status file is written *after* the DISPATCH row in the
+  parent's teardown ensure block, so its presence guarantees the row
+  is on disk. Closes the race where `wait` could return between
+  `Process.wait2` unblocking and `Session#finalize_session!`
+  appending the row, which made dispatch-poll orchestrators flake
+  on "missing telemetry". (#36)
+
+### Changed
+
+- `koder/STATE.md` is now a thin past / present / future handoff
+  instead of a long-running project history. Durable change history
+  belongs in `CHANGELOG.md`, release verification in `koder/releases/`,
+  and issue or implementation detail in `koder/issues/` or
+  `koder/plans/`.
+- Agent orientation and the repo-local `open` / `close` skills now
+  explicitly tell future sessions to keep `STATE.md` concise and route
+  detailed notes to the durable tracking document that owns them.
+
 ## [0.6.5] — 2026-05-07
 
 ### Added

data/README.md

@@ -2,15 +2,18 @@
 
 Run multiple AI coding agents from your terminal and coordinate them.
 
-Harnex wraps Claude Code and OpenAI Codex (or any terminal CLI) in a
-local harness so you can launch agents, send them tasks, watch their
-screens, and stop them cleanly — all from the command line.
+Harnex wraps Claude Code, OpenAI Codex, or any terminal CLI in a local
+harness so you can launch agents, send them tasks, watch live panes or
+transcripts, and stop them cleanly — all from the command line.
 
 ```bash
 gem install harnex
 ```
 
-Requires **Ruby 3.x**. No other dependencies.
+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**, and tmux-backed
+workflows require `tmux`.
 
 Then ask the CLI what to do next:
 
@@ -20,6 +23,9 @@ harnex --help
 harnex agents-guide
 ```
 
+If you use Codex, run `harnex doctor` after installing or upgrading the
+Codex CLI. It verifies the local `codex app-server` prerequisite.
+
 `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.
@@ -28,7 +34,7 @@ or project-local docs are required.
 
 ```bash
 # Start an agent in tmux
-harnex run codex --id planner --tmux
+harnex run codex --id planner --tmux planner
 
 # Send it a task and wait for it to finish
 harnex send --id planner --message "Write a plan to /tmp/plan.md" --wait-for-idle
@@ -50,7 +56,8 @@ job, watch it work, stop it when done.
   findings. Each step is a fresh agent with clean context.
 
 - **You want to see what agents are doing.** `harnex pane` shows
-  the agent's live terminal. No black boxes.
+  a tmux-backed agent's live terminal, or Codex's synthesized
+  JSON-RPC transcript. No black boxes.
 
 - **You don't want to babysit.** Send a task with `--wait-for-idle`,
   walk away, check back when it's done.
@@ -68,9 +75,19 @@ job, watch it work, stop it when done.
 
 | Agent | Support |
 |-------|---------|
-| Claude Code | Full (prompt detection, stop sequence, vim mode) |
-| OpenAI Codex | Full (prompt detection, stop sequence) |
-| Any terminal CLI | Generic wrapping (everything works except smart prompt detection) |
+| 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; `--legacy-pty` remains supported for TUI/interactive PTY use |
+| 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 legacy PTY flag behavior.
 
 ## Multi-agent workflows
 
@@ -78,21 +95,24 @@ The real power is chaining agents together:
 
 ```bash
 # 1. Codex writes a plan
-harnex run codex --id cx-plan --tmux
+harnex run codex --id cx-plan --tmux cx-plan
 harnex send --id cx-plan --message "Plan the auth module, write to /tmp/plan.md" --wait-for-idle
 harnex stop --id cx-plan
 
 # 2. Fresh Codex implements the plan
-harnex run codex --id cx-impl --tmux
+harnex run codex --id cx-impl --tmux cx-impl
 harnex send --id cx-impl --message "Implement /tmp/plan.md, run tests" --wait-for-idle
 harnex stop --id cx-impl
 
 # 3. Claude reviews the implementation
-harnex run claude --id cl-review --tmux
+harnex run claude --id cl-review --tmux cl-review
 harnex send --id cl-review --message "Review changes against /tmp/plan.md, write /tmp/review.md" --wait-for-idle
 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.
+
 Harnex ships CLI-readable agent guides for this pattern:
 
 - **[Dispatch](guides/01_dispatch.md)** — the fire-and-watch pattern:
@@ -133,19 +153,47 @@ Presets map to stall policy defaults:
 
 Explicit `--stall-after` and `--max-resumes` flags override preset defaults.
 
+For one-shot startup prompts, add `--auto-stop`. It requires `--context`
+and stops the session after the first task completion or PTY prompt return.
+
 For structured subscriptions, stream JSONL events:
 
 ```bash
-harnex events --id cx-impl-42 | jq -c '.'
+harnex events --id cx-impl-42
 ```
 
 Schema details and compatibility policy are documented in
 [docs/events.md](docs/events.md).
 
+## Dispatch history
+
+Every finished `harnex run` appends one JSON line to
+`<repo>/.harnex/dispatch.jsonl`. Harnex finds the repo by walking up from the
+run directory until it sees `.git/`; sessions outside a git repo write to
+`~/.local/state/harnex/dispatch.jsonl`.
+
+Use `harnex history` to inspect it:
+
+```bash
+harnex history
+harnex history --json | jq .
+```
+
+Dispatch briefs can declare soft budget metadata through `--meta`:
+
+```bash
+harnex run codex --meta '{"read_budget_lines":2000,"output_ceiling_lines":800}' ...
+```
+
+Those declared values are copied into summary `meta`. Terminal summary
+`actual` also records rough measurements for downstream enforcement:
+`lines_changed`, `output_lines`, `output_bytes`, and `event_records`.
+Harnex records the data only; consumers decide whether to fail closed.
+
 ## Long-running and overnight work
 
 For plain "force-resume on stall" recovery, use
-`harnex run --watch --preset impl`.
+`harnex run codex --watch --preset impl --context "Read /tmp/task.md"`.
 
 A **buddy** is for richer reasoning: doc drift checks, semantic sanity checks,
 and multi-session correlation. It's still just another harnex session.
@@ -155,8 +203,8 @@ and multi-session correlation. It's still just another harnex session.
 Spawn a buddy alongside a long-running implementation worker:
 
 ```bash
-harnex run codex --id worker-42 --tmux
-harnex run claude --id buddy-42 --tmux
+harnex run codex --id worker-42 --tmux worker-42
+harnex run claude --id buddy-42 --tmux buddy-42
 harnex send --id buddy-42 --message "$(cat <<'EOF'
 Watch harnex session worker-42.
 Every 5 minutes: run `harnex pane --id worker-42 --lines 30`.
@@ -165,7 +213,7 @@ nudge it: `harnex send --id worker-42 --message "Continue your task."`.
 When it exits, report back:
   tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 done" Enter
 EOF
-"
+)"
 ```
 
 ### Example: watch for doc drift during implementation
@@ -174,8 +222,8 @@ A buddy that checks whether a worker's code changes have left
 docs out of date:
 
 ```bash
-harnex run codex --id worker-99 --tmux
-harnex run claude --id buddy-99 --tmux
+harnex run codex --id worker-99 --tmux worker-99
+harnex run claude --id buddy-99 --tmux buddy-99
 harnex send --id buddy-99 --message "$(cat <<'EOF'
 Watch harnex session worker-99.
 Every 5 minutes: run `harnex pane --id worker-99 --lines 30`.
@@ -187,7 +235,7 @@ inline comments) that are now stale. If so, nudge the worker:
 When the worker exits, report a summary to the invoker:
   tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-99 done. Doc drift: <yes/no>" Enter
 EOF
-"
+)"
 ```
 
 ### The invoker doesn't need to be a harnex session
@@ -213,7 +261,9 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 | `harnex pane --id <id>` | Capture the agent's tmux screen (`--follow` for live) |
 | `harnex logs --id <id>` | Read session transcript (`--follow` to tail) |
 | `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 history` | List completed dispatches from `.harnex/dispatch.jsonl` |
+| `harnex wait --id <id>` | Block until exit, a target state, or `--until task_complete` |
+| `harnex doctor` | Run adapter dependency preflight checks; add `--sweep` for read-only session drift diagnostics |
 | `harnex guide` | Getting started walkthrough |
 | `harnex agents-guide` | Agent-facing dispatch, chain, buddy, monitoring, and naming guides |
 | `harnex recipes` | Tested workflow patterns |

data/TECHNICAL.md

@@ -29,6 +29,7 @@ harnex run codex -- --cd ~/other/repo
 | `--watch-file PATH` | Auto-send a file-change hook (`--watch PATH`/`--watch=PATH` legacy) |
 | `--context TXT`     | Give the agent a task on startup                                    |
 | `--auto-stop`       | With `--context`, stop after the first task completion              |
+| `--fast`            | For Codex, use `service_tier="fast"` instead of default `flex`      |
 | `--timeout SEC`     | Wait budget for detached registration                               |
 
 ### `harnex send` — Talk to a running agent
@@ -88,6 +89,16 @@ harnex wait --id worker
 harnex wait --id worker --until prompt --timeout 300
 ```
 
+### `harnex history` — List completed dispatches
+
+```bash
+harnex history
+harnex history --json | jq .
+```
+
+Reads `<repo>/.harnex/dispatch.jsonl`, where `<repo>` is found by walking up
+until `.git/` is present. Use `--global` for the no-repo fallback file.
+
 ### `harnex logs` — Read session transcripts
 
 ```bash
@@ -247,6 +258,7 @@ Schema details and compatibility guarantees are in [docs/events.md](docs/events.
    ├── base.rb     adapter interface
    ├── generic.rb  fallback adapter for any CLI
    ├── codex.rb    codex-specific behavior
+   ├── opencode.rb opencode-specific behavior
    └── claude.rb   claude-specific behavior
 ```
 
@@ -365,6 +377,17 @@ The adapter reads the screen and returns a state hash:
 - Multi-step submit: types text, then sends Enter after a
   short delay so pasted prompts are actually submitted
 
+### OpenCode Adapter
+
+- Uses optimistic PTY prompt detection to avoid inbox deadlock
+  when OpenCode's alternate-screen TUI omits stable plain-text
+  prompt markers in snapshots.
+- Stop sequence sends a double Ctrl+C to match OpenCode's native
+  terminal shutdown path (interrupt first, force-quit second if
+  needed).
+- Multi-step submit mirrors Claude/Codex PTY behavior: text first,
+  then Enter with a short delay.
+
 ## State Machine
 
 `SessionState` tracks the agent's readiness:

data/guides/01_dispatch.md

@@ -86,6 +86,8 @@ Codex flag forms differ between transports. The default JSON-RPC adapter
 `-c model="<name>"` instead. The legacy PTY adapter (`harnex run codex
 --legacy-pty`) still accepts `-m`. Harnex rejects `-m` early on JSON-RPC
 with an actionable error rather than letting the subprocess boot-disconnect.
+Codex app-server runs also default to `service_tier="flex"`; add
+`--fast` to use `service_tier="fast"`.
 
 ## Send
 

data/lib/harnex/adapters/base.rb

@@ -1,7 +1,11 @@
+require "open3"
+require "timeout"
+
 module Harnex
   module Adapters
     class Base
       PROMPT_PREFIXES = [">", "\u203A", "\u276F"].freeze
+      AGENT_VERSION_TIMEOUT_SECONDS = 2.0
 
       # Adapter contract — subclasses MUST implement:
       #   base_command          -> Array[String]  CLI args to spawn
@@ -26,6 +30,21 @@ module Harnex
         :pty
       end
 
+      # Vendor of the underlying agent — populates DISPATCH meta.agent_provider.
+      # Subclasses override (claude → "anthropic", codex → "openai").
+      def provider
+        nil
+      end
+
+      # Probes `<base_command.first> --version` with a short timeout and
+      # memoizes the result for the adapter's lifetime. Returns nil when
+      # the binary is missing, exits non-zero, or stalls past the timeout.
+      def agent_version
+        return @agent_version if defined?(@agent_version)
+
+        @agent_version = probe_agent_version
+      end
+
       def describe
         { transport: transport }
       end
@@ -108,6 +127,20 @@ module Harnex
 
       protected
 
+      def probe_agent_version
+        cli = base_command.first
+        return nil unless cli
+
+        Timeout.timeout(AGENT_VERSION_TIMEOUT_SECONDS) do
+          stdout, status = Open3.capture2(cli, "--version", err: File::NULL, in: File::NULL)
+          return nil unless status.success?
+
+          stdout.to_s.lines.first&.strip
+        end
+      rescue Errno::ENOENT, Timeout::Error, StandardError
+        nil
+      end
+
       def submit_bytes
         "\r"
       end

data/lib/harnex/adapters/claude.rb

@@ -8,6 +8,10 @@ module Harnex
         super("claude", extra_args)
       end
 
+      def provider
+        "anthropic"
+      end
+
       def base_command
         [
           "claude",

data/lib/harnex/adapters/codex.rb

@@ -10,6 +10,10 @@ module Harnex
         @banner_seen = false
       end
 
+      def provider
+        "openai"
+      end
+
       def base_command
         [
           "codex",