harnex 0.7.5 → 0.7.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c6173057b1fe4fa547979d3d9803f345acb4e658dd942aefa096ef886727c33
-  data.tar.gz: da1662c9dce791ae644aa4a0ea57d2124a1698593e6db98b2ac737d9f42816f6
+  metadata.gz: '09276571f581a98eb6c613e88e4035ed8420bcae710c43d57e307cc5eb4d468b'
+  data.tar.gz: 886e1555b2ee4d128d992e4d35aafc716c0bc2aa16318123b053e5e128a7337a
 SHA512:
-  metadata.gz: e2758cfa10fc9b221235efea20ff21be32b5558c1ab06eb4515cea5485be96e1371d663735c826d9587833caa46aed65486b5c3cedfe8ce3be04e7ac1c328f7f
-  data.tar.gz: 765cf4ef020f3a7cfa8bbd1aad517ac1b4ec8901579b3720ea618ec246b20009c07c088d4d86e354ead78194844bba771790df0271d54fccecad6f6058874d9f
+  metadata.gz: 90f7f457f829f99424c1f2635706c3231c08bf1cea7329e47b6992fde3aa45e123c40c0d278bf2c9a5c8bc2ecd6d0f742a812320c659c5bbe68fd4ab94df6c9d
+  data.tar.gz: 65323fa96b6f5c92564b2be10cfe802f846fff1b76079f26cbaa362588dce50ae86a59c250b456058f3acad8ca31f03c9c49b2ad096c85a6aae5510797ff3abb

data/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [Unreleased]
 
+## [0.7.7] - 2026-06-12 | 10:48 AM | IST
+
+### Fixed
+
+- Codex app-server failed turns now emit `task_failed` instead of being
+  misreported as successful `task_complete` work. `harnex wait --until done`
+  returns non-zero for failed-turn events, dispatch history records
+  `terminal_event=task_failed`, and auto-stop terminates structured sessions
+  without sending a stale `turn/interrupt` after the turn is already complete.
+- Codex app-server nested error notifications now preserve the real Codex error
+  message (for example missing provider credentials) without counting them as
+  transport disconnects.
+
+### Changed
+
+- Refreshed the pinned Codex app-server JSON Schema fixtures to
+  `codex-cli 0.139.0` and taught the test schema validator `minLength`.
+
+## [0.7.6] - 2026-06-09 | 12:59 AM | IST
+
+### Added
+
+- `harnex status --json` now exposes work-level completion fields (`done`,
+  `work_state`, and `process_state`) so monitors can distinguish completed
+  work from a still-live interactive process.
+- `harnex wait --until done` waits for `task_complete` or terminal exit,
+  whichever arrives first, giving queue monitors a safe default fence.
+
+### Changed
+
+- Refreshed README quick-start and monitoring guidance to emphasize
+  `--context --auto-stop`, `--until task_complete` for interactive structured
+  sessions, durable terminal summaries, and timeout/artifact verification.
+- Monitoring, buddy, and recipe examples now gate unattended work on
+  `--until done` / `done` / `work_state` instead of `state=completed` alone.
+
 ## [0.7.5] - 2026-05-26 | 05:18 PM | IST
 
 ### Added

data/README.md

@@ -33,16 +33,24 @@ or project-local docs are required.
 ## What it does
 
 ```bash
-# Start an agent in tmux
-harnex run pi --id planner --tmux planner
+# Start a visible one-shot worker, give it a task, and stop on completion
+harnex run pi --id planner --tmux planner \
+  --context "Write a plan to /tmp/plan.md" --auto-stop
 
-# 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
+# Wait for the work-level completion signal and terminal telemetry
+harnex wait --id planner --until done --timeout 900
 
-# Peek at what it's doing
-harnex pane --id planner --lines 30
+# Inspect the final state or the recent dispatch history
+harnex status --id planner --json
+harnex history --limit 5
+```
+
+For a long-lived interactive session, keep the worker open and send work to it:
 
-# Stop it
+```bash
+harnex run pi --id planner --tmux planner
+harnex send --id planner --message "Write a plan to /tmp/plan.md" --wait-for-idle
+harnex pane --id planner --lines 30
 harnex stop --id planner
 ```
 
@@ -59,8 +67,9 @@ job, watch it work, stop it when done.
   tmux-backed terminal, `harnex logs` tails the persisted transcript, and
   `harnex events` streams structured JSONL lifecycle events.
 
-- **You don't want to babysit.** Send a task with `--wait-for-idle`,
-  walk away, check back when it's done.
+- **You don't want to babysit.** Use `--context --auto-stop` for
+  one-shot work, `--watch` for bounded stall recovery, or
+  `--wait-for-idle` as a send fence.
 
 - **You want local-only orchestration.** Everything runs on your
   machine. No cloud services, no API keys beyond what the agents need.
@@ -169,6 +178,31 @@ bare `--watch` means babysitter mode.
 For one-shot startup prompts, add `--auto-stop`. It requires `--context`
 and stops the session after the first task completion or PTY prompt return.
 
+## Completion and waiting
+
+Choose the wait predicate that matches how you launched the worker:
+
+- `harnex wait --id ID --until done --timeout SECS` is the safest unattended
+  work fence. It returns when Harnex sees `task_complete`, `task_failed`, or a
+  terminal exit, whichever comes first; failed work returns non-zero.
+- `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
+  `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.
+- `harnex send --wait-for-idle` is an atomic send fence for PTY-style
+  interactions. It proves the turn returned to an idle/prompt state, not that
+  your acceptance criteria passed.
+- `harnex status --id ID --json` can report `running`, `completed`, `failed`,
+  or `unknown` from durable terminal summary rows even after the live registry
+  is gone. Treat `state` as process/session state; use `done` and `work_state`
+  as the work-level monitor contract.
+
+Always set a timeout for unattended waits and verify the expected artifact,
+tests, or git state after harnex reports completion.
+
 For structured subscriptions, stream JSONL events:
 
 ```bash
@@ -183,7 +217,9 @@ Schema details and compatibility policy are documented in
 Every finished `harnex run` writes dispatch records. In a git repo, the
 default path is `<repo>/.harnex/dispatch.jsonl`; outside a git repo, the
 compact history record falls back to `~/.local/state/harnex/dispatch.jsonl`.
-`harnex history` reads the compact records from that location.
+`harnex history` reads the compact records from that location, and
+`harnex status --id ID --json` / `harnex wait` can use the same durable
+terminal summaries when the live session registry is already gone.
 
 Use `harnex history` to inspect it:
 
@@ -274,14 +310,14 @@ See [recipes/03_buddy.md](recipes/03_buddy.md) for the full pattern.
 | Command | What it does |
 |---------|-------------|
 | `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 done) |
+| `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 |
-| `harnex status` | List running sessions (`--json` for full payloads) |
+| `harnex status` | List running sessions; with `--id ID --json`, terminal summaries can classify completed/failed sessions after exit |
 | `harnex pane --id <id>` | Capture a tmux-backed session's 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 history` | List completed dispatches from `.harnex/dispatch.jsonl` |
-| `harnex wait --id <id>` | Block until exit, a target state, or `--until task_complete` |
+| `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 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 |

data/guides/01_dispatch.md

@@ -73,7 +73,7 @@ for i in 1 2 3; do
   harnex run pi --id w-$i --tmux w-$i --detach \
     --context "Read and execute /tmp/task-$i.md" --auto-stop &
 done
-for i in 1 2 3; do harnex wait --id w-$i & done
+for i in 1 2 3; do harnex wait --id w-$i --until done & done
 wait
 ```
 
@@ -125,7 +125,8 @@ Use the lightest primitive that gives the signal you need:
 | Continuous pane view | `harnex pane --id pi-i-NN --follow` |
 | Transcript tail | `harnex logs --id pi-i-NN --lines 80` |
 | Structured events | `harnex events --id pi-i-NN --snapshot` |
-| Native turn completion | `harnex wait --id pi-i-NN --until task_complete` |
+| Work completion/failure fence | `harnex wait --id pi-i-NN --until done` |
+| Native successful-turn completion | `harnex wait --id pi-i-NN --until task_complete` |
 
 For unattended policy-only stall recovery, use built-in watch mode:
 

data/guides/03_buddy.md

@@ -54,8 +54,8 @@ If the worker appears stuck at a prompt or permission dialog for more than
 10 minutes with no progress, nudge it:
 - `harnex send --id pi-i-42 --message "You appear to have stalled. Continue with your current task."`
 
-If `harnex status --id pi-i-42 --json` reports `state=completed` or `state=failed`, report back:
-- `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "pi-i-42 terminal state reached. Check harnex status --id pi-i-42 --json." Enter`
+If `harnex status --id pi-i-42 --json` reports `done=true` or `work_state=failed`, report back:
+- `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "pi-i-42 work-level state reached. Check harnex status --id pi-i-42 --json." Enter`
 
 Do not interfere with active work. Stop yourself after reporting completion.
 ```

data/guides/04_monitoring.md

@@ -17,24 +17,28 @@ Prefer signals in this order:
 | `harnex pane` | Live UI interpretation and prompt/error diagnosis |
 | `harnex status` | Session liveness and coarse state |
 
-For structured sessions (Pi RPC and Codex app-server),
-`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.
+For unattended monitors, prefer `harnex wait --until done`: it returns on the
+work-level `task_complete` or `task_failed` signal, or terminal exit, whichever
+comes first. Failed work returns non-zero. For structured sessions (Pi RPC and
+Codex app-server), `harnex wait --until task_complete` remains the exact
+successful-turn fence. Neither knows your acceptance criteria; verify the
+expected artifact or tests afterward.
 
 ## Completion Test
 
-For unattended work, first gate on harnex terminal state, then verify the task
+For unattended work, first gate on harnex work completion, then verify the task
 artifact and repo health:
 
 ```bash
-harnex wait --id pi-i-NN --timeout 5400 &&
+harnex wait --id pi-i-NN --until done --timeout 5400 &&
   test -f path/to/expected-artifact &&
   test -z "$(git status --short)"
 ```
 
-`harnex wait` succeeds from durable terminal telemetry (`--summary-out` /
-`.harnex/dispatch.jsonl` / exit status), not from tmp done markers.
+`harnex wait --until done` succeeds from `task_complete` or durable successful
+terminal telemetry (`--summary-out` / `.harnex/dispatch.jsonl` / exit status),
+returns non-zero for `task_failed` / failed terminal telemetry, and does not use
+tmp done markers.
 
 Adjust the artifact path to the task. The point is to avoid declaring done while
 a worker is between edits or between commits.
@@ -72,6 +76,8 @@ harnex events --id pi-i-NN
 For task completion:
 
 ```bash
+harnex wait --id pi-i-NN --until done --timeout 900
+# Or, when you specifically need the structured turn event:
 harnex wait --id pi-i-NN --until task_complete --timeout 900
 ```
 
@@ -92,12 +98,13 @@ while :; do
   fi
 
   row=$(harnex status --id pi-i-NN --json | ruby -rjson -e 'rows=JSON.parse(STDIN.read); print JSON.generate(rows.first || {})')
+  done=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["done"] ? "true" : "false")')
+  work_state=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["work_state"].to_s)')
   state=$(printf '%s' "$row" | ruby -rjson -e 'print(JSON.parse(STDIN.read)["state"].to_s)')
 
-  case "$state" in
-    completed) echo "pi-i-NN completed"; break ;;
-    failed|unknown) echo "pi-i-NN terminal state: $state" >&2; exit 1 ;;
-    running) harnex pane --id pi-i-NN --lines 20 ;;
+  case "$done:$work_state" in
+    true:*) echo "pi-i-NN work completed"; break ;;
+    false:failed) echo "pi-i-NN work failed; process state: $state" >&2; exit 1 ;;
     *) harnex pane --id pi-i-NN --lines 20 ;;
   esac
 
@@ -136,6 +143,7 @@ interpretation.
 
 ## Anti-Patterns
 
+- Polling `state=completed` alone and missing live sessions with `task_complete=true`.
 - Polling `state=prompt` alone and calling it done.
 - Blocking orchestrators on `/tmp/*-done.txt` as the only completion signal.
 - Letting an unattended loop run with no wall-clock cap.

data/lib/harnex/adapters/codex_appserver.rb

@@ -339,7 +339,7 @@ module Harnex
           @current_turn_id = nil
           @state = :prompt
         when "error"
-          @state = :disconnected
+          @state = :busy
         end
 
         @notification_handler&.call(message)

data/lib/harnex/codex/app_server/client.rb

@@ -265,8 +265,7 @@ module Harnex
 
             if message["error"]
               err_msg = message.dig("error", "message") || "RPC error"
-              pending.push(StandardError.new("codex_appserver RPC error: #{err_msg}"))
-              signal_disconnect(message["error"])
+              pending.push(StandardError.new(err_msg))
             else
               pending.push(message["result"] || {})
             end

data/lib/harnex/commands/status.rb

@@ -30,6 +30,8 @@ module Harnex
           Use --all when supervising workers launched from sibling worktrees.
           With --id, terminal summaries can report completed/failed/unknown
           even after the live session registry is gone.
+          `state` is process/session state; use JSON `done`/`work_state`
+          or `harnex wait --until done` for work-level completion.
           A prompt-like state is not a completion signal by itself.
       TEXT
     end
@@ -100,10 +102,17 @@ module Harnex
     end
 
     def normalize_live_status(session)
+      task_failed = task_failed?(session)
+      task_complete = task_complete?(session) && !task_failed
+      work_state = task_failed ? "failed" : Harnex.work_state_for("running", task_complete: task_complete)
       session.merge(
         "state" => "running",
+        "process_state" => "running",
         "terminal" => false,
-        "task_complete" => !session["last_completed_at"].to_s.empty?,
+        "task_complete" => task_complete,
+        "task_failed" => task_failed,
+        "done" => Harnex.work_done_for("running", task_complete: task_complete),
+        "work_state" => work_state,
         "exit" => nil,
         "exit_code" => nil,
         "summary_out" => nil,
@@ -112,6 +121,16 @@ module Harnex
       )
     end
 
+    def task_complete?(session)
+      session["task_complete"] == true || session["task_complete"].to_s == "true" ||
+        !session["last_completed_at"].to_s.empty?
+    end
+
+    def task_failed?(session)
+      session["task_failed"] == true || session["task_failed"].to_s == "true" ||
+        !session["last_failed_at"].to_s.empty?
+    end
+
     def load_live_status(session)
       uri = URI("http://#{session.fetch('host')}:#{session.fetch('port')}/status")
       request = Net::HTTP::Get.new(uri)

data/lib/harnex/commands/wait.rb

@@ -11,8 +11,8 @@ module Harnex
     EXIT_STATUS_GRACE_POLL_INTERVAL = 0.05
     FINAL_EVENT_GRACE_SECONDS = 5.0
 
-    EVENT_PREDICATES = %w[task_complete].freeze
-    LEGACY_EVENT_TYPES = %w[agent_state exited task_complete].freeze
+    EVENT_PREDICATES = %w[task_complete task_failed].freeze
+    LEGACY_EVENT_TYPES = %w[agent_state exited task_complete task_failed].freeze
 
     def self.usage(program_name = "harnex wait")
       <<~TEXT
@@ -21,8 +21,13 @@ module Harnex
         Options:
           --id ID         Session ID to wait for (required)
           --until STATE   Wait until session reaches STATE. Supported:
+                            done            (work fence — task_complete,
+                                             task_failed, or terminal exit,
+                                             whichever comes first)
                             task_complete   (events JSONL — fires on
-                                             turn/completed; adapter-agnostic)
+                                             successful turn completion)
+                            task_failed     (events JSONL — fires on
+                                             failed turn completion)
                             <other>         (agent_state HTTP poll, e.g.
                                              "prompt", "busy")
                           Without --until, waits for session exit (default).
@@ -31,12 +36,14 @@ module Harnex
           -h, --help      Show this help
 
         Common patterns:
+          #{program_name} --id cx-i-42 --until done --timeout 900
           #{program_name} --id cx-i-42 --until task_complete --timeout 900
           #{program_name} --id cx-i-42 --until prompt --timeout 120
           #{program_name} --id cx-i-42
 
         Gotchas:
-          task_complete is an event predicate; prompt/busy are live state polls.
+          done is the safest work-level fence for monitors.
+          task_complete/task_failed are event predicates; prompt/busy are live state polls.
           Prompt state alone does not prove work acceptance. Verify artifacts/tests.
           Exit waits can resolve from terminal summary rows when live registry/
           exit-status files are already gone.
@@ -65,7 +72,10 @@ module Harnex
       raise "--id is required for harnex wait" unless @options[:id]
 
       if @options[:until_state]
-        if EVENT_PREDICATES.include?(@options[:until_state])
+        case @options[:until_state]
+        when "done"
+          wait_until_done
+        when *EVENT_PREDICATES
           wait_until_event(@options[:until_state])
         else
           wait_until_state
@@ -133,9 +143,9 @@ module Harnex
           event = parse_event(line)
           next unless event
 
-          task_complete_seen = true if event_type(event) == "task_complete"
+          task_complete_seen = true if %w[task_complete task_failed].include?(event_type(event))
           if matches?(event, predicate, task_complete_seen)
-            return [emit_event_match(event, start_time), f.pos, task_complete_seen]
+            return [emit_event_match(event, start_time, predicate), f.pos, task_complete_seen]
           end
         end
         offset = f.pos
@@ -168,6 +178,10 @@ module Harnex
       case predicate
       when "task_complete"
         type == "task_complete"
+      when "task_failed"
+        type == "task_failed"
+      when "done"
+        %w[task_complete task_failed].include?(type)
       when "prompt"
         type == "task_complete" ||
           (task_complete_seen && type == "agent_state" && event["state"] == "prompt")
@@ -176,18 +190,112 @@ module Harnex
       end
     end
 
-    def emit_event_match(event, start_time)
+    def done_event_failed?(event)
+      return true if event_type(event) == "task_failed"
+
+      status = event["status"].to_s
+      !status.empty? && !%w[completed success succeeded].include?(status)
+    end
+
+    def emit_event_match(event, start_time, predicate)
       waited = (Time.now - start_time).round(1)
-      puts JSON.generate(
+      payload = {
         ok: true,
         id: @options[:id],
         event: event_type(event),
         seq: event["seq"],
         waited_seconds: waited
-      )
+      }
+      if predicate == "done"
+        failed = done_event_failed?(event)
+        payload.merge!(
+          ok: !failed,
+          status: failed ? "failed" : "done",
+          state: "running",
+          process_state: "running",
+          terminal: false,
+          task_complete: !failed,
+          done: !failed,
+          work_state: failed ? "failed" : "completed"
+        )
+        payload[:last_error] = event["message"] || event["error"] if failed
+      end
+      puts JSON.generate(payload)
+      return 1 if predicate == "done" && done_event_failed?(event)
+
       0
     end
 
+    def wait_until_done
+      repo_root = Harnex.resolve_repo_root(@options[:repo_path])
+      events_path = Harnex.events_log_path(repo_root, @options[:id])
+      exit_path = Harnex.exit_status_path(repo_root, @options[:id])
+      registry = Harnex.read_registry(repo_root, @options[:id])
+      start_time = Time.now
+      deadline = @options[:timeout] ? start_time + @options[:timeout] : nil
+
+      offset = 0
+      task_complete_seen = false
+      final_event_deadline = nil
+
+      status, offset, task_complete_seen = scan_events(events_path, offset, "done", task_complete_seen, start_time)
+      return status if status
+
+      unless registry
+        terminal = done_status(repo_root)
+        return emit_done_terminal_status(terminal) if terminal
+        return emit_done_exit_status(exit_path, @options[:id]) if File.exist?(exit_path)
+
+        unless File.exist?(events_path)
+          warn("harnex wait: no session found with id #{@options[:id].inspect}")
+          puts JSON.generate(ok: false, id: @options[:id], state: "unknown", process_state: "unknown", terminal: false,
+                             task_complete: false, done: false, work_state: "unknown", status: "unknown")
+          return 1
+        end
+      end
+
+      target_pid = registry && registry["pid"]
+
+      loop do
+        status, offset, task_complete_seen = scan_events(events_path, offset, "done", task_complete_seen, start_time)
+        return status if status
+
+        unless registry
+          terminal = done_status(repo_root)
+          return emit_done_terminal_status(terminal) if terminal
+          return emit_done_exit_status(exit_path, @options[:id]) if File.exist?(exit_path)
+        end
+
+        if deadline && Time.now >= deadline
+          waited = (Time.now - start_time).round(1)
+          puts JSON.generate(ok: false, id: @options[:id], status: "timeout", waited_seconds: waited,
+                             done: false, work_state: "running")
+          return 124
+        end
+
+        if target_pid && !Harnex.alive_pid?(target_pid)
+          final_event_deadline ||= Time.now + FINAL_EVENT_GRACE_SECONDS
+          if Time.now >= final_event_deadline
+            await_exit_status(exit_path)
+            return emit_done_exit_status(exit_path, @options[:id]) if File.exist?(exit_path)
+
+            terminal = done_status(repo_root)
+            return emit_done_terminal_status(terminal) if terminal
+
+            waited = (Time.now - start_time).round(1)
+            puts JSON.generate(ok: false, id: @options[:id], state: "exited", process_state: "exited",
+                               terminal: true, task_complete: false, done: false, work_state: "unknown",
+                               waited_seconds: waited)
+            return 1
+          end
+        else
+          final_event_deadline = nil
+        end
+
+        sleep EVENT_POLL_INTERVAL
+      end
+    end
+
     def wait_until_state
       repo_root = Harnex.resolve_repo_root(@options[:repo_path])
       target_state = @options[:until_state]
@@ -244,7 +352,8 @@ module Harnex
         return emit_terminal_status(terminal) if terminal
 
         warn("harnex wait: no session found with id #{@options[:id].inspect}")
-        puts JSON.generate(ok: false, id: @options[:id], state: "unknown", terminal: false, status: "unknown")
+        puts JSON.generate(ok: false, id: @options[:id], state: "unknown", process_state: "unknown",
+                           terminal: false, task_complete: false, done: false, work_state: "unknown", status: "unknown")
         return 1
       end
 
@@ -259,7 +368,8 @@ module Harnex
           terminal = terminal_status(repo_root)
           return emit_terminal_status(terminal) if terminal
 
-          puts JSON.generate(ok: false, id: @options[:id], state: "unknown", terminal: false, status: "unknown")
+          puts JSON.generate(ok: false, id: @options[:id], state: "unknown", process_state: "unknown",
+                             terminal: false, task_complete: false, done: false, work_state: "unknown", status: "unknown")
           return 1
         end
 
@@ -328,19 +438,62 @@ module Harnex
       status
     end
 
+    def done_status(repo_root)
+      status = Harnex::TerminalStatus.resolve(id: @options[:id], repo_root: repo_root)
+      return nil unless status
+      return nil unless status["done"] || status["terminal"]
+
+      status
+    end
+
+    def emit_done_exit_status(exit_path, id)
+      data = JSON.parse(File.read(exit_path))
+      exit_code = data["exit_code"]
+      task_complete = data["task_complete"] == true || data["task_complete"].to_s == "true"
+      task_failed = data["task_failed"] == true || data["task_failed"].to_s == "true"
+      exit_success = !task_failed && (exit_code.nil? || exit_code.to_i == 0)
+      state = exit_success ? "completed" : "failed"
+      done = task_complete || exit_success
+      payload = data.merge(
+        "ok" => done,
+        "id" => id,
+        "state" => state,
+        "process_state" => "exited",
+        "terminal" => true,
+        "task_complete" => task_complete,
+        "task_failed" => task_failed,
+        "done" => done,
+        "work_state" => Harnex.work_state_for(state, task_complete: task_complete)
+      )
+      success = done
+      puts JSON.generate(payload)
+      return 0 if success
+
+      exit_code.is_a?(Integer) && exit_code.positive? ? exit_code : 1
+    rescue JSON::ParserError
+      puts JSON.generate(ok: false, id: id, state: "failed", process_state: "exited", terminal: true,
+                         task_complete: false, done: false, work_state: "failed", status: "invalid_exit_status")
+      1
+    end
+
+    def emit_done_terminal_status(status)
+      payload = terminal_payload(status)
+      payload[:ok] = !!payload[:done]
+      payload[:status] = payload[:done] ? "done" : status["state"]
+      puts JSON.generate(payload)
+
+      if payload[:ok]
+        0
+      elsif status["exit_code"].is_a?(Integer) && status["exit_code"] > 0
+        status["exit_code"]
+      else
+        1
+      end
+    end
+
     def emit_terminal_status(status)
-      payload = {
-        ok: status["state"] == "completed",
-        id: status["id"],
-        state: status["state"],
-        terminal: true,
-        task_complete: status["task_complete"],
-        exit: status["exit"],
-        exit_code: status["exit_code"],
-        summary_out: status["summary_out"],
-        ended_at: status["ended_at"],
-        source: status["source"]
-      }
+      payload = terminal_payload(status)
+      payload[:ok] = status["state"] == "completed"
       puts JSON.generate(payload)
 
       if payload[:ok]
@@ -352,6 +505,29 @@ module Harnex
       end
     end
 
+    def terminal_payload(status)
+      task_complete = !!status["task_complete"]
+      task_failed = !!status["task_failed"]
+      work_state = status["work_state"] || Harnex.work_state_for(status["state"], task_complete: task_complete)
+      done = status.key?("done") ? !!status["done"] : work_state == "completed"
+      {
+        ok: false,
+        id: status["id"],
+        state: status["state"],
+        process_state: status["process_state"] || Harnex.process_state_for(status["state"], terminal: true),
+        terminal: status.key?("terminal") ? !!status["terminal"] : true,
+        task_complete: task_complete,
+        task_failed: task_failed,
+        done: done,
+        work_state: work_state,
+        exit: status["exit"],
+        exit_code: status["exit_code"],
+        summary_out: status["summary_out"],
+        ended_at: status["ended_at"],
+        source: status["source"]
+      }
+    end
+
     def parser
       @parser ||= OptionParser.new do |opts|
         opts.banner = "Usage: harnex wait [options]"

data/lib/harnex/core.rb

@@ -68,6 +68,36 @@ module Harnex
     VERSION
   end
 
+  def work_state_for(session_state, task_complete: false)
+    return "completed" if task_complete
+
+    case session_state.to_s
+    when "completed"
+      "completed"
+    when "failed"
+      "failed"
+    when "running"
+      "running"
+    else
+      "unknown"
+    end
+  end
+
+  def work_done_for(session_state, task_complete: false)
+    work_state_for(session_state, task_complete: task_complete) == "completed"
+  end
+
+  def process_state_for(session_state, terminal: false)
+    return "running" unless terminal
+
+    case session_state.to_s
+    when "completed", "failed"
+      "exited"
+    else
+      "unknown"
+    end
+  end
+
   def host_info
     {
       host: Socket.gethostname,

data/lib/harnex/dispatch_history.rb

@@ -85,6 +85,7 @@ module Harnex
     end
 
     def classify(session)
+      return ["failed", "task_failed"] if session.respond_to?(:task_failed?) && session.task_failed?
       return ["completed", "task_complete"] if session.task_complete?
       return ["timeout", "timeout"] if session.exit_code == 124
       return ["killed", "process_kill"] if session.term_signal

data/lib/harnex/runtime/session.rb

@@ -16,6 +16,7 @@ module Harnex
       agent_session_id cost_usd
     ].freeze
     BUDGET_META_FIELDS = %w[read_budget_lines output_ceiling_lines].freeze
+    SUCCESSFUL_TURN_STATUSES = %w[completed success succeeded].freeze
     class EventCounters
       def initialize
         @counts = {
@@ -103,6 +104,8 @@ module Harnex
       @session_finalized = false
       @turn_started_seen = false
       @last_completed_at = nil
+      @last_failed_at = nil
+      @last_failed_status = nil
       @pi_streamed_text_by_message = {}
       @auto_stop = !!auto_stop
       @auto_stop_fired = false
@@ -221,9 +224,19 @@ module Harnex
       end
 
       payload[:input_state] = adapter.input_state(screen_snapshot) if include_input_state
+      task_complete = task_complete?
+      task_failed = task_failed?
+      work_state = task_failed ? "failed" : Harnex.work_state_for("running", task_complete: task_complete)
       payload[:agent_state] = @state_machine.to_s
+      payload[:process_state] = "running"
       payload[:inbox] = @inbox.stats
       payload[:last_completed_at] = @last_completed_at&.iso8601
+      payload[:last_failed_at] = @last_failed_at&.iso8601
+      payload[:task_complete] = task_complete
+      payload[:task_failed] = task_failed
+      payload[:done] = Harnex.work_done_for("running", task_complete: task_complete)
+      payload[:work_state] = work_state
+      payload[:last_error] = @last_error
       payload[:model] = summary_model
       payload[:effort] = meta_hash["effort"]
       payload[:auto_disconnects] = @event_counters.snapshot[:disconnections]
@@ -231,7 +244,11 @@ module Harnex
     end
 
     def task_complete?
-      !!@last_completed_at
+      !!@last_completed_at && !task_failed?
+    end
+
+    def task_failed?
+      !!@last_failed_at
     end
 
     def git_start
@@ -252,7 +269,7 @@ module Harnex
       inject_sequence([{ text: text, newline: newline }])
     end
 
-    def inject_stop(turn_id: nil)
+    def inject_stop(turn_id: nil, interrupt: true)
       unless structured_transport?
         raise "session is not running" unless pid && Harnex.alive_pid?(pid)
       end
@@ -269,15 +286,21 @@ module Harnex
             end
           end
         end
-        @inject_mutex.synchronize do
-          begin
-            adapter.interrupt(turn_id: turn_id)
-          rescue StandardError
-            nil
+        if interrupt
+          @inject_mutex.synchronize do
+            begin
+              adapter.interrupt(turn_id: turn_id)
+            rescue StandardError
+              nil
+            end
+            @state_machine.force_busy!
           end
-          @state_machine.force_busy!
+          return { ok: true, signal: "interrupt_sent" }
         end
-        return { ok: true, signal: "interrupt_sent" }
+
+        @state_machine.force_busy!
+        signal_rpc_done! unless @pid
+        return { ok: true, signal: "terminate_sent" }
       end
 
       @inject_mutex.synchronize do
@@ -331,7 +354,12 @@ module Harnex
 
       turn_id = nil
       @inject_mutex.synchronize do
-        turn_id = adapter.dispatch(**dispatch)
+        begin
+          turn_id = adapter.dispatch(**dispatch)
+        rescue StandardError => e
+          mark_task_failed(status: "dispatch_error", error: e.message)
+          raise
+        end
         @state_machine.force_busy!
         @injected_count += 1
         @last_injected_at = Time.now
@@ -455,14 +483,25 @@ module Harnex
         @state_machine.force_busy!
         emit_event("turn_started", turnId: params.dig("turn", "id"))
       when "turn/completed"
-        @last_completed_at = Time.now
         @state_machine.force_prompt!
         turn = params["turn"] || {}
-        payload = { turnId: turn["id"] }
-        payload[:status] = turn["status"] if turn["status"]
-        payload[:tokenUsage] = params["tokenUsage"] if params["tokenUsage"]
-        emit_event("task_complete", **payload)
-        schedule_auto_stop("task_complete", turn_id: payload[:turnId])
+        status = turn["status"]
+        turn_id = turn["id"] || params["turnId"]
+        payload = { turnId: turn_id }
+        payload[:status] = status if status
+        payload[:tokenUsage] = params["tokenUsage"] if params["tokenUsage"].is_a?(Hash)
+        if successful_turn_status?(status)
+          @last_completed_at = Time.now
+          emit_event("task_complete", **payload)
+        else
+          mark_task_failed(
+            turn_id: turn_id,
+            status: status,
+            error: extract_turn_error_message(turn),
+            codex_error_info: extract_turn_error_info(turn)
+          )
+        end
+        schedule_auto_stop("turn_completed", interrupt: false)
       when "item/completed"
         emit_event("item_completed", item: params["item"])
         @event_counters.record_item(params["item"])
@@ -482,15 +521,70 @@ module Harnex
       when "account/rateLimits/updated"
         @rate_limits = params
       when "error"
-        @last_error = params["message"].to_s unless params["message"].to_s.empty?
+        message = extract_error_notification_message(params)
+        @last_error = message unless message.to_s.empty?
         @state_machine.force_busy!
-        emit_event("disconnected", source: "error_notification", message: params["message"])
-        signal_rpc_done!
+        emit_event(
+          "error",
+          source: "error_notification",
+          message: message,
+          codex_error_info: extract_error_notification_info(params),
+          will_retry: params["willRetry"],
+          threadId: params["threadId"],
+          turnId: params["turnId"]
+        )
+        signal_rpc_done! if params["turnId"].to_s.empty?
       end
     rescue StandardError => e
       warn("harnex: rpc notification handler error: #{e.message}")
     end
 
+    def successful_turn_status?(status)
+      text = status.to_s
+      return true if text.empty?
+
+      SUCCESSFUL_TURN_STATUSES.include?(text)
+    end
+
+    def mark_task_failed(turn_id: nil, status: nil, error: nil, codex_error_info: nil)
+      @last_failed_at = Time.now
+      @last_failed_status = status.to_s.empty? ? "failed" : status.to_s
+      @last_error = error.to_s unless error.to_s.empty?
+
+      payload = { status: @last_failed_status }
+      payload[:turnId] = turn_id if turn_id
+      payload[:message] = error unless error.to_s.empty?
+      payload[:codex_error_info] = codex_error_info if codex_error_info
+      emit_event("task_failed", **payload)
+    end
+
+    def extract_error_notification_message(params)
+      error = params["error"]
+      if error.is_a?(Hash)
+        error["message"] || error.dig("error", "message") || params["message"]
+      else
+        params["message"]
+      end
+    end
+
+    def extract_error_notification_info(params)
+      error = params["error"]
+      error.is_a?(Hash) ? error["codexErrorInfo"] : nil
+    end
+
+    def extract_turn_error_message(turn)
+      error = turn["error"]
+      return error["message"] if error.is_a?(Hash)
+      return error if error.is_a?(String)
+
+      nil
+    end
+
+    def extract_turn_error_info(turn)
+      error = turn["error"]
+      error.is_a?(Hash) ? error["codexErrorInfo"] : nil
+    end
+
     def handle_jsonl_notification(message)
       event_type = message["type"].to_s
 
@@ -504,7 +598,7 @@ module Harnex
         @state_machine.force_prompt!
         emit_event("task_complete")
         adapter.request_session_stats_async if adapter.respond_to?(:request_session_stats_async)
-        schedule_auto_stop("task_complete")
+        schedule_auto_stop("task_complete", interrupt: false)
       when "message_start"
         @pi_streamed_text_by_message[pi_message_key(message["message"])] = false
       when "message_update"
@@ -573,12 +667,21 @@ module Harnex
 
     def handle_rpc_disconnect(error)
       msg = error.is_a?(Hash) ? error["message"] : error&.message
+      if normal_auto_stop_disconnect?(msg)
+        signal_rpc_done!
+        return
+      end
+
       @last_error = msg.to_s unless msg.to_s.empty?
       @state_machine.force_busy!
       emit_event("disconnected", source: "transport", message: msg) rescue nil
       signal_rpc_done!
     end
 
+    def normal_auto_stop_disconnect?(message)
+      message.to_s.empty? && @auto_stop_fired && (task_complete? || task_failed?)
+    end
+
     def dispatch_initial_prompt
       return unless adapter.respond_to?(:initial_prompt)
 
@@ -733,13 +836,22 @@ module Harnex
       return unless defined?(@exit_code) && !@exit_code.nil?
 
       exit_path = Harnex.exit_status_path(repo_root, id)
+      task_complete = task_complete?
+      task_failed = task_failed?
+      state = task_failed || @exit_code.to_i != 0 ? "failed" : "completed"
       payload = {
-        ok: true,
+        ok: !task_failed && state == "completed",
         id: id,
         cli: adapter.key,
         session_id: session_id,
         repo_root: repo_root,
         exit_code: @exit_code,
+        state: state,
+        process_state: "exited",
+        task_complete: task_complete,
+        task_failed: task_failed,
+        done: Harnex.work_done_for(state, task_complete: task_complete),
+        work_state: Harnex.work_state_for(state, task_complete: task_complete),
         started_at: @started_at.iso8601,
         exited_at: Time.now.iso8601,
         injected_count: @injected_count
@@ -943,7 +1055,7 @@ module Harnex
       schedule_auto_stop("prompt_after_busy") if seen_busy && new_state == :prompt
     end
 
-    def schedule_auto_stop(reason, turn_id: nil)
+    def schedule_auto_stop(reason, turn_id: nil, interrupt: true)
       return unless @auto_stop
 
       should_fire = @auto_stop_mutex.synchronize do
@@ -958,7 +1070,7 @@ module Harnex
 
       thread = Thread.new do
         begin
-          inject_stop(turn_id: turn_id)
+          inject_stop(turn_id: turn_id, interrupt: interrupt)
         rescue StandardError => e
           warn("harnex: auto-stop failed after #{reason}: #{e.message}")
         end
@@ -1004,17 +1116,26 @@ module Harnex
 
     def normalize_auto_stop_exit_code!
       return unless @auto_stop
-      return unless @last_completed_at
       return unless @auto_stop_fired
 
+      if task_failed?
+        @exit_code = 1 if @exit_code.nil? || @exit_code.zero? || @term_signal
+        @term_signal = nil if @exit_code == 1
+        return
+      end
+
+      return unless task_complete?
+
       @exit_code = 0
       @term_signal = nil
     end
 
     def classify_exit
       return "timeout" if @exit_code == 124
-      return "success" if @exit_code == 0 && session_summary_present?
       return "boot_failure" if boot_failure_exit?
+      return "failure" if task_failed?
+      return "success" if @exit_code == 0 && task_complete?
+      return "success" if @exit_code == 0 && session_summary_present?
       return "failure" unless @exit_code == 0
 
       "disconnected"
@@ -1098,7 +1219,7 @@ module Harnex
         files_changed: @git_end[:files_changed],
         commits: @git_end[:commits],
         exit: @exit_reason,
-        task_complete: !!@last_completed_at,
+        task_complete: task_complete?,
         signal: @term_signal,
         exit_code: @exit_code,
         last_error: @last_error,
@@ -1244,6 +1365,7 @@ module Harnex
       @event_counters.record(type)
       @events_mutex.synchronize do
         return unless @events_log
+        return if @events_log.closed?
 
         @events_log_seq += 1
         event = {

data/lib/harnex/terminal_status.rb

@@ -42,8 +42,12 @@ module Harnex
         "id" => Harnex.normalize_id(id),
         "repo_root" => File.expand_path(repo_root.to_s.empty? ? Dir.pwd : repo_root),
         "state" => "unknown",
+        "process_state" => "unknown",
         "terminal" => false,
         "task_complete" => false,
+        "task_failed" => false,
+        "done" => false,
+        "work_state" => "unknown",
         "exit" => nil,
         "exit_code" => nil,
         "summary_out" => nil,
@@ -127,12 +131,19 @@ module Harnex
       meta = record["meta"] || {}
       actual = record["actual"] || {}
       state = classify_summary_state(actual)
+      task_complete = !!actual["task_complete"]
+      task_failed = state == "failed" && !task_complete
+      terminal = state != "unknown"
       {
         "id" => meta["id"].to_s,
         "repo_root" => meta["repo"] || fallback_repo_root,
         "state" => state,
-        "terminal" => state != "unknown",
-        "task_complete" => !!actual["task_complete"],
+        "process_state" => Harnex.process_state_for(state, terminal: terminal),
+        "terminal" => terminal,
+        "task_complete" => task_complete,
+        "task_failed" => task_failed,
+        "done" => Harnex.work_done_for(state, task_complete: task_complete),
+        "work_state" => Harnex.work_state_for(state, task_complete: task_complete),
         "exit" => blank_to_nil(actual["exit"]),
         "exit_code" => actual["exit_code"],
         "summary_out" => summary_path,
@@ -164,12 +175,19 @@ module Harnex
         else
           "unknown"
         end
+      task_complete = record["terminal_event"].to_s == "task_complete"
+      task_failed = record["terminal_event"].to_s == "task_failed" || (state == "failed" && !task_complete)
+      terminal = state != "unknown"
       {
         "id" => record["id"].to_s,
         "repo_root" => fallback_repo_root,
         "state" => state,
-        "terminal" => state != "unknown",
-        "task_complete" => record["terminal_event"].to_s == "task_complete",
+        "process_state" => Harnex.process_state_for(state, terminal: terminal),
+        "terminal" => terminal,
+        "task_complete" => task_complete,
+        "task_failed" => task_failed,
+        "done" => Harnex.work_done_for(state, task_complete: task_complete),
+        "work_state" => Harnex.work_state_for(state, task_complete: task_complete),
         "exit" => history_exit(status),
         "exit_code" => nil,
         "summary_out" => blank_to_nil(record["summary_out_path"]),

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.7.5"
-  RELEASE_DATE = "2026-05-26"
+  VERSION = "0.7.7"
+  RELEASE_DATE = "2026-06-12"
 end

data/recipes/01_fire_and_watch.md

@@ -19,7 +19,8 @@ harnex run codex --id cx-23 --tmux
 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
+harnex send --id cx-23 --message "Implement koder/plans/plan_23.md. Run tests when done."
+harnex wait --id cx-23 --until done --timeout 1200
 ```
 
 For tasks that need structured output, tell the worker to write a
@@ -32,12 +33,13 @@ 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
+harnex send --id cx-23 --message "Read and execute /tmp/task-cx-23.md"
+harnex wait --id cx-23 --until done --timeout 1200
 ```
 
 ### 3. Watch until done
 
-Use `--wait-for-idle` as the fence, then read the worker's screen:
+Use `harnex wait --until done` as the work-level fence, then read the worker's screen:
 
 ```bash
 harnex pane --id cx-23 --lines 25

data/recipes/03_buddy.md

@@ -45,8 +45,9 @@ Your job:
 2. If the worker appears stuck at a prompt for more than 10 minutes
    with no progress, nudge it:
    - `harnex send --id worker-42 --message "You appear to have stalled. Continue with your current task."`
-3. If the worker has exited (status shows no session), report back:
-   - `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 has exited. Check results." Enter`
+3. If `harnex status --id worker-42 --json` reports `done=true` or
+   `work_state=failed`, report back:
+   - `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 reached a work-level terminal state. Check results." Enter`
 4. Keep watching until the worker finishes or is stopped.
 
 Do not interfere with work in progress. Only nudge when clearly stalled.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.7.5
+  version: 0.7.7
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-26 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies: []
 description: A local PTY harness that wraps terminal AI agents (Claude, Codex, Pi)
   and adds a control plane for discovery, messaging, and coordination.