harnex 0.7.4 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e99b85fa8112b666665da16757d871098867e0b05c9521c3507fc2092616f825
-  data.tar.gz: 78a5190335ee968c77d75531d23998c34272d24a3b6a8d6a53d5e9a8922c87da
+  metadata.gz: 4c6173057b1fe4fa547979d3d9803f345acb4e658dd942aefa096ef886727c33
+  data.tar.gz: da1662c9dce791ae644aa4a0ea57d2124a1698593e6db98b2ac737d9f42816f6
 SHA512:
-  metadata.gz: 4c32673867f2b86ee84fa1768ee4fee82a3ddb0fb69abd5c369349d59fe9feef3cc468ee71776115da19ca2997b1f647678b413f8c93d02538f56c17daf316d4
-  data.tar.gz: bf049097af8736c25991af1894dd15b6cc8159393f99eb215a0dc7ddd67f9716b1864589664fdd08671edc6859899c9cb84c46852b940323b8f11f42d5f8ee29
+  metadata.gz: e2758cfa10fc9b221235efea20ff21be32b5558c1ab06eb4515cea5485be96e1371d663735c826d9587833caa46aed65486b5c3cedfe8ce3be04e7ac1c328f7f
+  data.tar.gz: 765cf4ef020f3a7cfa8bbd1aad517ac1b4ec8901579b3720ea618ec246b20009c07c088d4d86e354ead78194844bba771790df0271d54fccecad6f6058874d9f

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [0.7.5] - 2026-05-26 | 05:18 PM | IST
+
+### Added
+
+- `Harnex::TerminalStatus` now resolves durable terminal dispatch state from
+  summary/history rows so commands can classify inactive sessions without
+  relying on tmp done markers.
+
+### Changed
+
+- `harnex status --json --id <id>` now returns a machine-readable row even when
+  the live session is gone, with `state` in `running|completed|failed|unknown`
+  and terminal metadata (`terminal`, `exit`, `exit_code`, `summary_out`).
+- `harnex wait --id <id>` now falls back to terminal summary/history telemetry
+  when registry and exit-status files are missing, returning `completed` on
+  summary success and `unknown` when no durable terminal signal exists.
+- Monitoring guides now treat `/tmp/*-done.txt` as legacy compatibility hints;
+  canonical completion is `harnex wait` / `harnex status --json` / dispatch
+  summary rows.
+
 ## [0.7.4] - 2026-05-25 | 08:45 AM | IST
 
 ### Added

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 the worker exits or writes `/tmp/pi-i-42-done.txt`, report back:
-- `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "pi-i-42 finished. Check /tmp/pi-i-42-done.txt." Enter`
+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`
 
 Do not interfere with active work. Stop yourself after reporting completion.
 ```

data/guides/04_monitoring.md

@@ -24,16 +24,20 @@ afterward.
 
 ## Completion Test
 
-For unattended work, declare done with a conjunction of work-level facts:
+For unattended work, first gate on harnex terminal state, then verify the task
+artifact and repo health:
 
 ```bash
-test -f /tmp/pi-i-NN-done.txt &&
-  test -z "$(git status --short)" &&
-  test "$(git log -1 --format=%ct)" -lt "$(($(date +%s) - 600))"
+harnex wait --id pi-i-NN --timeout 5400 &&
+  test -f path/to/expected-artifact &&
+  test -z "$(git status --short)"
 ```
 
-Adjust the artifact path and commit-age window to the task. The point is to
-avoid declaring done while a worker is between edits or between commits.
+`harnex wait` succeeds from durable terminal telemetry (`--summary-out` /
+`.harnex/dispatch.jsonl` / exit status), not from 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.
 
 ## Why Pane State Alone Is Not Enough
 
@@ -73,22 +77,30 @@ harnex wait --id pi-i-NN --until task_complete --timeout 900
 
 ## Background Sweeper
 
-Consumers often run a small shell loop that checks the expected done marker,
-tree state, and harnex liveness. Keep a hard wall-clock cap so an unattended
-pipeline cannot wait forever:
+Consumers often run a small shell loop that checks terminal state, then drops
+to pane diagnostics only while work is still running. Keep a hard wall-clock cap
+so an unattended pipeline cannot wait forever:
 
 ```bash
 start=$(date +%s)
 max_wait=5400
 
-until test -f /tmp/pi-i-NN-done.txt; do
+while :; do
   if test "$(($(date +%s) - start))" -gt "$max_wait"; then
     echo "wall-clock cap hit for pi-i-NN" >&2
     exit 2
   fi
 
-  harnex status --id pi-i-NN --json
-  harnex pane --id pi-i-NN --lines 20
+  row=$(harnex status --id pi-i-NN --json | ruby -rjson -e 'rows=JSON.parse(STDIN.read); print JSON.generate(rows.first || {})')
+  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 ;;
+    *) harnex pane --id pi-i-NN --lines 20 ;;
+  esac
+
   sleep 60
 done
 ```
@@ -125,6 +137,7 @@ interpretation.
 ## Anti-Patterns
 
 - 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.
 - Reading raw tmux panes instead of `harnex pane`.
 - Using `--wait-for-idle` as acceptance proof.

data/guides/05_naming.md

@@ -93,9 +93,9 @@ The task file name does not need to duplicate the exact short phase code. It
 should be easy to scan in `/tmp` and should include the same task number as the
 session ID.
 
-## Done Markers
+## Done Markers (Legacy Compatibility)
 
-Derive done markers from the session ID:
+If a legacy workflow still expects a done marker, derive it from the session ID:
 
 ```text
 /tmp/pi-p-42-done.txt
@@ -103,5 +103,9 @@ Derive done markers from the session ID:
 /tmp/pi-cr-42-done.txt
 ```
 
+Treat done markers as compatibility hints only. Canonical completion should come
+from harnex terminal telemetry (`harnex wait` / `harnex status --json` / summary
+rows in `.harnex/dispatch.jsonl`).
+
 When a brief asks for a completion marker, make it one line and include the
 highest-signal result: tests passed, review clean, or the blocking issue.

data/lib/harnex/commands/status.rb

@@ -28,6 +28,8 @@ module Harnex
         Gotchas:
           By default, status filters to the current repo root.
           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.
           A prompt-like state is not a completion signal by itself.
       TEXT
     end
@@ -83,12 +85,31 @@ module Harnex
     end
 
     def load_sessions
-      repo_root = @options[:all] ? nil : Harnex.resolve_repo_root(@options[:repo_path])
-      sessions = Harnex.active_sessions(repo_root, id: @options[:id])
+      active_repo_root = @options[:all] ? nil : Harnex.resolve_repo_root(@options[:repo_path])
+      fallback_repo_root = Harnex.resolve_repo_root(@options[:repo_path])
+      sessions = Harnex.active_sessions(active_repo_root, id: @options[:id])
+
+      live = sessions.map { |session| normalize_live_status(load_live_status(session)) }
+                     .sort_by { |session| [session["repo_root"].to_s, session["started_at"].to_s, session["id"].to_s] }
+                     .reverse
+      return live unless @options[:id]
+      return [live.first] unless live.empty?
+
+      terminal = Harnex::TerminalStatus.resolve(id: @options[:id], repo_root: fallback_repo_root)
+      [terminal || Harnex::TerminalStatus.unknown(id: @options[:id], repo_root: fallback_repo_root)]
+    end
 
-      sessions.map { |session| load_live_status(session) }
-        .sort_by { |session| [session["repo_root"].to_s, session["started_at"].to_s, session["id"].to_s] }
-        .reverse
+    def normalize_live_status(session)
+      session.merge(
+        "state" => "running",
+        "terminal" => false,
+        "task_complete" => !session["last_completed_at"].to_s.empty?,
+        "exit" => nil,
+        "exit_code" => nil,
+        "summary_out" => nil,
+        "ended_at" => nil,
+        "source" => "live"
+      )
     end
 
     def load_live_status(session)
@@ -128,7 +149,7 @@ module Harnex
         "PORT" => session["port"].to_s,
         "AGE" => timeago(session["started_at"]),
         "IDLE" => format_idle(session["log_idle_s"]),
-        "STATE" => session.dig("input_state", "state").to_s.empty? ? "-" : session.dig("input_state", "state").to_s,
+        "STATE" => table_state(session),
         "DESC" => truncate(session["description"])
       }
       row["REPO"] = truncate_repo(session["repo_root"])
@@ -139,6 +160,14 @@ module Harnex
       columns.map { |column| row.fetch(column).ljust(widths.fetch(column)) }.join("  ")
     end
 
+    def table_state(session)
+      input_state = session.dig("input_state", "state").to_s
+      return input_state unless input_state.empty?
+
+      state = session["state"].to_s
+      state.empty? ? "-" : state
+    end
+
     def timeago(timestamp)
       return "-" if timestamp.to_s.empty?
 

data/lib/harnex/commands/wait.rb

@@ -38,6 +38,8 @@ module Harnex
         Gotchas:
           task_complete is an event predicate; 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.
           Without --timeout, wait can block indefinitely.
       TEXT
     end
@@ -238,7 +240,11 @@ module Harnex
       unless registry
         return read_exit_status(exit_path, @options[:id]) if File.exist?(exit_path)
 
+        terminal = terminal_status(repo_root)
+        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")
         return 1
       end
 
@@ -248,7 +254,13 @@ module Harnex
       loop do
         unless Harnex.alive_pid?(target_pid)
           await_exit_status(exit_path)
-          return read_exit_status(exit_path, @options[:id])
+          return read_exit_status(exit_path, @options[:id]) if File.exist?(exit_path)
+
+          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")
+          return 1
         end
 
         if deadline && Time.now >= deadline
@@ -308,6 +320,38 @@ module Harnex
       end
     end
 
+    def terminal_status(repo_root)
+      status = Harnex::TerminalStatus.resolve(id: @options[:id], repo_root: repo_root)
+      return nil unless status
+      return nil unless status["terminal"]
+
+      status
+    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"]
+      }
+      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 parser
       @parser ||= OptionParser.new do |opts|
         opts.banner = "Usage: harnex wait [options]"

data/lib/harnex/terminal_status.rb

@@ -0,0 +1,202 @@
+require "json"
+require "time"
+
+module Harnex
+  module TerminalStatus
+    module_function
+
+    def resolve(id:, repo_root: Dir.pwd)
+      normalized_id = Harnex.normalize_id(id)
+      root = File.expand_path(repo_root.to_s.empty? ? Dir.pwd : repo_root)
+
+      latest_summary = nil
+      latest_summary_path = nil
+      latest_history = nil
+
+      history_paths(root).each do |path|
+        summary, history = scan_dispatch_path(path, normalized_id)
+        if newer_summary?(summary, latest_summary)
+          latest_summary = summary
+          latest_summary_path = path
+        end
+        latest_history = history if newer_history?(history, latest_history)
+      end
+
+      summary_path = latest_history && latest_history["summary_out_path"].to_s.strip
+      if summary_path && !summary_path.empty? && File.file?(summary_path)
+        summary, = scan_dispatch_path(summary_path, normalized_id)
+        if newer_summary?(summary, latest_summary)
+          latest_summary = summary
+          latest_summary_path = summary_path
+        end
+      end
+
+      return build_from_summary(latest_summary, latest_summary_path, root) if latest_summary
+      return build_from_history(latest_history, root) if latest_history
+
+      nil
+    end
+
+    def unknown(id:, repo_root: Dir.pwd)
+      {
+        "id" => Harnex.normalize_id(id),
+        "repo_root" => File.expand_path(repo_root.to_s.empty? ? Dir.pwd : repo_root),
+        "state" => "unknown",
+        "terminal" => false,
+        "task_complete" => false,
+        "exit" => nil,
+        "exit_code" => nil,
+        "summary_out" => nil,
+        "started_at" => nil,
+        "ended_at" => nil,
+        "source" => "none"
+      }
+    end
+
+    def history_paths(repo_root)
+      local_path = DispatchHistory.path_for(repo_root)
+      return [local_path] if File.file?(local_path)
+
+      global_path = DispatchHistory.global_path
+      return [global_path] if File.file?(global_path)
+
+      []
+    rescue StandardError
+      []
+    end
+
+    def scan_dispatch_path(path, id)
+      summary_record = nil
+      history_record = nil
+
+      File.foreach(path) do |line|
+        record = JSON.parse(line)
+        next unless record.is_a?(Hash)
+
+        if summary_record?(record) && record.dig("meta", "id").to_s == id
+          summary_record = record
+        elsif history_record?(record) && record["id"].to_s == id
+          history_record = record
+        end
+      rescue JSON::ParserError
+        next
+      end
+
+      [summary_record, history_record]
+    rescue Errno::ENOENT
+      [nil, nil]
+    end
+
+    def summary_record?(record)
+      record["meta"].is_a?(Hash) && record["actual"].is_a?(Hash)
+    end
+
+    def history_record?(record)
+      record["schema_version"] == 1 && record.key?("status")
+    end
+
+    def newer_summary?(candidate, current)
+      return false unless candidate
+      return true unless current
+
+      summary_time(candidate) >= summary_time(current)
+    end
+
+    def newer_history?(candidate, current)
+      return false unless candidate
+      return true unless current
+
+      history_time(candidate) >= history_time(current)
+    end
+
+    def summary_time(record)
+      parse_time(record.dig("meta", "ended_at")) || parse_time(record.dig("meta", "started_at")) || Time.at(0)
+    end
+
+    def history_time(record)
+      parse_time(record["ended_at"]) || parse_time(record["started_at"]) || Time.at(0)
+    end
+
+    def parse_time(value)
+      Time.iso8601(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    def build_from_summary(record, summary_path, fallback_repo_root)
+      meta = record["meta"] || {}
+      actual = record["actual"] || {}
+      state = classify_summary_state(actual)
+      {
+        "id" => meta["id"].to_s,
+        "repo_root" => meta["repo"] || fallback_repo_root,
+        "state" => state,
+        "terminal" => state != "unknown",
+        "task_complete" => !!actual["task_complete"],
+        "exit" => blank_to_nil(actual["exit"]),
+        "exit_code" => actual["exit_code"],
+        "summary_out" => summary_path,
+        "started_at" => meta["started_at"],
+        "ended_at" => meta["ended_at"],
+        "source" => "summary_out"
+      }
+    end
+
+    def classify_summary_state(actual)
+      exit = actual["exit"].to_s
+      exit_code = actual["exit_code"]
+
+      return "completed" if exit == "success"
+      return "completed" if exit.empty? && exit_code == 0
+      return "failed" unless exit.empty? && exit_code.nil?
+
+      "unknown"
+    end
+
+    def build_from_history(record, fallback_repo_root)
+      status = record["status"].to_s
+      state =
+        case status
+        when "completed"
+          "completed"
+        when "failed", "timeout", "killed"
+          "failed"
+        else
+          "unknown"
+        end
+      {
+        "id" => record["id"].to_s,
+        "repo_root" => fallback_repo_root,
+        "state" => state,
+        "terminal" => state != "unknown",
+        "task_complete" => record["terminal_event"].to_s == "task_complete",
+        "exit" => history_exit(status),
+        "exit_code" => nil,
+        "summary_out" => blank_to_nil(record["summary_out_path"]),
+        "started_at" => record["started_at"],
+        "ended_at" => record["ended_at"],
+        "source" => "dispatch_history"
+      }
+    end
+
+    def history_exit(status)
+      case status
+      when "completed"
+        "success"
+      when "timeout"
+        "timeout"
+      when "killed"
+        "killed"
+      when "failed"
+        "failure"
+      else
+        nil
+      end
+    end
+
+    def blank_to_nil(value)
+      text = value.to_s
+      text.empty? ? nil : text
+    end
+  end
+end

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.7.4"
-  RELEASE_DATE = "2026-05-25"
+  VERSION = "0.7.5"
+  RELEASE_DATE = "2026-05-26"
 end

data/lib/harnex.rb

@@ -5,6 +5,7 @@ require "open3"
 require_relative "harnex/version"
 require_relative "harnex/core"
 require_relative "harnex/dispatch_history"
+require_relative "harnex/terminal_status"
 require_relative "harnex/watcher"
 require_relative "harnex/adapters"
 require_relative "harnex/runtime/session_state"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.7.5
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 2026-05-26 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.
@@ -65,6 +65,7 @@ files:
 - lib/harnex/runtime/message.rb
 - lib/harnex/runtime/session.rb
 - lib/harnex/runtime/session_state.rb
+- lib/harnex/terminal_status.rb
 - lib/harnex/version.rb
 - lib/harnex/watcher.rb
 - lib/harnex/watcher/inotify.rb