harnex 0.29.1 → 0.30.1

data/lib/harnex/config.rb

@@ -6,6 +6,7 @@ module Harnex
     PHASE_POLICIES = %w[warn reject].freeze
     RETENTION_DIRS = %w[events output receipts].freeze
     RETENTION_FIELDS = %w[max_age_days max_bytes].freeze
+    LANE_TEMPLATES = %w[worktree_path branch].freeze
     RETENTION_ENV = {
       "events" => {
         "max_age_days" => "HARNEX_EVENTS_MAX_AGE_DAYS",
@@ -38,6 +39,10 @@ module Harnex
       def retention
         data.is_a?(Hash) ? data["retention"] : nil
       end
+
+      def lanes
+        data.is_a?(Hash) ? data["lanes"] : nil
+      end
     end
 
     module_function
@@ -63,6 +68,22 @@ module Harnex
 
       validate_phase!(document["phase"], path) if document.key?("phase")
       validate_retention!(document["retention"], path) if document.key?("retention")
+      validate_lanes!(document["lanes"], path) if document.key?("lanes")
+    end
+
+    # #90: where worktree lanes live and what their branches are called,
+    # e.g. {"worktree_path": "../{name}", "branch": "night/{mm}{dd}_{name}"}.
+    def validate_lanes!(lanes, path)
+      raise ConfigError, "#{path}: $.lanes must be an object" unless lanes.is_a?(Hash)
+
+      lanes.each do |key, template|
+        unless LANE_TEMPLATES.include?(key)
+          raise ConfigError, "#{path}: $.lanes.#{key} is not supported (expected #{LANE_TEMPLATES.join(' or ')})"
+        end
+        next if template.is_a?(String) && template.include?("{name}")
+
+        raise ConfigError, "#{path}: $.lanes.#{key} must be a string containing {name}"
+      end
     end
 
     def validate_phase!(phase, path)

data/lib/harnex/core.rb

@@ -450,6 +450,17 @@ module Harnex
     nil
   end
 
+  # #92: who is sending a message, for the receiving lane's footer. `via`
+  # is "reply" when `harnex reply` sends on the lane's behalf
+  # (HARNEX_SEND_VIA), else "send".
+  def sender_identity(env = ENV)
+    {
+      "via" => env["HARNEX_SEND_VIA"].to_s.strip.empty? ? "send" : env["HARNEX_SEND_VIA"].strip,
+      "session" => env["HARNEX_ID"].to_s.strip,
+      "owner" => ambient_owner_id(env).to_s
+    }.reject { |_key, value| value.empty? }
+  end
+
   # How to invoke this harnex in a printed hint: the checkout's bin when
   # running from source, plain `harnex` for the installed gem.
   def cli_command

data/lib/harnex/lanes.rb

@@ -11,8 +11,9 @@ module Harnex
   # harnex/<name>. A record under STATE_DIR/lanes lets `result`, `reply`,
   # `land` and `discard` find a lane by name from anywhere in its repo.
   #
-  # Record states: running (a turn is out and nobody has collected it),
-  # done, failed, landed, discarded.
+  # Internal record states: running (a turn is out and uncollected), done,
+  # failed, landed, discarded. Machine listings project the worker's settled
+  # state independently, with `collected` indicating the record's boundary.
   module Lanes
     NAME = /\A[A-Za-z0-9][A-Za-z0-9._-]{0,47}\z/
     BRANCH_PREFIX = "harnex/".freeze
@@ -74,20 +75,45 @@ module Harnex
     end
 
     # A name resolves to this repo's lane first, then to the only lane
-    # anywhere with that name.
+    # anywhere whose worker is running (those names are unique, #89), then
+    # in flight, open, or at all.
     def resolve(name, from: Dir.pwd)
       root = main_root(from)
       lane = root && load(root, name)
       return lane if lane
 
       matches = all.select { |candidate| candidate["name"] == name }
-      return matches.first if matches.one?
       raise OptionParser::InvalidArgument, "no lane named #{name.inspect} (see `harnex lanes`)" if matches.empty?
 
+      [matches.select { |l| open?(l) && live?(l) }, matches.select { |l| in_flight?(l) },
+       matches.select { |l| open?(l) }, matches].each do |group|
+        return group.first if group.one?
+      end
       raise OptionParser::InvalidArgument,
             "several lanes are named #{name.inspect} (#{matches.map { |l| l['repo_root'] }.join(', ')}); run from the lane's repo"
     end
 
+    # Working (or finished but uncollected), or a worktree not yet landed,
+    # in a repo that still exists.
+    def in_flight?(lane)
+      open?(lane) && !never_started?(lane) && (lane["state"] == "running" || !lane["branch"].nil?) &&
+        File.directory?(lane["repo_root"].to_s)
+    end
+
+    # #89: the in-flight lane anywhere that holds `name`, if any. Generated
+    # names skip these, so `harnex result NAME` and `reply NAME` find their
+    # lane from anywhere.
+    def holder(name)
+      all.find { |lane| lane["name"] == name && in_flight?(lane) }
+    end
+
+    # The lane anywhere whose worker is running under `name`, if any. A name
+    # someone chooses is refused only while another repo's worker has it, so
+    # stale lanes elsewhere (an old eval, an abandoned clone) never block it.
+    def live_holder(name)
+      all.find { |lane| lane["name"] == name && open?(lane) && live?(lane) }
+    end
+
     # Lanes this caller started in this repo whose current turn nobody has
     # collected yet.
     def pending(from: Dir.pwd, owner: Harnex.ambient_owner_id)
@@ -98,25 +124,88 @@ module Harnex
 
     FILLER = %w[a an the this that these those to of in on at for from with and or but it its please
                 run use add make have has can could would should will do does just then also your you
-                our my me i we gpt worker workers task repo repository git command file files code].freeze
-
-    def generate_name(root, task, prefix: "pi")
-      words = task.to_s.downcase.scan(/[a-z0-9]+/).reject { |word| FILLER.include?(word) }.first(4)
-      base = ([prefix] + words).join("-")[0, 40].sub(/-+\z/, "")
+                our my me i we gpt worker workers task repo repository git command file files code
+                are is be carry out brief lane].freeze
+
+    # A lane working in another worktree of the repo is named after that
+    # worktree (`pi-night-1024_s3`); otherwise after the task's first words.
+    # Either way no repo has the name in flight (#89).
+    def generate_name(root, task, cwd: nil, prefix: "pi")
+      base = ([prefix] + name_words(root, task, cwd)).join("-")[0, 40].sub(/[-_.]+\z/, "")
       name = base
       index = 2
-      while open?(load(root, name)) || Harnex.read_registry(root, name)
+      while open?(load(root, name)) || holder(name) || Harnex.read_registry(root, name)
         name = "#{base}-#{index}"
         index += 1
       end
       name
     end
 
+    def name_words(root, task, cwd)
+      top = cwd && toplevel(cwd)
+      if top && root && !same_dir?(top, root)
+        slug = File.basename(top).downcase.gsub(/[^a-z0-9._-]+/, "-").sub(/\A[^a-z0-9]+/, "")
+        return [slug] unless slug.empty?
+      end
+      task.to_s.downcase.scan(/[a-z0-9]+/).reject { |word| FILLER.include?(word) || word.match?(/\A[a-z]\z/) }.first(4)
+    end
+
     def live?(lane)
       registry = Harnex.read_registry(lane["run_root"], lane["name"])
       !registry.nil? && Harnex.alive_pid?(registry["pid"])
     end
 
+    # #93: listing is read-only, not result collection. The record's running
+    # state still drives pending/result and the table's "finished, uncollected".
+    # Fence evidence to this launch and follow-up so a reused name cannot pick
+    # up an earlier turn. Settlement can precede process exit (Pi at prompt).
+    def snapshot(lane)
+      live = live?(lane)
+      view = lane.merge("live" => live, "collected" => lane["state"] != "running")
+      return view unless lane["state"] == "running"
+
+      %w[outcome last_error settled_at last_turn].each { |key| view.delete(key) }
+      event = events(lane).reverse.find do |row|
+        row.is_a?(Hash) && %w[task_complete task_failed work_turn agent_start].include?(row["type"]) &&
+          after?(row["ts"], lane["launched_at"]) &&
+          (!lane["after_seq"] || row["seq"].to_i > lane["after_seq"].to_i)
+      end
+      if event && %w[task_complete task_failed].include?(event["type"])
+        failed = event["type"] == "task_failed" ||
+                 (!event["status"].to_s.empty? && !%w[completed success succeeded].include?(event["status"]))
+        view.merge!("state" => failed ? "failed" : "done", "outcome" => event["outcome_class"] || event["status"],
+                    "settled_at" => event["ts"])
+        view["last_error"] = event["message"] || event["error"] if failed
+      elsif !live
+        # Process failures may exit without a task event. The canonical end
+        # row supplies their class; ignore old rows from a previous launch.
+        terminal = TerminalStatus.resolve(id: lane["name"], repo_root: lane["run_root"])
+        if terminal && terminal["terminal"] && after?(terminal["ended_at"], lane["launched_at"])
+          view.merge!("state" => terminal["work_state"] == "completed" ? "done" : "failed",
+                      "outcome" => terminal["outcome_class"], "settled_at" => terminal["ended_at"])
+        elsif (exit_status = fresh_exit_status(lane))
+          done = exit_status["task_complete"] == true ||
+                 (exit_status["task_failed"] != true && exit_status["exit_code"] == 0)
+          view.merge!("state" => done ? "done" : "failed", "outcome" => exit_status["outcome_class"],
+                      "settled_at" => exit_status["exited_at"])
+        end
+      end
+      view
+    end
+
+    def fresh_exit_status(lane)
+      path = Harnex.exit_status_path(lane["run_root"], lane["name"])
+      data = JSON.parse(File.read(path))
+      return nil unless data.is_a?(Hash)
+
+      # Exit timestamps have second precision; mtime also fences same-second
+      # relaunches so an earlier dispatch's leftover file cannot settle one.
+      since = Time.iso8601(lane["launched_at"].to_s)
+      data if File.mtime(path) >= since && after?(data["exited_at"], since.iso8601)
+    rescue Errno::ENOENT, JSON::ParserError, ArgumentError
+      nil
+    end
+
     # The live worker's activity snapshot (see ActivityTracker), or nil.
     def activity(lane)
       registry = Harnex.read_registry(lane["run_root"], lane["name"])
@@ -155,17 +244,43 @@ module Harnex
     end
 
     # The main checkout of the repo that contains `path` (also from inside one
-    # of its worktrees), or nil outside git.
+    # of its worktrees), or nil outside git. In a bare layout (`repo/.bare`
+    # plus sibling worktrees, #89) it is the worktree on the bare repo's HEAD
+    # branch, so every worktree of the repo shares one lane namespace.
     def main_root(path)
       common, _err, ok = git(path, "rev-parse", "--path-format=absolute", "--git-common-dir")
       return nil unless ok
 
       return File.dirname(common) if File.basename(common) == ".git"
 
+      bare_main_worktree(path, common) || toplevel(path)
+    end
+
+    def same_dir?(one, two)
+      File.realpath(one.to_s) == File.realpath(two.to_s)
+    rescue SystemCallError
+      File.expand_path(one.to_s) == File.expand_path(two.to_s)
+    end
+
+    def toplevel(path)
       top, _err, ok = git(path, "rev-parse", "--show-toplevel")
       ok ? top : nil
     end
 
+    def bare_main_worktree(path, common)
+      list, _err, ok = git(path, "worktree", "list", "--porcelain")
+      return nil unless ok
+
+      entries = list.split(/\n{2,}/).map do |block|
+        block.lines.to_h { |line| line.chomp.split(" ", 2).then { |key, value| [key, value.to_s] } }
+      end
+      return nil unless entries.first&.key?("bare")
+
+      head, _err, ok = git(common, "symbolic-ref", "-q", "HEAD")
+      main = ok && entries.find { |entry| entry["branch"] == head && File.directory?(entry["worktree"].to_s) }
+      main ? main["worktree"] : nil
+    end
+
     def head_sha(dir)
       sha, _err, ok = git(dir, "rev-parse", "HEAD")
       ok ? sha : nil
@@ -176,10 +291,28 @@ module Harnex
       ok ? out.lines.map { |line| line[3..].to_s.strip } : []
     end
 
+    # #90: a worktree lane lives at .harnex/worktrees/NAME on harnex/NAME,
+    # unless the repo's .harnex/config.json `lanes` templates say otherwise
+    # ({name}, {yyyy}, {mm}, {dd}; worktree_path is relative to the main
+    # checkout, so "../{name}" puts lanes beside it).
+    def worktree_layout(root, name, now: Time.now)
+      templates = Config.load_repo(root).lanes || {}
+      fill = lambda do |template|
+        template.gsub("{name}", name).gsub("{yyyy}", now.strftime("%Y")).gsub("{mm}", now.strftime("%m"))
+                .gsub("{dd}", now.strftime("%d"))
+      end
+      path = fill.call(templates["worktree_path"] || File.join(WORKTREES_DIR, "{name}"))
+      [File.expand_path(path, root), fill.call(templates["branch"] || "#{BRANCH_PREFIX}{name}")]
+    rescue Config::ConfigError => e
+      raise OptionParser::InvalidArgument, "invalid config #{e.message}"
+    end
+
     def create_worktree(root, name)
       Harnex.ensure_git_excluded(root)
-      worktree = File.join(root, WORKTREES_DIR, name)
-      branch = BRANCH_PREFIX + name
+      worktree, branch = worktree_layout(root, name)
+      _out, _err, valid = git(root, "check-ref-format", "--branch", branch)
+      raise OptionParser::InvalidArgument, "lanes.branch gives #{branch.inspect}, which is not a valid branch name" unless valid
+
       _out, _err, exists = git(root, "rev-parse", "--verify", "--quiet", "refs/heads/#{branch}")
       if exists || File.exist?(worktree)
         raise OptionParser::InvalidArgument,
@@ -259,8 +392,12 @@ module Harnex
       merged
     end
 
+    # Inside the checkout: "a/b"; beside it: "../x"; anywhere else: absolute.
     def relative(root, path)
-      path.to_s.start_with?("#{root}/") ? path.to_s.delete_prefix("#{root}/") : path.to_s
+      return path.to_s.delete_prefix("#{root}/") if path.to_s.start_with?("#{root}/")
+
+      sibling = "../#{File.basename(path.to_s)}"
+      File.expand_path(sibling, root.to_s) == File.expand_path(path.to_s) ? sibling : path.to_s
     end
 
     # ---- briefs ------------------------------------------------------------
@@ -419,7 +556,7 @@ module Harnex
       lane["settled_at"] = now
       # Kept so a later `harnex result NAME` can show the result again.
       lane["last_turn"] = turn.slice("final_message", "final_message_path", "final_message_truncated", "model",
-                                     "outcome_class", "status", "last_error", "end_sha")
+                                     "outcome_class", "status", "last_error", "end_sha", "earlier_replies")
       save(lane)
     end
 
@@ -436,13 +573,79 @@ module Harnex
 
     def render(lane, turn, exit_code)
       lines = []
-      message = final_message(turn)
+      message = with_earlier_replies(final_message(turn), turn)
       lines << message.rstrip << "" unless message.strip.empty? || exit_code == Waiter::DONE_EXIT_TIMEOUT
       lines << "── #{lane['name']}: #{headline(lane, turn, exit_code)}"
-      lines.concat(details(lane, exit_code).map { |line| "   #{line}" })
+      lines.concat((interjection_lines(lane) + details(lane, exit_code)).map { |line| "   #{line}" })
       lines.join("\n")
     end
 
+    # An answered ask prints only its answer, plus what else reached the
+    # worker (#92).
+    def render_answer(lane, turn)
+      text = with_earlier_replies(final_message(turn), turn)
+      notes = interjection_lines(lane)
+      return text if notes.empty?
+
+      [text.rstrip, "", "── #{lane['name']}: #{notes.first}", *notes.drop(1).map { |line| "   #{line}" }].join("\n")
+    end
+
+    # #92: when a later message reached the worker after it had answered,
+    # the turn's result is its answer to that message; the answers it
+    # replaced (the original task's report among them) come first.
+    def with_earlier_replies(message, turn)
+      earlier = Array(turn["earlier_replies"]).map(&:to_s).reject { |text| text.strip.empty? }
+      return message if earlier.empty? || message.strip.empty?
+
+      parts = earlier.map { |text| "[earlier reply this turn, before another message reached the worker]\n#{text.rstrip}" }
+      (parts + ["[latest reply]\n#{message.rstrip}"]).join("\n\n")
+    end
+
+    # #92: messages that reached the worker from anyone but the lane's own
+    # owner and its `harnex reply` (someone's `harnex send` from another
+    # terminal or session), since the lane's latest launch.
+    def interjections(lane)
+      events(lane).select do |event|
+        event["type"] == "send" && event["from"].is_a?(Hash) && after?(event["ts"], lane["launched_at"]) &&
+          !own_message?(lane, event["from"])
+      end
+    end
+
+    def own_message?(lane, from)
+      owner = lane["owner"].to_s
+      from["owner"].to_s == owner && (!owner.empty? || from["via"] == "reply")
+    end
+
+    def interjection_lines(lane)
+      found = interjections(lane)
+      return [] if found.empty?
+
+      count = found.length == 1 ? "1 message" : "#{found.length} messages"
+      ["interjected: #{count} reached the worker from outside this lane " \
+       "(the reply above may answer #{found.length == 1 ? 'it' : 'them'}; all: `harnex events --id #{lane['name']}`):"] +
+        found.last(5).map { |event| "  #{clock(event['ts'])} #{sender_label(event['from'])}: #{preview(event)}" }
+    end
+
+    def sender_label(from)
+      who = if from["session"] then "harnex session #{from['session']}"
+            elsif from["owner"] then "session #{from['owner'][0, 8]}"
+            else "a terminal"
+            end
+      "from #{who} (harnex #{from['via'] || 'send'})"
+    end
+
+    def preview(event)
+      text = event["msg"].to_s.sub(/\A\[harnex [^\]]*\]\s*/, "").gsub(/\s+/, " ").strip
+      cut = text.length > 160 || event["msg_truncated"]
+      "\"#{text[0, 160]}#{cut ? '…' : ''}\""
+    end
+
+    def clock(ts)
+      Time.iso8601(ts.to_s).localtime.strftime("%H:%M:%S")
+    rescue ArgumentError
+      ts.to_s
+    end
+
     def headline(lane, turn, exit_code)
       model = turn["model"] || lane["model"] || lane["requested_model"]
       parts = []
@@ -465,6 +668,9 @@ module Harnex
       dir = lane["worktree"] || lane["cwd"]
       return nil unless lane["base_sha"] && File.directory?(dir.to_s)
 
+      shas = lane["branch"] ? nil : worker_commits(lane)
+      return worker_change_summary(lane, dir, shas) if shas
+
       count, _err, ok = git(dir, "rev-list", "--count", "#{lane['base_sha']}..HEAD")
       return nil unless ok
 
@@ -473,6 +679,47 @@ module Harnex
       stat.empty? ? commits : "#{commits}, #{compact_stat(stat)}"
     end
 
+    # #91: a lane working in place shares HEAD with whoever else commits
+    # there, so count only the commits the worker made (worker_commits
+    # events). nil when the worker's harnex did not track them.
+    def worker_commits(lane)
+      found = events(lane).select { |event| after?(event["ts"], lane["created_at"]) }
+      return nil unless found.any? { |event| event["type"] == "git" && event["tracks_worker_commits"] }
+
+      found.select { |event| event["type"] == "worker_commits" }.flat_map { |event| Array(event["shas"]) }
+    end
+
+    def worker_change_summary(lane, dir, shas)
+      moved, _err, ok = git(dir, "rev-list", "#{lane['base_sha']}..HEAD")
+      return nil unless ok
+
+      history = moved.split
+      mine = history & shas
+      text = "#{mine.length} commit#{mine.length == 1 ? '' : 's'}"
+      stat = mine.empty? ? nil : commits_stat(dir, mine)
+      text += ", #{stat}" if stat
+      others = history.length - mine.length
+      text += " (HEAD also moved #{others} commit#{others == 1 ? '' : 's'} by others)" if others.positive?
+      text
+    end
+
+    def commits_stat(dir, shas)
+      out, _err, ok = git(dir, "show", "--numstat", "--format=", *shas)
+      return nil unless ok
+
+      files = {}
+      added = removed = 0
+      out.each_line do |line|
+        plus, minus, path = line.chomp.split("\t", 3)
+        next unless path
+
+        files[path] = true
+        added += plus.to_i
+        removed += minus.to_i
+      end
+      "#{files.size} file#{files.size == 1 ? '' : 's'} (+#{added} -#{removed})"
+    end
+
     def compact_stat(stat)
       files = stat[/(\d+) files? changed/, 1]
       added = stat[/(\d+) insertions?/, 1]
@@ -483,6 +730,8 @@ module Harnex
     def details(lane, exit_code)
       name = lane["name"]
       return ["keep waiting: harnex result #{name}"] if exit_code == Waiter::DONE_EXIT_TIMEOUT
+      provider_hint = provider_failure_hint(lane)
+      return ["next: #{provider_hint}"] if lane["kind"] == "ask" && !exit_code.zero? && provider_hint
       return ["more: harnex reply #{name} \"...\""] if lane["kind"] == "ask"
 
       out = []
@@ -502,6 +751,8 @@ module Harnex
         else
           out << "worked in place in #{lane['cwd']}; more work: `harnex reply #{name} \"...\"`"
         end
+      elsif provider_hint
+        out << "next: #{provider_hint}#{lane['branch'] ? "; or `harnex discard #{name}`" : ''}"
       else
         retry_model = model_problem?(lane) ? other_model(lane) : nil
         out << "next: `harnex reply #{name} \"Continue the same task from where you stopped\"" \
@@ -512,6 +763,15 @@ module Harnex
       out
     end
 
+    def provider_failure_hint(lane)
+      case lane["outcome"]
+      when "policy_refusal"
+        "provider refused the content; a retry needs a rephrased brief or another route"
+      when "provider_error_unexplained"
+        "read the provider/gateway logs before retrying; the provider returned no error details"
+      end
+    end
+
     def commit_count(lane)
       count, _err, ok = git(lane["worktree"] || lane["cwd"], "rev-list", "--count", "#{lane['base_sha']}..HEAD")
       ok ? count.to_i : 0

data/lib/harnex/mcp.rb

@@ -41,6 +41,7 @@ module Harnex
           "model" => MODEL, "effort" => EFFORT,
           "fallback_model" => { "type" => "string", "description" => "Ask this model instead if the first is rate limited" },
           "write" => { "type" => "boolean", "description" => "Let the worker edit files and run commands (default false)" },
+          "name" => { "type" => "string", "description" => "Lane name (default: pi-ask-<random>)" },
           "cwd" => CWD, "wait_minutes" => WAIT_MINUTES
         } },
         "annotations" => { "readOnlyHint" => false, "openWorldHint" => true }
@@ -56,7 +57,7 @@ module Harnex
         "inputSchema" => { "type" => "object", "required" => ["task"], "properties" => {
           "task" => { "type" => "string", "description" => "Self-contained brief: files, expected behavior, how to verify (e.g. the test command)" },
           "worktree" => { "type" => "string", "description" => "Lane name; work in a new git worktree on branch harnex/NAME (recommended for edits)" },
-          "name" => { "type" => "string", "description" => "Lane name when not using a worktree (default: from the task)" },
+          "name" => { "type" => "string", "description" => "Lane name when not using a worktree (default: the cwd worktree's name, else from the task)" },
           "wait" => { "type" => "boolean", "description" => "Wait for the result (default true); false starts the lane and returns at once" },
           "model" => MODEL, "effort" => EFFORT, "cwd" => CWD, "wait_minutes" => WAIT_MINUTES
         } },
@@ -250,10 +251,11 @@ module Harnex
         case tool
         when "delegate"
           if args["worktree"].to_s.empty? && args["name"].to_s.empty?
-            root = Lanes.main_root(work_dir(args)) || work_dir(args)
-            args["name"] = Lanes.generate_name(root, args["task"] || args["prompt"] || args["brief"])
+            dir = work_dir(args)
+            args["name"] = Lanes.generate_name(Lanes.main_root(dir) || dir, args["task"] || args["prompt"] || args["brief"], cwd: dir)
           end
         when "ask"
+          args["id"] = args["name"] unless args["name"].to_s.strip.empty?
           args["id"] ||= "pi-ask-#{SecureRandom.hex(2)}"
         end
         args

data/lib/harnex/orchestration.rb

@@ -23,7 +23,8 @@ module Harnex
     # are not fatal unless a caller names them (#57). provider_capacity was
     # task_failed before #82 and stays fatal; pass fatal classes to exempt it.
     DEFAULT_FATAL_CLASSES = %w[
-      completed_no_activity task_failed provider_capacity boot_failure permission_prompt timeout process_failed
+      completed_no_activity task_failed provider_capacity policy_refusal provider_error_unexplained
+      boot_failure permission_prompt timeout process_failed
     ].freeze
 
     module_function

data/lib/harnex/runtime/api_server.rb

@@ -78,7 +78,8 @@ module Harnex
             text: payload[:text],
             submit: payload[:submit],
             enter_only: payload[:enter_only],
-            force: payload[:force]
+            force: payload[:force],
+            from: payload[:from]
           )
           http_code = result.delete(:http_status) || 200
           json(client, http_code, result)
@@ -136,6 +137,15 @@ module Harnex
       context
     end
 
+    # Who sent a message (#92), as `harnex send` reports it: bounded strings.
+    def sender(value)
+      return nil unless value.is_a?(Hash)
+
+      value.slice("via", "session", "owner").filter_map do |key, text|
+        [key, text.to_s[0, 120]] unless text.to_s.strip.empty?
+      end.to_h
+    end
+
     def parse_send_body(headers, body)
       if headers["content-type"].to_s.include?("application/json")
         parsed = JSON.parse(body.empty? ? "{}" : body)
@@ -145,7 +155,8 @@ module Harnex
             text: parsed["text"].to_s,
             submit: parsed.fetch("submit", true),
             enter_only: parsed.fetch("enter_only", false),
-            force: parsed.fetch("force", false)
+            force: parsed.fetch("force", false),
+            from: sender(parsed["from"])
           }
         else
           {

data/lib/harnex/runtime/inbox.rb

@@ -32,13 +32,14 @@ module Harnex
       @thread&.kill
     end
 
-    def enqueue(text:, submit:, enter_only:, force: false)
+    def enqueue(text:, submit:, enter_only:, force: false, from: nil)
       msg = Message.new(
         id: SecureRandom.hex(8),
         text: text,
         submit: submit,
         enter_only: enter_only,
         force: force,
+        from: from,
         queued_at: Time.now,
         status: :queued
       )
@@ -139,6 +140,7 @@ module Harnex
     def deliver_now(msg, follow_up: false)
       options = { text: msg.text, submit: msg.submit, enter_only: msg.enter_only, force: msg.force }
       options[:follow_up] = true if follow_up
+      options[:from] = msg.from if msg.from
       result = @session.inject_via_adapter(**options)
       msg.status = :delivered
       msg.delivered_at = Time.now

data/lib/harnex/runtime/message.rb

@@ -1,6 +1,6 @@
 module Harnex
   Message = Struct.new(:id, :text, :submit, :enter_only, :force, :queued_at, :status, :delivered_at, :error,
-                       :after_seq, :delivery, keyword_init: true) do
+                       :after_seq, :delivery, :from, keyword_init: true) do
     def to_h
       {
         id: id,