harnex 0.7.14 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e50f27f3d17436e058126d656fdaeb3dfd58cbfdb0e565b8f221ae6b579f3507
-  data.tar.gz: 01f08ae4414ed2e6a5d4d4503888349c7e27b7aee348b805a435f393ba0f95ad
+  metadata.gz: 9142cc69cec0a0cf0dc3961ccc27dc3728baea445c7d83b4c2d69a34b7e6a499
+  data.tar.gz: b89c616cb2484d48e74ef88985a438f7ebb1c22b1af17dd44cbaab3ee0c020cd
 SHA512:
-  metadata.gz: f62483a74ed5651eecc43c2e30f5020ddd077b0038a17522309af411335c86b94a04d45eec39a2d33defcbb0d781b7ac1c3085c34bd24d0ab1f9baaeb5ebbc32
-  data.tar.gz: 896793c0dc92d82f62989105714be633fc3b4966752fa3049d7258529cc31fbad2ac0ef1ff36bec2c5b9ac1b2baf42ac325d96f3fe9228f8efbfd0b61bc0e906
+  metadata.gz: 220566d1c646ca49b7f41f8ed053b2909dda8468ab3dc877bfcfe5f47b52988492d54b9d2fcc42ff0e42154921fde97af0824688b27df69e94bd9fc49b77c2f8
+  data.tar.gz: e52eca128c1f078171ab991acd25bafa810e8341a7f6c8f199535cd03b7a881ee03f2c4193afb01ece92cc00d0a8025a6bdb564739aeb13cbe6a02a4f4d87d0a

data/CHANGELOG.md

@@ -1,6 +1,49 @@
 # Changelog
 
-## [Unreleased]
+## [0.8.0] - 2026-08-02 | 08:46 PM | IST
+
+Minor bump: two behavior changes below (`wait --until done` exit codes,
+`--attempt-kind retry` now requiring `--parent-dispatch-id`).
+
+### Added
+
+- Dispatch-start records (#62): every dispatch appends a durable
+  `dispatch_start` row to the repo dispatch stream at registration (id,
+  session_id, pid, host, started_at, meta, schema_version); the
+  `dispatch_end` row written at teardown completes it. End rows now carry
+  `record_type` and `session_id` so readers can pair them.
+- `harnex history` now shows uncompleted dispatches as `running` (pid alive
+  on this host) or `interrupted` (pid gone, no end row) instead of hiding
+  them until teardown.
+- Duplicate-dispatch guard (#62): `harnex run --attempt-kind retry` requires
+  `--parent-dispatch-id`, and retry/fix/superseding dispatches naming a
+  still-running parent in the same repo are refused with a clear error.
+  `--allow-live-parent` overrides for intentional parallelism; `review` is
+  exempt.
+
+### Changed
+
+- `harnex wait --until done` now has a documented exit-code contract
+  (guides/04_monitoring.md): `0` accepted work, `1` failed, `2` completed but
+  proof rejected, `3` no such session, `124` timeout. The wrapped process's
+  exit code is reported as payload data instead of being passed through.
+  Payloads carry a `wait_result` field.
+- `harnex wait --until done` re-checks liveness every poll (registry, then
+  uncompleted start row with alive pid) and blocks while the session's pid
+  is alive. Stale exit-status files and events from an earlier dispatch that
+  reused the same id are ignored while a live session is in view.
+- `harnex status` no longer silently reports stale registry data as live:
+  rows are labelled `source: live|registry|dispatch_start` with
+  `degraded: true` when the live status API was unreachable. With `--id`, a
+  running session whose registry row is missing is still reported running
+  from its uncompleted start row.
+- One canonical repo resolution for all dispatch-stream writers and readers:
+  history rows now key off the session's `repo_root` (matching the summary
+  path) instead of the launch cwd, and `repo_key` canonicalizes symlinked
+  paths via realpath so registries written from a symlinked cwd stay visible
+  to checkers resolving the physical path.
+- Refreshed the codex app-server schema fixtures against codex-cli 0.145.0
+  (10 fixtures; upstream-additive changes only, no adapter impact).
 
 ## [0.7.14] - 2026-07-15 | 10:06 PM | IST
 

data/guides/04_monitoring.md

@@ -22,7 +22,53 @@ For unattended monitors on existing visible/detached sessions, prefer
 `task_failed` signal, or terminal exit, whichever comes first. Successful work
 exits `0`, failed work exits non-zero, and wall-clock caps exit `124`. For
 callers that need the lower-level primitive, `harnex wait --until done` exposes
-the same work fence. For structured sessions (Pi RPC and Codex app-server),
+the same work fence.
+
+## Live-Run Visibility
+
+Every dispatch appends a `dispatch_start` row to the repo's dispatch stream
+(`.harnex/dispatch.jsonl`) at registration; the `dispatch_end` row at teardown
+completes it. Between those two rows the run is visible to every documented
+signal, from any cwd in the same repo:
+
+- `harnex status --id X` reports `state=running` for a live session. When the
+  live HTTP status API is unreachable it still reports running from the
+  registry (or, failing that, from the uncompleted start row) and labels the
+  row `degraded: true` with `source` set to `registry` or `dispatch_start`.
+- `harnex history` shows uncompleted dispatches as `running` (pid alive) or
+  `interrupted` (pid gone, no end row). Completed dispatches render one
+  `dispatch_end` row.
+- `harnex wait --until done` blocks while the session's pid is alive, up to
+  `--timeout`. "No signal yet" from a live worker is never terminal.
+
+A monitor consulting these signals can never classify a healthy mid-run
+worker as dead. If `status` says running, do not dispatch a replacement.
+
+## `wait --until done` Exit-Code Contract
+
+| Code | `wait_result` | Meaning |
+| --- | --- | --- |
+| `0` | `done` | Completed with accepted work |
+| `1` | `failed` | Work failed, process failed, or killed |
+| `2` | `rejected_proof` | Completed but proof rejected (`completed_no_activity`, `report_missing`, `report_invalid`, `report_rejected`) |
+| `3` | `no_such_session` | No live, start, event, or terminal signal for the id |
+| `124` | `timeout` | `--timeout` elapsed while the session was still running |
+
+The JSON payload always carries `wait_result` plus the work-state fields
+(`done`, `work_state`, `outcome_class`, `artifact_report_status`). The child
+process's own exit code is reported as data (`exit_code`), never passed
+through as wait's exit status. Treat `2` as a work-acceptance failure, `3` as
+a coordination error (wrong id or wrong repo), and only `0` as success.
+
+## Duplicate-Dispatch Guard
+
+`harnex run --attempt-kind retry` requires `--parent-dispatch-id`, and any
+retry/fix/superseding dispatch whose named parent is still running in the
+same repo is refused. Wait for the parent
+(`harnex wait --id <parent> --until done`) or stop it first. Pass
+`--allow-live-parent` only for intentional parallelism (e.g. isolated
+worktrees). `--attempt-kind review` is exempt: a completed parent may still
+sit at a live prompt while its work is reviewed. For structured sessions (Pi RPC and Codex app-server),
 `harnex wait --until task_complete` remains the exact accepted-turn fence.
 Codex acknowledgment-only auto-stop turns are typed
 `completed_no_activity` and fail this fence without transcript parsing.

data/lib/harnex/commands/history.rb

@@ -1,5 +1,6 @@
 require "json"
 require "optparse"
+require "set"
 require "time"
 
 module Harnex
@@ -74,13 +75,60 @@ module Harnex
     end
 
     def filtered_records
-      records = load_records
+      records = derived_records
       records = records.select { |record| record["id"].to_s.include?(@options[:id]) } if @options[:id]
       records = records.select { |record| started_after?(record, @options[:since]) } if @options[:since]
       records = records.last(@options[:limit]) unless @options[:all]
       records
     end
 
+    # One row per dispatch: start rows completed by an end row are dropped
+    # (the end row carries the outcome); uncompleted start rows surface as
+    # running (pid alive on this host) or interrupted (no end row, pid gone).
+    def derived_records
+      raw = load_records
+      ended = Set.new
+      raw.each do |record|
+        next unless DispatchHistory.end_record?(record)
+
+        session_id = record["session_id"].to_s
+        ended << "sid:#{session_id}" unless session_id.empty?
+        ended << "leg:#{record['id']}|#{record['started_at']}"
+      end
+
+      raw.filter_map do |record|
+        next record unless DispatchHistory.start_record?(record)
+        next nil if start_completed?(record, ended)
+
+        derive_live_record(record)
+      end
+    end
+
+    def start_completed?(record, ended)
+      session_id = record["session_id"].to_s
+      return true if !session_id.empty? && ended.include?("sid:#{session_id}")
+
+      ended.include?("leg:#{record['id']}|#{record['started_at']}")
+    end
+
+    def derive_live_record(record)
+      alive = DispatchHistory.same_host?(record) &&
+              record["pid"] && Harnex.alive_pid?(record["pid"])
+      record.merge(
+        "status" => alive ? "running" : "interrupted",
+        "terminal_event" => nil,
+        "duration_s" => alive ? seconds_since(record["started_at"]) : nil,
+        "ended_at" => nil
+      )
+    end
+
+    def seconds_since(timestamp)
+      seconds = (Time.now - Time.iso8601(timestamp.to_s)).to_i
+      seconds.negative? ? 0 : seconds
+    rescue ArgumentError
+      nil
+    end
+
     def load_records
       path = DispatchHistory.path_for(Dir.pwd, global: @options[:global])
       return [] unless File.file?(path)
@@ -129,7 +177,9 @@ module Harnex
     end
 
     def format_duration(value)
-      seconds = Integer(value || 0)
+      return "-" if value.nil?
+
+      seconds = Integer(value)
       hours = seconds / 3600
       minutes = (seconds % 3600) / 60
       rest = seconds % 60

data/lib/harnex/commands/run.rb

@@ -33,8 +33,13 @@ module Harnex
       --id --description --detach --tmux --host --port --watch --watch-file
       --stall-after --max-resumes --preset --context --meta --summary-out
       --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
-      --require-artifact-report --require-attribution --auto-stop --fast --legacy-pty --help
+      --require-artifact-report --require-attribution --auto-stop --fast --legacy-pty
+      --allow-live-parent --help
     ].concat(TELEMETRY_FLAGS.keys).freeze
+
+    # Attempt kinds that redo the parent's work; dispatching one while the
+    # parent is still running duplicates work in the same checkout.
+    LIVE_PARENT_GUARDED_KINDS = %w[retry fix superseding].freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
       --max-resumes --preset --context --meta --summary-out --artifact-report
@@ -86,7 +91,13 @@ module Harnex
           --parent-attempt-id ID
                              Parent attempt id for retry/fix/review joins
           --attempt-kind KIND
-                             initial, retry, fix, review, or superseding (default: initial)
+                             initial, retry, fix, review, or superseding (default: initial).
+                             retry requires --parent-dispatch-id so the
+                             duplicate-dispatch guard can verify the parent
+          --allow-live-parent
+                             Dispatch even though --parent-dispatch-id names a
+                             session that is still running (intentional
+                             parallelism, e.g. isolated worktrees)
           --orchestration-run-id ID
                              Logical primary-orchestrator run id for queue rollups
           --orchestration-generation-id ID
@@ -164,6 +175,7 @@ module Harnex
         cwd: nil,
         root: nil,
         auto_stop: false,
+        allow_live_parent: false,
         detach: false,
         tmux: false,
         tmux_name: nil,
@@ -195,6 +207,7 @@ module Harnex
       @options[:artifact_report] = resolve_artifact_report(repo_root)
       @options[:id] ||= Harnex.generate_id(repo_root)
       validate_unique_id!(repo_root)
+      validate_live_parent_guard!(repo_root)
       effective_child_args = apply_context(apply_codex_service_tier(cli_name, child_args))
       adapter = Harnex.build_adapter(cli_name, effective_child_args, legacy_pty: @options[:legacy_pty])
       @options[:detach] = true if @options[:tmux]
@@ -258,6 +271,7 @@ module Harnex
         tmux_cmd += [flag, value] if flag && value
       end
       tmux_cmd << "--require-attribution" if @options[:require_attribution]
+      tmux_cmd << "--allow-live-parent" if @options[:allow_live_parent]
       tmux_cmd += ["--summary-out", @options[:summary_out]] if @options[:summary_out]
       tmux_cmd += ["--artifact-report", @options[:artifact_report]] if @options[:artifact_report]
       tmux_cmd << "--require-artifact-report" if @options[:require_artifact_report]
@@ -357,6 +371,33 @@ module Harnex
             "Use a different --id or stop the existing session first."
     end
 
+    # Duplicate-dispatch guard (issue #62): a retry/fix/superseding attempt
+    # whose parent dispatch is still running would duplicate work in the same
+    # checkout. Explicit --parent-dispatch-id only — the implicit HARNEX_ID
+    # lineage of a live spawner must not trip this.
+    def validate_live_parent_guard!(repo_root)
+      metadata = @options[:meta].is_a?(Hash) ? @options[:meta] : {}
+      kind = metadata["attempt_kind"].to_s
+      parent_id = metadata["parent_dispatch_id"].to_s.strip
+
+      if kind == "retry" && parent_id.empty?
+        raise "harnex run: --attempt-kind retry requires --parent-dispatch-id " \
+              "so the duplicate-dispatch guard can verify the parent is not still running."
+      end
+
+      return if @options[:allow_live_parent]
+      return if parent_id.empty?
+      return unless LIVE_PARENT_GUARDED_KINDS.include?(kind)
+
+      live = Harnex.active_sessions(repo_root, id: parent_id).first
+      return unless live
+
+      raise "harnex run: refusing #{kind} dispatch — parent dispatch #{parent_id.inspect} " \
+            "is still running (pid #{live['pid']}, started #{live['started_at']}). " \
+            "Wait for it (harnex wait --id #{parent_id} --until done), stop it, " \
+            "or pass --allow-live-parent for intentional parallelism."
+    end
+
     def build_session(adapter, repo_root)
       watch = Harnex.build_watch_config(@options[:watch], repo_root)
       Session.new(
@@ -541,6 +582,8 @@ module Harnex
           @options[:context] = required_option_value("--context", Regexp.last_match(1))
         when "--auto-stop"
           @options[:auto_stop] = true
+        when "--allow-live-parent"
+          @options[:allow_live_parent] = true
         when "--require-attribution"
           @options[:require_attribution] = true
         when "--fast"
@@ -646,7 +689,7 @@ module Harnex
         case arg
         when "--"
           return false
-        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--require-artifact-report", "--require-attribution", "--fast", "--legacy-pty"
+        when "-h", "--help", "--detach", "--tmux", "--auto-stop", "--require-artifact-report", "--require-attribution", "--fast", "--legacy-pty", "--allow-live-parent"
           nil
         when /\A--tmux=/
           nil

data/lib/harnex/commands/status.rb

@@ -97,14 +97,49 @@ module Harnex
       return live unless @options[:id]
       return [live.first] unless live.empty?
 
+      running = running_from_start_record(fallback_repo_root)
+      return [running] if running
+
       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
 
+    # Registry row missing but the dispatch stream has an uncompleted start
+    # row whose pid is alive: the worker is running, just not registry-visible
+    # from this context. Report running (labelled degraded), never dead.
+    def running_from_start_record(repo_root)
+      start = Harnex::DispatchHistory.live_start_record(repo_root: repo_root, id: @options[:id])
+      return nil unless start
+
+      {
+        "id" => start["id"].to_s,
+        "cli" => start["cli"],
+        "pid" => start["pid"],
+        "description" => start["description"],
+        "repo_root" => start["repo_root"] || repo_root,
+        "started_at" => start["started_at"],
+        "state" => "running",
+        "process_state" => "running",
+        "terminal" => false,
+        "task_complete" => false,
+        "task_failed" => false,
+        "done" => false,
+        "work_state" => "running",
+        "exit" => nil,
+        "exit_code" => nil,
+        "summary_out" => nil,
+        "ended_at" => nil,
+        "source" => "dispatch_start",
+        "degraded" => true,
+        "live_status" => "unreachable"
+      }
+    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)
+      degraded = session["live_status"] == "unreachable"
       session.merge(
         "state" => "running",
         "process_state" => "running",
@@ -117,7 +152,8 @@ module Harnex
         "exit_code" => nil,
         "summary_out" => nil,
         "ended_at" => nil,
-        "source" => "live"
+        "source" => degraded ? "registry" : "live",
+        "degraded" => degraded
       )
     end
 
@@ -131,6 +167,9 @@ module Harnex
         !session["last_failed_at"].to_s.empty?
     end
 
+    # On HTTP failure the row is still backed by a verified-alive pid, but the
+    # data is the registry snapshot, not the live API — label it as degraded
+    # instead of silently passing it off as live.
     def load_live_status(session)
       uri = URI("http://#{session.fetch('host')}:#{session.fetch('port')}/status")
       request = Net::HTTP::Get.new(uri)
@@ -140,11 +179,11 @@ module Harnex
         http.request(request)
       end
 
-      return session unless response.is_a?(Net::HTTPSuccess)
+      return session.merge("live_status" => "unreachable") unless response.is_a?(Net::HTTPSuccess)
 
-      session.merge(JSON.parse(response.body))
+      session.merge(JSON.parse(response.body)).merge("live_status" => "ok")
     rescue StandardError
-      session
+      session.merge("live_status" => "unreachable")
     end
 
     def render_table(sessions)

data/lib/harnex/commands/wait.rb

@@ -14,6 +14,19 @@ module Harnex
     EVENT_PREDICATES = %w[task_complete task_failed].freeze
     LEGACY_EVENT_TYPES = %w[agent_state exited task_complete task_failed].freeze
 
+    # Exit-code contract for `--until done` (documented in guides/04_monitoring.md).
+    DONE_EXIT_DONE = 0
+    DONE_EXIT_FAILED = 1
+    DONE_EXIT_REJECTED_PROOF = 2
+    DONE_EXIT_NO_SESSION = 3
+    DONE_EXIT_TIMEOUT = 124
+
+    # Outcome classes where the process completed but the work was not
+    # accepted: proof was missing, invalid, rejected, or nothing happened.
+    REJECTED_PROOF_CLASSES = %w[
+      completed_no_activity report_missing report_invalid report_rejected
+    ].freeze
+
     def self.usage(program_name = "harnex wait")
       <<~TEXT
         Usage: #{program_name} [options]
@@ -41,8 +54,18 @@ module Harnex
           #{program_name} --id cx-i-42 --until prompt --timeout 120
           #{program_name} --id cx-i-42
 
+        Exit codes for --until done:
+          0    completed with accepted work
+          1    failed (work failed, process failed, or killed)
+          2    completed but proof rejected (completed_no_activity,
+               report_missing, report_invalid, report_rejected)
+          3    no such session (no live, start, event, or terminal signal)
+          124  --timeout elapsed while the session was still running
+
         Gotchas:
           done is the safest work-level fence for monitors.
+          While the session's pid is alive, --until done blocks (up to
+          --timeout); "no signal yet" from a live worker is never terminal.
           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/
@@ -134,7 +157,9 @@ module Harnex
       end
     end
 
-    def scan_events(path, offset, predicate, task_complete_seen, start_time)
+    # min_ts: with a live session in view, events written before it started
+    # belong to an earlier run that reused the id — never match on them.
+    def scan_events(path, offset, predicate, task_complete_seen, start_time, min_ts: nil)
       return [nil, offset, task_complete_seen] unless File.exist?(path) && File.size(path) > offset
 
       File.open(path, "r") do |f|
@@ -142,6 +167,7 @@ module Harnex
         f.each_line do |line|
           event = parse_event(line)
           next unless event
+          next if stale_event?(event, min_ts)
 
           task_complete_seen = true if %w[task_complete task_failed].include?(event_type(event))
           if matches?(event, predicate, task_complete_seen)
@@ -154,6 +180,17 @@ module Harnex
       [nil, offset, task_complete_seen]
     end
 
+    def stale_event?(event, min_ts)
+      return false unless min_ts
+
+      # Events without a parseable ts (legacy formats) cannot be dated;
+      # treat them as fresh rather than silently dropping completion signals.
+      ts = parse_wait_time(event["ts"])
+      return false unless ts
+
+      ts < min_ts
+    end
+
     def parse_event(line)
       event = JSON.parse(line)
       event.is_a?(Hash) ? event : nil
@@ -206,11 +243,14 @@ module Harnex
         seq: event["seq"],
         waited_seconds: waited
       }
+      exit_code = 0
       if predicate == "done"
         failed = done_event_failed?(event)
+        exit_code = failed ? done_failure_exit_code(event["outcome_class"]) : DONE_EXIT_DONE
         payload.merge!(
           ok: !failed,
           status: failed ? "failed" : "done",
+          wait_result: done_wait_result(exit_code),
           state: "running",
           process_state: "running",
           terminal: false,
@@ -224,79 +264,136 @@ module Harnex
         payload[:last_error] = event["message"] || event["error"] if failed
       end
       puts JSON.generate(payload)
-      return 1 if predicate == "done" && done_event_failed?(event)
+      exit_code
+    end
+
+    def done_failure_exit_code(outcome_class)
+      REJECTED_PROOF_CLASSES.include?(outcome_class.to_s) ? DONE_EXIT_REJECTED_PROOF : DONE_EXIT_FAILED
+    end
 
-      0
+    def done_wait_result(exit_code)
+      case exit_code
+      when DONE_EXIT_DONE then "done"
+      when DONE_EXIT_REJECTED_PROOF then "rejected_proof"
+      else "failed"
+      end
     end
 
+    # Contract: while the session's pid is alive, block (up to --timeout).
+    # Liveness is re-checked every poll from the registry, falling back to an
+    # uncompleted dispatch-start row, so a running worker is never classified
+    # as dead just because one signal source is missing. "No signal yet"
+    # while alive is not terminal.
     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
+      observed_live = nil
+      session_started_at = nil
 
-      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
+      loop do
+        live = live_session(repo_root)
+        if live
+          observed_live = live
+          session_started_at ||= parse_wait_time(live["started_at"])
         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)
+        status, offset, task_complete_seen =
+          scan_events(events_path, offset, "done", task_complete_seen, start_time, min_ts: session_started_at)
         return status if status
 
-        unless registry
+        unless live
+          if observed_live
+            return resolve_after_exit(repo_root, events_path, exit_path, offset,
+                                      task_complete_seen, start_time, observed_live, session_started_at)
+          end
+
+          # Historical query: never observed the session alive.
+          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
-          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], status: "no_such_session",
+                               wait_result: "no_such_session", state: "unknown", process_state: "unknown",
+                               terminal: false, task_complete: false, done: false, work_state: "unknown")
+            return DONE_EXIT_NO_SESSION
+          end
         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
+          puts JSON.generate(ok: false, id: @options[:id], status: "timeout", wait_result: "timeout",
+                             waited_seconds: waited, done: false,
+                             work_state: live ? "running" : "unknown")
+          return DONE_EXIT_TIMEOUT
         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)
+        sleep EVENT_POLL_INTERVAL
+      end
+    end
 
-            terminal = done_status(repo_root)
-            return emit_done_terminal_status(terminal) if terminal
+    # Registry row first; when it is not visible from this context, an
+    # uncompleted dispatch-start row with an alive pid still proves liveness.
+    def live_session(repo_root)
+      registry = Harnex.read_registry(repo_root, @options[:id])
+      return registry if registry
 
-            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
+      Harnex::DispatchHistory.live_start_record(repo_root: repo_root, id: @options[:id])
+    end
 
-        sleep EVENT_POLL_INTERVAL
+    # The session was alive and its pid is now gone: give teardown a bounded
+    # grace to land the final events, summary row, and exit-status file, then
+    # classify from the freshest signal that belongs to the observed session.
+    def resolve_after_exit(repo_root, events_path, exit_path, offset, task_complete_seen,
+                           start_time, observed_live, session_started_at)
+      await_exit_status(exit_path)
+
+      status, _offset, _seen =
+        scan_events(events_path, offset, "done", task_complete_seen, start_time, min_ts: session_started_at)
+      return status if status
+
+      if File.exist?(exit_path) && fresh_exit_status?(exit_path, observed_live, session_started_at)
+        return emit_done_exit_status(exit_path, @options[:id])
       end
+
+      terminal = done_status(repo_root, min_started_at: session_started_at)
+      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",
+                         wait_result: "failed", waited_seconds: waited)
+      DONE_EXIT_FAILED
+    end
+
+    # Guards against classifying from an exit-status file left behind by an
+    # earlier dispatch that reused the same id.
+    def fresh_exit_status?(exit_path, observed_live, session_started_at)
+      data = JSON.parse(File.read(exit_path))
+      observed_session_id = observed_live["session_id"].to_s
+      exit_session_id = data["session_id"].to_s
+      return exit_session_id == observed_session_id unless exit_session_id.empty? || observed_session_id.empty?
+
+      exited_at = parse_wait_time(data["exited_at"])
+      return true unless exited_at && session_started_at
+
+      exited_at >= session_started_at
+    rescue StandardError
+      true
+    end
+
+    def parse_wait_time(value)
+      Time.iso8601(value.to_s)
+    rescue ArgumentError
+      nil
     end
 
     def wait_until_state
@@ -441,11 +538,16 @@ module Harnex
       status
     end
 
-    def done_status(repo_root)
+    def done_status(repo_root, min_started_at: nil)
       status = Harnex::TerminalStatus.resolve(id: @options[:id], repo_root: repo_root)
       return nil unless status
       return nil unless status["done"] || status["terminal"]
 
+      if min_started_at
+        row_started = parse_wait_time(status["started_at"])
+        return nil if row_started && row_started < min_started_at
+      end
+
       status
     end
 
@@ -457,6 +559,7 @@ module Harnex
       exit_success = !task_failed && (exit_code.nil? || exit_code.to_i == 0)
       state = exit_success ? "completed" : "failed"
       done = task_complete || exit_success
+      result_code = done ? DONE_EXIT_DONE : done_failure_exit_code(data["outcome_class"])
       payload = data.merge(
         "ok" => done,
         "id" => id,
@@ -466,32 +569,26 @@ module Harnex
         "task_complete" => task_complete,
         "task_failed" => task_failed,
         "done" => done,
-        "work_state" => Harnex.work_state_for(state, task_complete: task_complete)
+        "work_state" => Harnex.work_state_for(state, task_complete: task_complete),
+        "wait_result" => done_wait_result(result_code)
       )
-      success = done
       puts JSON.generate(payload)
-      return 0 if success
-
-      exit_code.is_a?(Integer) && exit_code.positive? ? exit_code : 1
+      result_code
     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
+                         task_complete: false, done: false, work_state: "failed",
+                         status: "invalid_exit_status", wait_result: "failed")
+      DONE_EXIT_FAILED
     end
 
     def emit_done_terminal_status(status)
       payload = terminal_payload(status)
       payload[:ok] = !!payload[:done]
       payload[:status] = payload[:done] ? "done" : status["state"]
+      result_code = payload[:done] ? DONE_EXIT_DONE : done_failure_exit_code(status["outcome_class"])
+      payload[:wait_result] = done_wait_result(result_code)
       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
+      result_code
     end
 
     def emit_terminal_status(status)

data/lib/harnex/commands/watch.rb

@@ -350,8 +350,9 @@ module Harnex
           -h, --help           Show this help
 
         `harnex watch` is the safe watcher for existing --tmux or detached
-        dispatches. It exits 0 for task_complete/done, non-zero for task_failed
-        or failed terminal summaries, and 124 for --max-wait timeouts.
+        dispatches. Exit codes follow the `harnex wait --until done` contract:
+        0 accepted work, 1 failed, 2 completed-but-proof-rejected, 3 no such
+        session, 124 for --max-wait timeouts.
 
         For launch-and-babysit stall recovery, use `harnex run --watch`.
       TEXT

data/lib/harnex/core.rb

@@ -157,8 +157,18 @@ module Harnex
     {}
   end
 
+  # Canonical path resolution shared by every registry/exit/events writer and
+  # reader. realpath collapses symlinked prefixes so a session registered from
+  # a symlinked cwd stays visible to checkers resolving the physical path.
+  def canonical_repo_root(path)
+    expanded = File.expand_path(path)
+    File.realpath(expanded)
+  rescue StandardError
+    expanded
+  end
+
   def repo_key(repo_root)
-    Digest::SHA256.hexdigest(repo_root)[0, 16]
+    Digest::SHA256.hexdigest(canonical_repo_root(repo_root))[0, 16]
   end
 
   def normalize_id(id)

data/lib/harnex/dispatch_history.rb

@@ -62,12 +62,107 @@ module Harnex
       end
     end
 
+    def start_record?(record)
+      record.is_a?(Hash) && record["record_type"] == "dispatch_start"
+    end
+
+    def end_record?(record)
+      return false unless record.is_a?(Hash)
+      return true if record["record_type"] == "dispatch_end"
+
+      # Legacy end rows predate record_type.
+      record["schema_version"] == 1 && record.key?("status") && !record.key?("record_type")
+    end
+
+    def end_matches_start?(end_record, start_record)
+      end_session = end_record["session_id"].to_s
+      start_session = start_record["session_id"].to_s
+      return end_session == start_session unless end_session.empty? || start_session.empty?
+
+      end_record["id"].to_s == start_record["id"].to_s &&
+        end_record["started_at"].to_s == start_record["started_at"].to_s
+    end
+
+    # Latest start row for `id` and any end row that completes it.
+    def latest_rows(path, id)
+      latest_start = nil
+      matching_end = nil
+
+      return { start: nil, end: nil } unless File.file?(path)
+
+      File.foreach(path) do |line|
+        record = JSON.parse(line)
+        next unless record.is_a?(Hash)
+        next unless record["id"].to_s == id
+
+        if start_record?(record)
+          latest_start = record
+          matching_end = nil
+        elsif end_record?(record)
+          matching_end = record if latest_start && end_matches_start?(record, latest_start)
+        end
+      rescue JSON::ParserError
+        next
+      end
+
+      { start: latest_start, end: matching_end }
+    end
+
+    # A dispatch_start row with no completing end row whose pid is alive on
+    # this host — evidence of a running session even when the live registry
+    # is not visible from the caller's context.
+    def live_start_record(repo_root:, id:)
+      normalized_id = Harnex.normalize_id(id)
+      rows = latest_rows(path_for(repo_root), normalized_id)
+      start = rows[:start]
+      return nil unless start
+      return nil if rows[:end]
+      return nil unless same_host?(start)
+
+      pid = start["pid"]
+      return nil unless pid && Harnex.alive_pid?(pid)
+
+      start
+    rescue StandardError
+      nil
+    end
+
+    def same_host?(record)
+      host = record["host"].to_s
+      return true if host.empty?
+
+      host == Harnex.host_info[:host].to_s
+    end
+
+    # Appended at registration so a running dispatch always has a durable
+    # trace; the dispatch_end row written in finalize_session! completes it.
+    def build_start_record(session)
+      {
+        schema_version: 1,
+        record_type: "dispatch_start",
+        id: session.id,
+        session_id: session.session_id,
+        pid: session.pid,
+        host: Harnex.host_info[:host],
+        cli: session.adapter.key,
+        description: session.description,
+        started_at: session.started_at.utc.iso8601,
+        repo_root: session.repo_root,
+        tier: session.__send__(:meta_hash)["tier"],
+        meta: session.__send__(:meta_hash),
+        summary_out_path: session.summary_out,
+        events_log_path: session.events_log_path
+      }
+    end
+
     def build_record(session)
       ended_at = session.ended_at || Time.now
       status, terminal_event = classify(session)
       {
         schema_version: 1,
+        record_type: "dispatch_end",
         id: session.id,
+        session_id: session.session_id,
         description: session.description,
         cli: session.adapter.key,
         started_at: session.started_at.utc.iso8601,

data/lib/harnex/runtime/session.rb

@@ -205,6 +205,7 @@ module Harnex
       @server = ApiServer.new(self)
       @server.start
       persist_registry
+      append_dispatch_start_record
 
       stdin_state = STDIN.tty? ? STDIN.raw! : nil
       watch_thread = start_watch_thread
@@ -474,6 +475,7 @@ module Harnex
       @server = ApiServer.new(self)
       @server.start
       persist_registry
+      append_dispatch_start_record
 
       watch_thread = start_watch_thread
       @inbox.start
@@ -1993,13 +1995,26 @@ module Harnex
       warn("harnex: failed to write dispatch summary #{summary_out}: #{e.message}")
     end
 
+    def append_dispatch_start_record
+      DispatchHistory.append(dispatch_history_path, DispatchHistory.build_start_record(self))
+    rescue StandardError => e
+      warn("harnex: failed to write dispatch start record: #{e.message}")
+    end
+
     def append_dispatch_history_record
-      path = DispatchHistory.path_for(launch_cwd)
-      DispatchHistory.append(path, DispatchHistory.build_record(self))
+      DispatchHistory.append(dispatch_history_path, DispatchHistory.build_record(self))
     rescue StandardError => e
       warn("harnex: failed to write dispatch history: #{e.message}")
     end
 
+    # One canonical stream per session: the start row and the end row must
+    # land in the same file so readers can pair them. repo_root — not the
+    # launch cwd — is the root that registry, events, and default summary
+    # paths already key off.
+    def dispatch_history_path
+      @dispatch_history_path ||= DispatchHistory.path_for(repo_root)
+    end
+
     def normalized_usage_summary(summary)
       summary ||= {}
       USAGE_FIELDS.to_h { |field| [field, summary[field] || summary[field.to_s]] }

data/lib/harnex/terminal_status.rb

@@ -78,6 +78,7 @@ module Harnex
       File.foreach(path) do |line|
         record = JSON.parse(line)
         next unless record.is_a?(Hash)
+        next if DispatchHistory.start_record?(record)
 
         if summary_record?(record) && record.dig("meta", "id").to_s == id
           summary_record = record

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.7.14"
-  RELEASE_DATE = "2026-07-15"
+  VERSION = "0.8.0"
+  RELEASE_DATE = "2026-08-02"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.7.14
+  version: 0.8.0
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-15 00:00:00.000000000 Z
+date: 2026-08-02 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.