harnex 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcf0c88485eceb630094f32cd520c12f6c3d5915f2e2b7790191c2ed98a236a5
-  data.tar.gz: f228c15c98a47d69b5b4c7129373f88d5eb42f6413ac998995294ef3271d99e3
+  metadata.gz: 3ea3eab047cc2e9f086fba4cfb98c6f585ffe888fdee0fb018c35515fe6257b4
+  data.tar.gz: ba40b96028fd01e6ade7517374e7d26d92a5d147a7be2ec08a581cd0203dae62
 SHA512:
-  metadata.gz: e3e6e7d4fe9b88ace781c9c9bc587316fce5e405063e6a575ddf5f46b4b76f6a05f7892e36656b7ef0b9160a5ad6890c1af5fe8e83ecd993c14d229c9a7d1468
-  data.tar.gz: c043e50074d2100651cbc22585f7d046f5621c51a5ea6d0433d24200f174df98c7fdfd4ea1ec46633cfeae496776c82b08e177abdae7abe547d2244da4f66be0
+  metadata.gz: e1e85c57df13dd411b10308659b72376f9491f1c6e4d7c4e5d906f9f78096dc0f82a0ac866c01e356d75cedb5f285b71970d0ea175e5935ca8ed0e3bcf40dd88
+  data.tar.gz: 1283d788ceaff2e608f7e13b7f4f640d65d9f683e35cbe649cc9dd7d0223e094740df146fbe10ed6fa15685bf27671e9059c6378bb2bc8acc5c850aef5f6c9ab

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.12.0] - 2026-09-03 | 10:09 AM | IST
+
+### Added
+
+- Registered sessions now atomically publish a typed completion marker under
+  `$HARNEX_STATE_DIR/done/` at the first accepted, rejected, failed, or error
+  work result, without requiring a `wait` or `watch` client.
+- `harnex run --on-done CMD` launches one non-blocking trusted local shell hook
+  with typed completion, receipt, commit, and elapsed-time environment values.
+  The option works in foreground, detached, and tmux launches.
+
+### Changed
+
+- `harnex status` now renders settled live work (`done`, `rejected`, or
+  `failed`) ahead of an adapter's prompt/busy state. Existing JSON fields and
+  the v2 dispatch envelope remain unchanged.
+
 ## [0.11.0] - 2026-08-14 | 01:03 PM | IST
 
 ### Fixed

data/guides/01_dispatch.md

@@ -87,6 +87,25 @@ for i in 1 2 3; do harnex watch --id w-$i --until done --max-wait 90m & done
 wait
 ```
 
+For unattended work, add a session-owned push signal rather than depending on
+one long blocking watcher call:
+
+```bash
+harnex run pi --id pi-i-NN --tmux pi-i-NN \
+  --context "Read and execute /tmp/task-NN.md" --auto-stop \
+  --on-done 'printf "%s %s\n" "$HARNEX_ID" "$HARNEX_OUTCOME" >> koder/scratch/HARNEX_WAKE.txt'
+```
+
+Every registered session writes
+`$HARNEX_STATE_DIR/done/<repo-key>--<normalized-id>.<outcome>`, even without a
+hook. `--on-done CMD` receives `HARNEX_ID`, `HARNEX_OUTCOME`,
+`HARNEX_WORK_STATE`, `HARNEX_RECEIPT_PATH`, `HARNEX_END_SHA`, and
+`HARNEX_ELAPSED_S`. Use a gitignored wake file. `CMD` is trusted `/bin/sh -c`
+input; never embed secrets in the command line.
+
+A push only wakes the consumer. Even `completed` requires report, artifact,
+test, and Git verification plus bounded `harnex watch --until done` calls.
+
 Rule: when you use `--tmux`, pass the same name as `--id`. If you pass only
 `--tmux NAME`, harnex creates a random session ID and the pane name no longer
 matches `harnex status` or `harnex pane --id`.

data/guides/04_monitoring.md

@@ -17,12 +17,30 @@ Prefer signals in this order:
 | `harnex pane` | Live UI interpretation and prompt/error diagnosis |
 | `harnex status` | Session liveness and coarse state |
 
-For unattended monitors on existing visible/detached sessions, prefer
-`harnex watch --until done`: it returns on the work-level `task_complete` or
+For unattended sessions, combine bounded watcher calls with the runner-owned
+push path. Every session writes
+`$HARNEX_STATE_DIR/done/<repo-key>--<id>.<outcome>` at its first work-terminal
+result. `harnex run --on-done CMD` can also launch one non-blocking local hook,
+even without a watcher and while the agent remains alive at a prompt:
+
+```bash
+harnex run pi --id pi-i-NN --tmux pi-i-NN --context "Read the task brief" \
+  --auto-stop \
+  --on-done 'printf "%s %s\n" "$HARNEX_ID" "$HARNEX_OUTCOME" >> koder/scratch/HARNEX_WAKE.txt'
+harnex watch --id pi-i-NN --until done --max-wait 30m
+```
+
+Use a gitignored wake destination. `CMD` is trusted shell input; never embed
+secrets. It receives `HARNEX_ID`, `HARNEX_OUTCOME`, `HARNEX_WORK_STATE`,
+`HARNEX_RECEIPT_PATH`, `HARNEX_END_SHA`, and `HARNEX_ELAPSED_S`. `completed`
+wakes the consumer but does not certify the prose; verify the receipt and
+artifact before acting.
+
+`harnex watch --until done` returns on the work-level `task_complete` or
 `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.
+the same work fence. Do not park an orchestrator in one unbounded watcher call.
 
 ## Live-Run Visibility
 
@@ -31,8 +49,10 @@ Every dispatch appends a `dispatch_start` row to the repo's dispatch stream
 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
+- `harnex status --id X` reports settled work as `done`, `rejected`, or
+  `failed` even while the adapter is back at `prompt`. When work is unsettled,
+  it reports the adapter input state. If 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
@@ -208,7 +228,8 @@ interpretation.
 - Polling `state=completed` alone and missing live sessions with `task_complete=true`.
 - Polling `state=prompt` alone and calling it done.
 - Wrapping `harnex wait` in loops that swallow non-zero `task_failed` results.
-- Blocking orchestrators on `/tmp/*-done.txt` as the only completion signal.
+- Blocking orchestrators on caller-owned `/tmp/*-done.txt` as the only completion signal.
+- Using one long watcher call without the runner-owned marker or `--on-done` push path.
 - 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/lib/harnex/commands/run.rb

@@ -33,7 +33,7 @@ module Harnex
       --id --description --detach --tmux --host --port --watch --watch-file
       --stall-after --max-resumes --preset --context --meta
       --artifact-report --validation-report --cwd --root --timeout --inbox-ttl
-      --require-artifact-report --require-attribution --auto-stop --fast --legacy-pty
+      --require-artifact-report --require-attribution --auto-stop --on-done --fast --legacy-pty
       --allow-live-parent --help
     ].concat(TELEMETRY_FLAGS.keys).freeze
 
@@ -43,7 +43,7 @@ module Harnex
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
       --max-resumes --preset --context --meta --artifact-report
-      --validation-report --cwd --root --timeout --inbox-ttl
+      --validation-report --on-done --cwd --root --timeout --inbox-ttl
     ].concat(TELEMETRY_FLAGS.keys).freeze
 
     def self.usage(program_name = "harnex run")
@@ -64,6 +64,7 @@ module Harnex
           --watch-file PATH  Auto-send a file-change hook on modification
           --context TEXT     Inject as the initial prompt (prepends session header)
           --auto-stop        Stop after the first accepted task completion from --context
+          --on-done CMD      Launch /bin/sh -c CMD once at the first typed work result
           --fast             (codex only) Use Codex service_tier="fast".
                              Default Codex runs force service_tier="flex".
           --meta JSON        Attach parsed JSON metadata to the started event
@@ -124,6 +125,8 @@ module Harnex
           Bare `--watch` enables the babysitter.
           --auto-stop requires --context. Structured Codex turns only count as
           accepted completion after command/tool activity or a Git delta.
+          --on-done CMD is trusted local shell input. Do not put secrets in CMD;
+          command lines may be visible to local process inspection.
           Every dispatch gets a harness-authored receipt. Workers may write only
           optional claims to HARNEX_ARTIFACT_CLAIMS_PATH; claims never accept work.
           Explicit --stall-after/--max-resumes values override --preset defaults.
@@ -177,6 +180,7 @@ module Harnex
         cwd: nil,
         root: nil,
         auto_stop: false,
+        on_done: nil,
         allow_live_parent: false,
         detach: false,
         tmux: false,
@@ -267,6 +271,7 @@ module Harnex
       tmux_cmd += ["--watch-file", @options[:watch]] if @options[:watch]
       tmux_cmd += ["--context", @options[:context]] if @options[:context]
       tmux_cmd << "--auto-stop" if @options[:auto_stop]
+      tmux_cmd += ["--on-done", @options[:on_done]] if @options[:on_done]
       tmux_cmd += ["--meta", JSON.generate(@options[:meta])] if @options[:meta]
       @options[:telemetry].each do |key, value|
         flag = TELEMETRY_KEYS_TO_FLAGS[key]
@@ -457,6 +462,7 @@ module Harnex
         require_artifact_report: @options[:require_artifact_report],
         inbox_ttl: @options[:inbox_ttl],
         auto_stop: @options[:auto_stop],
+        on_done: @options[:on_done],
         launch_cwd: history_cwd,
         child_cwd: session_child_cwd
       )
@@ -624,6 +630,11 @@ module Harnex
           @options[:context] = required_option_value("--context", Regexp.last_match(1))
         when "--auto-stop"
           @options[:auto_stop] = true
+        when "--on-done"
+          index += 1
+          @options[:on_done] = required_option_value(arg, argv[index])
+        when /\A--on-done=(.+)\z/
+          @options[:on_done] = required_option_value("--on-done", Regexp.last_match(1))
         when "--allow-live-parent"
           @options[:allow_live_parent] = true
         when "--require-attribution"
@@ -732,7 +743,7 @@ module Harnex
           nil
         when *VALUE_FLAGS
           index += 1
-        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|artifact-report|validation-report|cwd|root|timeout|inbox-ttl)=/
+        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|artifact-report|validation-report|on-done|cwd|root|timeout|inbox-ttl)=/
           nil
         when telemetry_equals_regex
           nil
@@ -753,7 +764,7 @@ module Harnex
         arg.start_with?(
           "--id=", "--description=", "--tmux=", "--host=", "--port=", "--watch=", "--watch-file=",
           "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--meta=",
-          "--artifact-report=", "--validation-report=", "--cwd=", "--root=", "--timeout=", "--inbox-ttl=",
+          "--artifact-report=", "--validation-report=", "--on-done=", "--cwd=", "--root=", "--timeout=", "--inbox-ttl=",
           *TELEMETRY_EQUALS_PREFIXES
         )
     end

data/lib/harnex/commands/status.rb

@@ -8,6 +8,7 @@ module Harnex
   class Status
     DESCRIPTION_WIDTH = 30
     REPO_WIDTH = 20
+    REJECTED_OUTCOME_CLASSES = Session::PROOF_REJECTION_CLASSES
 
     def self.usage(program_name = "harnex status")
       <<~TEXT
@@ -30,8 +31,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.
+          Settled work outranks prompt state in the table: done, rejected, or failed.
+          JSON `done`/`work_state` retains the structured work-level fields.
           A prompt-like state is not a completion signal by itself.
       TEXT
     end
@@ -217,6 +218,13 @@ module Harnex
     end
 
     def table_state(session)
+      failed = task_failed?(session) || session["work_state"].to_s == "failed"
+      completed = task_complete?(session) || session["work_state"].to_s == "completed"
+      if failed || completed
+        return "rejected" if rejected_work?(session)
+        return failed ? "failed" : "done"
+      end
+
       input_state = session.dig("input_state", "state").to_s
       return input_state unless input_state.empty?
 
@@ -224,6 +232,12 @@ module Harnex
       state.empty? ? "-" : state
     end
 
+    def rejected_work?(session)
+      return true if REJECTED_OUTCOME_CLASSES.include?(session["outcome_class"].to_s)
+
+      !task_failed?(session) && session["artifact_report_status"].to_s == "rejected"
+    end
+
     def timeago(timestamp)
       return "-" if timestamp.to_s.empty?
 

data/lib/harnex/core.rb

@@ -24,6 +24,8 @@ module Harnex
   GIT_FINGERPRINT_SAMPLE_BYTES = 64 * 1024
   STATE_DIR = File.expand_path(env_value("HARNEX_STATE_DIR", default: "~/.local/state/harnex"))
   SESSIONS_DIR = File.join(STATE_DIR, "sessions")
+  COMPLETION_OUTCOMES = %w[completed rejected failed error].freeze
+  COMPLETION_MARKERS_DIR = File.join(STATE_DIR, "done")
   WatchConfig = Struct.new(:absolute_path, :display_path, :hook_message, :debounce_seconds, keyword_init: true)
   ID_ADJECTIVES = %w[
     bold blue calm cool dark dry fast gold gray green
@@ -395,6 +397,19 @@ module Harnex
     File.join(exit_dir, "#{session_file_slug(repo_root, id)}.json")
   end
 
+  def completion_marker_path(repo_root, id, outcome)
+    normalized_outcome = outcome.to_s
+    unless COMPLETION_OUTCOMES.include?(normalized_outcome)
+      raise ArgumentError, "unsupported completion outcome #{outcome.inspect}"
+    end
+
+    File.join(COMPLETION_MARKERS_DIR, "#{session_file_slug(repo_root, id)}.#{normalized_outcome}")
+  end
+
+  def completion_marker_paths(repo_root, id)
+    COMPLETION_OUTCOMES.map { |outcome| completion_marker_path(repo_root, id, outcome) }
+  end
+
   def output_log_path(repo_root, id)
     output_dir = File.join(STATE_DIR, "output")
     FileUtils.mkdir_p(output_dir)

data/lib/harnex/runtime/completion_notifier.rb

@@ -0,0 +1,137 @@
+require "time"
+
+module Harnex
+  class CompletionNotifier
+    WORK_STATES = {
+      "completed" => "completed", "rejected" => "failed",
+      "failed" => "failed", "error" => "failed"
+    }.freeze
+
+    def initialize(repo_root:, id:, session_id:, receipt_path:, hook_command: nil,
+                   started_at: Time.now, clock: nil, event_sink: nil, spawn: nil,
+                   detach: nil, atomic_write: nil, remove: nil, stderr: $stderr)
+      @repo_root = Harnex.canonical_repo_root(repo_root)
+      @id = Harnex.normalize_id(id)
+      @session_id = session_id.to_s
+      @receipt_path = receipt_path.to_s
+      @hook_command = hook_command.to_s
+      @hook_command = nil if @hook_command.empty?
+      @started_at = started_at
+      @clock = clock || -> { Time.now }
+      @event_sink = event_sink
+      @spawn = spawn || method(:spawn_hook)
+      @detach = detach || ->(pid) { Process.detach(pid) }
+      @atomic_write = atomic_write || Harnex.method(:atomic_write_json)
+      @remove = remove || ->(path) { FileUtils.rm_f(path) }
+      @stderr = stderr
+      @mutex = Mutex.new
+      @registered = false
+      @notified = false
+    end
+
+    # Registration is the stale-marker boundary for a reused repo/id pair.
+    def register!
+      @mutex.synchronize do
+        return true if @registered
+
+        Harnex.completion_marker_paths(@repo_root, @id).each do |path|
+          @remove.call(path)
+        rescue StandardError => e
+          report_error("completion marker cleanup failed", "cleanup", e, path: path)
+        end
+        @registered = true
+      end
+      true
+    end
+
+    def notify(outcome:, work_state:, outcome_class:, artifact_report_status:,
+               end_sha:, terminal_signal:)
+      outcome = outcome.to_s
+      work_state = work_state.to_s
+      expected = WORK_STATES[outcome]
+      raise ArgumentError, "unsupported completion outcome #{outcome.inspect}" unless expected
+      raise ArgumentError, "#{outcome.inspect} completion requires work_state #{expected.inspect}" unless work_state == expected
+      return false unless @mutex.synchronize do
+        @registered && !@notified ? (@notified = true) : false
+      end
+
+      now = @clock.call
+      path = Harnex.completion_marker_path(@repo_root, @id, outcome)
+      payload = {
+        schema_version: 1, id: @id, session_id: @session_id,
+        repo_root: @repo_root, outcome: outcome, work_state: work_state,
+        outcome_class: optional_string(outcome_class),
+        artifact_report_status: optional_string(artifact_report_status),
+        receipt_path: @receipt_path, end_sha: optional_string(end_sha),
+        elapsed_s: elapsed_seconds(now), terminal_signal: terminal_signal.to_s,
+        notified_at: now.utc.iso8601
+      }
+      marker_written = write_marker(path, payload)
+      hook_launched = launch_hook(payload)
+      emit("completion_notification", outcome: outcome, work_state: work_state,
+           marker_path: path, marker_written: marker_written,
+           hook_configured: !@hook_command.nil?, hook_launched: hook_launched)
+      true
+    end
+
+    private
+
+    def optional_string(value)
+      text = value.to_s
+      text.empty? ? nil : text
+    end
+
+    def elapsed_seconds(now)
+      [(now - @started_at).to_i, 0].max
+    rescue StandardError
+      0
+    end
+
+    def write_marker(path, payload)
+      @atomic_write.call(path, payload)
+      true
+    rescue StandardError => e
+      report_error("completion marker write failed", "marker", e, path: path)
+      false
+    end
+
+    def launch_hook(payload)
+      return false unless @hook_command
+
+      env = {
+        "HARNEX_ID" => @id,
+        "HARNEX_OUTCOME" => payload.fetch(:outcome),
+        "HARNEX_WORK_STATE" => payload.fetch(:work_state),
+        "HARNEX_RECEIPT_PATH" => @receipt_path,
+        "HARNEX_END_SHA" => payload[:end_sha].to_s,
+        "HARNEX_ELAPSED_S" => payload.fetch(:elapsed_s).to_s
+      }
+      pid = @spawn.call(env, @hook_command, {
+        chdir: @repo_root, in: File::NULL, out: @stderr, err: @stderr
+      })
+      @detach.call(pid)
+      true
+    rescue StandardError => e
+      report_error("completion hook launch failed", "hook", e)
+      false
+    end
+
+    def spawn_hook(env, command, options)
+      Process.spawn(env, "/bin/sh", "-c", command, **options)
+    end
+
+    # Do not include exception messages: injected spawn failures can echo CMD.
+    def report_error(message, component, error, path: nil)
+      @stderr.puts("harnex: #{message} (#{error.class})") rescue nil
+      payload = { component: component, error_class: error.class.name }
+      payload[:path] = path if path
+      emit("completion_notification_error", **payload)
+    end
+
+    def emit(type, **payload)
+      @event_sink&.call(type, payload)
+    rescue StandardError => e
+      @stderr.puts("harnex: completion diagnostic event failed (#{e.class})") rescue nil
+    end
+  end
+end

data/lib/harnex/runtime/session.rb

@@ -1,5 +1,6 @@
 require "io/console"
 require "json"
+require "monitor"
 require "pty"
 require "shellwords"
 
@@ -39,6 +40,9 @@ module Harnex
       adapter_close real_disconnections stream_interruptions stalls force_resumes compactions recovered
     ].freeze
     SUCCESSFUL_TURN_STATUSES = %w[completed success succeeded].freeze
+    PROOF_REJECTION_CLASSES = %w[
+      completed_no_activity report_missing report_invalid report_rejected
+    ].freeze
     class EventCounters
       def initialize
         @counts = {
@@ -91,7 +95,7 @@ module Harnex
                 :output_log_path, :events_log_path, :started_at, :ended_at, :exit_code, :term_signal,
                 :require_artifact_report
 
-    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, artifact_report_path: nil, require_artifact_report: false, inbox_ttl: Inbox::DEFAULT_TTL, auto_stop: false, launch_cwd: nil, child_cwd: nil)
+    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, artifact_report_path: nil, require_artifact_report: false, inbox_ttl: Inbox::DEFAULT_TTL, auto_stop: false, on_done: nil, launch_cwd: nil, child_cwd: nil, completion_notifier: nil)
       @adapter = adapter
       @command = command
       @repo_root = repo_root
@@ -132,6 +136,20 @@ module Harnex
       @injected_count = 0
       @last_injected_at = nil
       @started_at = Time.now
+      @completion_transition_lock = Monitor.new
+      @completion_notification_mutex = Mutex.new
+      @completion_notification_registered = false
+      @completion_notification_sent = false
+      @pending_completion_notification = nil
+      @completion_notifier = completion_notifier || CompletionNotifier.new(
+        repo_root: repo_root,
+        id: @id,
+        session_id: @session_id,
+        receipt_path: @artifact_report_path,
+        hook_command: on_done,
+        started_at: @started_at,
+        event_sink: ->(type, payload) { emit_event(type, **payload) }
+      )
       @server = nil
       @reader = nil
       @output_log = nil
@@ -226,6 +244,7 @@ module Harnex
       @server = ApiServer.new(self)
       @server.start
       persist_registry
+      register_completion_notifier!
       append_dispatch_start_record
 
       stdin_state = STDIN.tty? ? STDIN.raw! : nil
@@ -506,6 +525,7 @@ module Harnex
       @server = ApiServer.new(self)
       @server.start
       persist_registry
+      register_completion_notifier!
       append_dispatch_start_record
 
       watch_thread = start_watch_thread
@@ -658,6 +678,10 @@ module Harnex
     end
 
     def record_successful_completion(payload)
+      @completion_transition_lock.synchronize { record_successful_completion_locked(payload) }
+    end
+
+    def record_successful_completion_locked(payload)
       assessment = completion_gate_required? ? assess_completion_proof : { accepted: true }
       unless assessment[:accepted]
         mark_task_failed(
@@ -668,7 +692,6 @@ module Harnex
           artifact_report_status: assessment[:report_status],
           diagnostics: assessment[:diagnostics]
         )
-        enforce_required_artifact_report!
         return false
       end
 
@@ -685,13 +708,17 @@ module Harnex
       # Persist proof before publishing task_complete. A coordinator that sees
       # the completion event can immediately validate the harness-authored file.
       enforce_required_artifact_report!
-      return false if task_failed?
+      if task_failed?
+        publish_completion_notification("task_failed")
+        return false
+      end
 
       event_payload = payload.dup
       event_payload[:outcome_class] = @completion_outcome_class if @completion_outcome_class
       event_payload[:artifact_report_status] = @completion_report_status if @completion_report_status
       event_payload[:artifact_report_path] = artifact_report_path
       emit_event("task_complete", **event_payload)
+      publish_completion_notification("task_complete")
       true
     end
 
@@ -757,7 +784,11 @@ module Harnex
       end
     end
 
-    def mark_task_failed(turn_id: nil, status: nil, error: nil, codex_error_info: nil, outcome_class: nil, artifact_report_status: nil, diagnostics: nil)
+    def mark_task_failed(**attributes)
+      @completion_transition_lock.synchronize { mark_task_failed_locked(**attributes) }
+    end
+
+    def mark_task_failed_locked(turn_id: nil, status: nil, error: nil, codex_error_info: nil, outcome_class: nil, artifact_report_status: nil, diagnostics: nil, publish: true)
       @last_completed_at = nil if outcome_class
       @last_failed_at = Time.now
       @last_failed_status = status.to_s.empty? ? "failed" : status.to_s
@@ -774,6 +805,11 @@ module Harnex
       payload[:artifact_report_status] = artifact_report_status if artifact_report_status
       payload[:diagnostics] = @completion_diagnostics unless @completion_diagnostics.empty?
       emit_event("task_failed", **payload)
+      if publish
+        enforce_required_artifact_report!
+        terminal_signal = @last_failed_status == "dispatch_error" ? "dispatch_error" : "task_failed"
+        publish_completion_notification(terminal_signal)
+      end
     end
 
     def extract_error_notification_message(params)
@@ -1175,6 +1211,71 @@ module Harnex
       Harnex.write_registry(@registry_path, payload)
     end
 
+    def register_completion_notifier!
+      @completion_notification_mutex.synchronize do
+        @completion_notifier.register!
+        @completion_notification_registered = true
+        deliver_completion_notification(@pending_completion_notification) if @pending_completion_notification
+      end
+    rescue StandardError => e
+      warn("harnex: completion marker cleanup failed (#{e.class})")
+      emit_event("completion_notification_error", component: "cleanup", error_class: e.class.name)
+    end
+
+    def publish_completion_notification(terminal_signal)
+      snapshot = completion_notification_snapshot(terminal_signal)
+      @completion_notification_mutex.synchronize do
+        return false if @completion_notification_sent || @pending_completion_notification
+        return !(@pending_completion_notification = snapshot).nil? unless @completion_notification_registered
+
+        deliver_completion_notification(snapshot)
+      end
+    rescue StandardError => e
+      warn("harnex: completion notification failed (#{e.class})")
+      emit_event("completion_notification_error", component: "session", error_class: e.class.name)
+      false
+    end
+
+    def deliver_completion_notification(snapshot)
+      @completion_notification_sent = true
+      @pending_completion_notification = nil
+      @completion_notifier.notify(**snapshot)
+    end
+
+    def completion_notification_snapshot(terminal_signal)
+      outcome = completion_notification_outcome(terminal_signal)
+      {
+        outcome: outcome, work_state: outcome == "completed" ? "completed" : "failed",
+        outcome_class: @completion_outcome_class, artifact_report_status: @completion_report_status,
+        end_sha: summary_string(@git_end[:sha]), terminal_signal: terminal_signal
+      }
+    end
+
+    def completion_notification_outcome(terminal_signal)
+      signal = terminal_signal.to_s
+      return "error" if %w[dispatch_error finalization].include?(signal)
+      return "rejected" if PROOF_REJECTION_CLASSES.include?(@completion_outcome_class.to_s)
+      return "rejected" if signal == "task_complete" && observed_receipt_outcome_status == "rejected"
+      return "completed" if signal == "task_complete"
+      return "failed" if signal == "task_failed"
+
+      "error"
+    end
+
+    def observed_receipt_outcome_status
+      JSON.parse(File.read(artifact_report_path)).dig("outcome", "status")
+    rescue StandardError
+      nil
+    end
+
+    def current_terminal_signal
+      return "dispatch_error" if task_failed? && @last_failed_status == "dispatch_error"
+      return "task_failed" if task_failed?
+      return "task_complete" if task_complete?
+
+      nil
+    end
+
     # Post-injection registry refresh. By the time this runs the prompt has
     # already reached the agent, so a failed bookkeeping write must not report
     # the send as failed — that would make an orchestrator retry a turn the
@@ -1442,7 +1543,11 @@ module Harnex
         @context_summary = normalized_context_summary(nil)
         warn("harnex: failed to collect session-end telemetry: #{e.message}")
       end
-      enforce_required_artifact_report!
+      @completion_transition_lock.synchronize do
+        terminal_signal = current_terminal_signal
+        enforce_required_artifact_report!
+        publish_completion_notification(terminal_signal || "finalization")
+      end
       @exit_reason ||= classify_exit
       record = DispatchHistory.build_record(self)
       append_dispatch_history_record(record)
@@ -1560,7 +1665,8 @@ module Harnex
           "code" => "receipt_write_error",
           "path" => "$",
           "message" => "harness could not write the observed-state receipt"
-        }]
+        }],
+        publish: false
       )
       @exit_code = 1 if @exit_code.nil? || @exit_code.zero? || @term_signal
       @term_signal = nil if @exit_code == 1

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.11.0"
-  RELEASE_DATE = "2026-08-14"
+  VERSION = "0.12.0"
+  RELEASE_DATE = "2026-09-03"
 end

data/lib/harnex.rb

@@ -19,6 +19,7 @@ require_relative "harnex/runtime/session_state"
 require_relative "harnex/runtime/message"
 require_relative "harnex/runtime/inbox"
 require_relative "harnex/runtime/file_change_hook"
+require_relative "harnex/runtime/completion_notifier"
 require_relative "harnex/runtime/api_server"
 require_relative "harnex/runtime/session"
 require_relative "harnex/commands/watch"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-09-03 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.
@@ -74,6 +74,7 @@ files:
 - lib/harnex/pricing.rb
 - lib/harnex/retention.rb
 - lib/harnex/runtime/api_server.rb
+- lib/harnex/runtime/completion_notifier.rb
 - lib/harnex/runtime/file_change_hook.rb
 - lib/harnex/runtime/inbox.rb
 - lib/harnex/runtime/message.rb