samagotchi 0.2.0 → 0.4.0

data/lib/samagotchi/text_diff.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Line-based unified diff (like `diff -u` without the file header), used to
+  # show what chi's edit/write tools change. Pure: strings in, a hash out.
+  #
+  #   TextDiff.unified("a\nb\n", "a\nc\n")
+  #   # => {text: "@@ -1,2 +1,2 @@\n a\n-b\n+c", added: 1, removed: 1, truncated: false}
+  #
+  # The common prefix and suffix are trimmed first (edits are local), then
+  # Myers O(ND) runs on the middle. When the edit distance passes
+  # MAX_EDIT_DISTANCE it gives up on a minimal diff and shows the whole middle
+  # as removed then added: correct, just not minimal. The text is cut at
+  # MAX_LINES / MAX_BYTES with a "… N more lines" line; the counts stay exact.
+  module TextDiff
+    CONTEXT = 3
+    MAX_LINES = 120
+    MAX_BYTES = 8 * 1024
+    MAX_EDIT_DISTANCE = 1000 # D² work: ~0.35 s for a dense 5 000-line edit
+    NO_NEWLINE = "\"
+
+    module_function
+
+    def unified(before, after, context: CONTEXT, max_lines: MAX_LINES, max_bytes: MAX_BYTES)
+      a = clean(before).lines
+      b = clean(after).lines
+      ops = edit_script(a, b)
+      added = ops.count { |op| op[0] == :add }
+      removed = ops.count { |op| op[0] == :del }
+      text, truncated = render(hunks(ops, context), a, b, max_lines, max_bytes)
+      { text: text, added: added, removed: removed, truncated: truncated }
+    end
+
+    def clean(text)
+      text.to_s.dup.force_encoding(Encoding::UTF_8).scrub("�")
+    end
+
+    # Ops are [:eq, ai, bi], [:del, ai, nil] or [:add, nil, bi] in file order.
+    def edit_script(a, b)
+      pre = 0
+      pre += 1 while pre < a.size && pre < b.size && a[pre] == b[pre]
+      suf = 0
+      suf += 1 while suf < a.size - pre && suf < b.size - pre && a[-1 - suf] == b[-1 - suf]
+
+      ops = (0...pre).map { |i| [:eq, i, i] }
+      a_mid = a[pre...(a.size - suf)]
+      b_mid = b[pre...(b.size - suf)]
+      middle = myers(a_mid, b_mid) ||
+               a_mid.each_index.map { |i| [:del, i, nil] } + b_mid.each_index.map { |j| [:add, nil, j] }
+      middle.each { |t, i, j| ops << [t, i && i + pre, j && j + pre] }
+      (0...suf).each { |s| ops << [:eq, a.size - suf + s, b.size - suf + s] }
+      ops
+    end
+
+    # Myers' greedy forward search, keeping one slice of V per round for the
+    # backtrack. Returns nil when the edit distance passes max_d.
+    def myers(a, b, max_d = MAX_EDIT_DISTANCE)
+      ids = {}
+      a = a.map { |l| ids[l] ||= ids.size }
+      b = b.map { |l| ids[l] ||= ids.size }
+      # No line in common (a full rewrite): the fallback is the minimal diff.
+      return nil if ids.size == a.uniq.size + b.uniq.size
+
+      n = a.size
+      m = b.size
+      off = n + m + 1
+      v = Array.new(2 * off + 1, 0)
+      trace = []
+      (0..(n + m)).each do |d|
+        return nil if d > max_d
+
+        # Round d reads k-1 and k+1 for k in -d..d: keep -(d+1)..d+1.
+        trace << v[off - d - 1, 2 * d + 3]
+        k = -d
+        while k <= d
+          x = if k == -d || (k != d && v[off + k - 1] < v[off + k + 1])
+                v[off + k + 1]
+              else
+                v[off + k - 1] + 1
+              end
+          y = x - k
+          while x < n && y < m && a[x] == b[y]
+            x += 1
+            y += 1
+          end
+          v[off + k] = x
+          return backtrack(trace, n, m) if x >= n && y >= m
+
+          k += 2
+        end
+      end
+      []
+    end
+
+    def backtrack(trace, x, y)
+      ops = []
+      (trace.size - 1).downto(0) do |d|
+        vd = trace[d]
+        at = ->(k) { vd[k + d + 1] }
+        k = x - y
+        prev_k = k == -d || (k != d && at.(k - 1) < at.(k + 1)) ? k + 1 : k - 1
+        prev_x = at.(prev_k)
+        prev_y = prev_x - prev_k
+        while x > prev_x && y > prev_y
+          x -= 1
+          y -= 1
+          ops << [:eq, x, y]
+        end
+        break if d.zero?
+
+        if x == prev_x
+          ops << [:add, nil, prev_y]
+        else
+          ops << [:del, prev_x, nil]
+        end
+        x = prev_x
+        y = prev_y
+      end
+      ops.reverse
+    end
+
+    # Groups ops into hunks: runs of changes whose gaps are at most 2*context
+    # unchanged lines, each padded with up to context lines on both sides.
+    def hunks(ops, context)
+      changed = ops.each_index.reject { |i| ops[i][0] == :eq }
+      return [] if changed.empty?
+
+      groups = [[changed.first, changed.first]]
+      changed.drop(1).each do |i|
+        if i - groups.last[1] - 1 <= 2 * context
+          groups.last[1] = i
+        else
+          groups << [i, i]
+        end
+      end
+      groups.map { |first, last| ops[[first - context, 0].max..[last + context, ops.size - 1].min] }
+    end
+
+    def render(hunks, a, b, max_lines, max_bytes)
+      lines = []
+      hunks.each do |hunk|
+        lines << header(hunk)
+        hunk.each do |t, i, j|
+          line = t == :add ? b[j] : a[i]
+          mark = { eq: " ", del: "-", add: "+" }[t]
+          # Only the "\n": chomp("\n") would take a CRLF's "\r" too.
+          lines << mark + (line.end_with?("\n") ? line[0...-1] : line)
+          lines << NO_NEWLINE unless line.end_with?("\n")
+        end
+      end
+      cut(lines, max_lines, max_bytes)
+    end
+
+    # @@ -start,len +start,len @@ with diff -u's conventions: ",1" is left
+    # out. A side with no lines in the hunk is an empty file (any other hunk
+    # has context lines), shown as 0,0.
+    def header(hunk)
+      a_lines = hunk.filter_map { |t, i, _| i unless t == :add }
+      b_lines = hunk.filter_map { |t, _, j| j unless t == :del }
+      "@@ -#{range(a_lines)} +#{range(b_lines)} @@"
+    end
+
+    def range(indexes)
+      return "0,0" if indexes.empty?
+
+      indexes.size == 1 ? (indexes.first + 1).to_s : "#{indexes.first + 1},#{indexes.size}"
+    end
+
+    def cut(lines, max_lines, max_bytes)
+      bytes = 0
+      lines.each_with_index do |line, i|
+        bytes += line.bytesize + 1
+        next unless i >= max_lines || bytes > max_bytes
+
+        rest = lines.size - i
+        return [(lines[0, i] + ["… #{rest} more lines"]).join("\n"), true]
+      end
+      [lines.join("\n"), false]
+    end
+  end
+end

data/lib/samagotchi/thinking.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Samagotchi
+  # How much a model thinks: one level per model, host or run, mapped to each
+  # backend's own switch. The one place that knows the mapping.
+  #
+  #   off      thinking off where the backend can do it
+  #   low, medium, high   the effort a chat host is asked for
+  #   default  chi sends nothing: the provider's or template's own default
+  #
+  # Order (#resolve): --thinking / SAMAGOTCHI_THINKING_LEVEL, then
+  # models.<key>.thinking, hosts.<name>.thinking, thinking.level in
+  # config.yml, then default.
+  module Thinking
+    LEVELS = %i[off low medium high default].freeze
+    EFFORTS = %i[low medium high].freeze
+    DEFAULT = :default
+
+    # Gemma 4 turns thinking on with this token at the start of the system prompt.
+    GEMMA_THINK_TOKEN = "<|think|>\n"
+    # An empty thought after the Qwen assistant cue: the model answers at once
+    # (what the server's own template does with enable_thinking false).
+    QWEN_EMPTY_THOUGHT = "<think>\n\n</think>\n\n"
+
+    # What a native prompt gets for a level: the text before the system
+    # prompt, the text after the assistant cue, and whether the level means
+    # anything there (low/medium/high have no native knob).
+    Native = Data.define(:system_token, :prefill, :honoured)
+
+    module_function
+
+    # A configured value as a level; nil when unset or not a level (that
+    # warns once, naming +where+). YAML reads an unquoted `off` as false,
+    # which is :off; true (`on`) isn't a level.
+    # @return [Symbol, nil]
+    def level(value, where)
+      return nil if value.nil?
+      return :off if value == false || value.to_s.strip.downcase == "false"
+
+      text = value.to_s.strip.downcase
+      return text.to_sym if LEVELS.include?(text.to_sym)
+
+      hint = value == true || %w[true on].include?(text) ? "; `on` isn't one, `default` leaves it to the model" : ""
+      ConfigFile.warn_once "Warning: #{where}: thinking must be one of #{LEVELS.join(', ')}#{hint}; ignored"
+      nil
+    end
+
+    # The level for +target+ and where it came from ("--thinking",
+    # "models: qwen", "hosts.work", "thinking.level"; nil for the default).
+    # @param target [HostRegistry::ModelTarget]
+    # @param names [Array<String>, nil] the model's lookup names (Engine#model_lookup_names)
+    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @return [Array(Symbol, String|nil)]
+    def resolve(target, names: nil, models: nil)
+      global, origin = global_level
+      return [global, origin == :cli ? "--thinking" : "SAMAGOTCHI_THINKING_LEVEL"] if global && %i[cli env].include?(origin)
+
+      models ||= begin
+        ConfigFile.model_settings
+      rescue StandardError
+        {}
+      end
+      names ||= [target.model, target.bare_model]
+      key, value = ConfigFile.model_setting(names, :thinking, models: models)
+      return [value, "models: #{key}"] if key
+
+      host = target.entry.respond_to?(:thinking) ? target.entry.thinking : nil
+      return [host, "hosts.#{target.entry.name}"] if host
+      return [global, "thinking.level"] if global
+
+      [DEFAULT, nil]
+    end
+
+    # thinking.level as a level and its origin (:cli, :env, :file), or nil.
+    def global_level
+      raw, origin = Config.get_with_origin("thinking.level")
+      return nil if origin == :default
+
+      where = { cli: "--thinking", env: "SAMAGOTCHI_THINKING_LEVEL" }.fetch(origin, "thinking.level")
+      value = level(raw, where)
+      value ? [value, origin] : nil
+    rescue StandardError
+      nil
+    end
+
+    # Request fields for an OpenAI-style chat host. off sends both switches
+    # (the template's enable_thinking and the OpenAI-style reasoning_effort
+    # "none"): llama.cpp, Splash and OpenRouter each honour one of them.
+    # An effort goes as reasoning_effort (llama.cpp ignores it). default
+    # sends nothing.
+    # @return [Hash] frozen
+    def chat_fields(level)
+      case level
+      when :off then { chat_template_kwargs: { enable_thinking: false }.freeze, reasoning_effort: "none" }.freeze
+      when *EFFORTS then { reasoning_effort: level.to_s }.freeze
+      else {}.freeze
+      end
+    end
+
+    # The native prompt's switch for +level+ under +profile+.
+    # @param profile [ModelProfile]
+    # @return [Native]
+    def native(level, profile)
+      off = level == :off
+      honoured = !EFFORTS.include?(level)
+      case profile&.name
+      when "gemma4" then Native.new(system_token: off ? "" : GEMMA_THINK_TOKEN, prefill: "", honoured: honoured)
+      when "qwen36" then Native.new(system_token: "", prefill: off ? QWEN_EMPTY_THOUGHT : "", honoured: honoured)
+      else Native.new(system_token: "", prefill: "", honoured: level == DEFAULT)
+      end
+    end
+  end
+end

data/lib/samagotchi/tool_activity.rb

@@ -65,11 +65,13 @@ module Samagotchi
 
     # "error" for an "Error:" result, and for an execute whose command
     # exited non-zero (its last "exit: N" line; no number: killed by a
-    # signal), so the turn tally's "(N failed)" counts it.
+    # signal), so the turn tally's "(N failed)" counts it. "stopped" for a
+    # task_wait the user's Stop ended: the task itself runs on.
     def tool_activity_status(result, tool_name = nil)
       text = result.to_s
       return "error" if text.start_with?("Error:")
       return "error" if tool_name == Tools::Execute::NAME && execute_failed?(text)
+      return "stopped" if tool_name == Tools::TaskWait::NAME && text.match?(/^wait_result: canceled$/)
 
       "ok"
     end

data/lib/samagotchi/tool_runner.rb

@@ -4,6 +4,8 @@ require_relative "tool_activity"
 require_relative "guardrails"
 require_relative "vision_context"
 require_relative "log"
+require_relative "edit_preview"
+require_relative "tools/tool_path"
 
 module Samagotchi
   # The single per-call path both loops use: the tool_call_started and
@@ -17,6 +19,10 @@ module Samagotchi
     # that returns many screenshots can't flood the context).
     MAX_IMAGES_PER_RESULT = 4
 
+    # file_before for a call that isn't an edit/write, or won't run.
+    NOT_AN_EDIT = Object.new.freeze
+    private_constant :NOT_AN_EDIT
+
     # @param kernel [KernelLoop] read lazily: Engine sets its hooks after
     #   the kernel is built.
     def initialize(kernel)
@@ -29,7 +35,9 @@ module Samagotchi
     #   shown_params: the params line the live row showed, and shown_label:
     #   its label ("chrome: screenshot"), only for a tool that isn't built in
     #   (the loops save them with the result, so a reload without the plugin
-    #   shows the same row)
+    #   shows the same row), and diff: what an edit/write changed in its
+    #   file (EditPreview.change; also on tool_call_completed, never in the
+    #   model's output)
     def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       # The gate runs first, so tool_call_started shows the call that runs.
@@ -45,7 +53,9 @@ module Samagotchi
       # The ask comes after tool_call_started: the UI shows the tool line,
       # then the approval under it.
       settle_ask(verdict) if verdict.ask?
+      before = verdict.deny? ? NOT_AN_EDIT : file_before(call)
       result = verdict.deny? ? denied(call, verdict) : dispatch(call)
+      diff = file_change(call, before)
       result = approved(result, verdict) if verdict.allow? && verdict.decided_by
       result, images = attach_images(call, result) if result[:images]
 
@@ -61,17 +71,40 @@ module Samagotchi
       completed = { type: :tool_call_completed, iteration: iteration, call_count: call_count, call_index: call_index,
                     tool: call[:name], output: capped, output_truncated: truncated, activity: result[:activity] }
       completed[:images] = images if images&.any?
+      completed[:diff] = diff if diff
       emit(on_stream_event, completed)
 
       run = { output: output, capped_output: capped, truncated: truncated, activity: result[:activity] }
       run[:images] = images if images&.any?
       run[:shown_params] = params if params && plugin_tool?(call[:name])
       run[:shown_label] = label if label
+      run[:diff] = diff if diff
       run
     end
 
     private
 
+    # edit/write only: the file just before the call runs. The row diffs it
+    # with the file after, whatever the result says, so an edit that fails
+    # after writing still shows its change and one that wrote nothing shows
+    # none.
+    def file_before(call)
+      return NOT_AN_EDIT unless EditPreview.tool?(call[:name])
+
+      EditPreview.snapshot(Tools::ToolPath.normalize(call[:path]))
+    rescue StandardError
+      NOT_AN_EDIT
+    end
+
+    def file_change(call, before)
+      return nil if before.equal?(NOT_AN_EDIT)
+
+      EditPreview.change(before, EditPreview.snapshot(Tools::ToolPath.normalize(call[:path])))
+    rescue StandardError => e
+      Log.warn(:turn, "edit_diff_failed", tool: call[:name], error: "#{e.class}: #{e.message}")
+      nil
+    end
+
     # A tool's output can hold bytes that aren't UTF-8 (`printf '\xff'`, a
     # binary file). They become "?" here, before the output reaches the
     # conversation, the events and the saved session: JSON.generate raises

data/lib/samagotchi/tools/ask_user_question.rb

@@ -19,30 +19,50 @@ module Samagotchi
 
       def self.name        = NAME
 
-      # Direct invocation (used in specs / headless fallback).
-      # When a blocking handler is not injected, return an instructional error so the
-      # model falls back to plain text rather than hanging.
-      def self.call(question, options: nil, header: nil, multi_select: nil, allow_freeform: nil)
-        question = question.to_s.strip
-        return "Error: question is required" if question.empty?
-
-        opts = normalize_options(options)
-        return "Error: options must be an array of 2-8 non-empty strings" if opts.nil?
-
-        header = header.to_s.strip
-        header = nil if header.empty?
-        ms = to_bool(multi_select)
-        af = to_bool(allow_freeform)
-
-        payload = {
+      QUESTION_REQUIRED_ERROR = "Error: ask_user_question requires 'question'"
+
+      # The tool result for a wrong number of options.
+      def self.options_count_error(count)
+        "Error: ask_user_question requires 2-8 options (got #{count}). Provide e.g. options=[\"Cats\",\"Dogs\"]"
+      end
+
+      # The one check of a model's ask_user_question call (the kernel runs it
+      # before the question opens). Dumb-model tolerant: options may be a JSON
+      # string or bracket noise, a single option is salvaged, missing options
+      # are read from the call's content, booleans may be strings; wire control
+      # tokens are stripped from the question and header.
+      # @param call [Hash] the tool call (question:/content:, options:, header:,
+      #   multi_select:, allow_freeform:)
+      # @return [Hash, String] the payload {question:, options:, header:,
+      #   multi_select:, allow_freeform:} (no header key when empty), or the
+      #   plain-text error the model gets as the tool result
+      def self.validate(call)
+        question = strip_wire_tokens(call[:question] || call[:content])
+        return QUESTION_REQUIRED_ERROR if question.empty?
+
+        options = normalize_options_lenient(call[:options])
+        options = normalize_options_lenient(call[:content].to_s) if options.empty? && call[:content]
+        return options_count_error(options.size) if options.empty? || options.size > 8
+
+        header = strip_wire_tokens(call[:header])
+        {
           question: question,
-          options: opts,
-          header: header,
-          multi_select: ms,
-          allow_freeform: af
+          options: options,
+          header: (header unless header.empty?),
+          multi_select: to_bool(call[:multi_select]),
+          allow_freeform: to_bool(call[:allow_freeform])
         }.compact
+      end
+
+      # Booleans the way models send them (Gemma passes "true"/"false").
+      def self.to_bool(value)
+        return value if value == true || value == false
 
-        JSON.pretty_generate(payload)
+        %w[1 true yes on].include?(value.to_s.strip.downcase)
+      end
+
+      def self.strip_wire_tokens(text)
+        text.to_s.gsub(/<\|[^|]*\|>/, "").gsub(/<\||\|>/, "").strip
       end
 
       # Normalize options param: accept Array or JSON string; strip, reject empty.
@@ -135,18 +155,6 @@ module Samagotchi
 
         arr.map { |v| sanitize_option(v) }.reject { |v| v.nil? || v.empty? }
       end
-
-      def self.to_bool(v)
-        return nil if v.nil?
-        return v if v == true || v == false
-
-        s = v.to_s.strip.downcase
-        return true if %w[1 true yes on].include?(s)
-        return false if %w[0 false no off].include?(s)
-
-        nil
-      end
-      private_class_method :to_bool
     end
   end
 end

data/lib/samagotchi/tools/builtins.rb

@@ -68,12 +68,16 @@ module Samagotchi
         Edit::NAME => lambda do |call, _kctx|
           Edit.call(call[:content], path: call[:path], start_line: call[:start_line], end_line: call[:end_line])
         end,
-        TaskCreate::NAME => ->(call, _kctx) { TaskCreate.call(call[:content], cwd: call[:cwd], env: call[:env]) },
-        TaskWait::NAME => lambda do |call, _kctx|
+        TaskCreate::NAME => lambda do |call, kctx|
+          next Execute::NOT_RUN_ON_STOP if cancelled_proc(kctx).call
+
+          TaskCreate.call(call[:content], cwd: call[:cwd], env: call[:env])
+        end,
+        TaskWait::NAME => lambda do |call, kctx|
           TaskWait.call(call[:content], timeout: call[:timeout], tail_lines: call[:tail_lines],
-                                        done_pattern: call[:done_pattern])
+                                        done_pattern: call[:done_pattern], cancelled: cancelled_proc(kctx))
         end,
-        Execute::NAME => ->(call, _kctx) { Execute.call(call[:content], cwd: call[:cwd]) },
+        Execute::NAME => ->(call, kctx) { Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx)) },
         RegisterReminder::NAME => lambda do |call, kctx|
           RegisterReminder.call(call[:content], reminder_store: kctx.reminder_store, description: call[:description],
                                                 interval_minutes: call[:interval_minutes])
@@ -94,6 +98,13 @@ module Samagotchi
 
       module_function
 
+      # Stop flips the turn's controller, seen through the Engine's PeerView
+      # (as DelegateWait does); a bare kernel has no peers: never cancelled.
+      def cancelled_proc(kctx)
+        peers = kctx.peers
+        -> { peers.respond_to?(:cancelled?) && peers.cancelled? }
+      end
+
       # @return [Registry] a new registry with the built-ins, in
       #   TOOL_SCHEMAS order (an Engine's own, which bundles add to)
       def registry

data/lib/samagotchi/tools/delegate_wait.rb

@@ -1,22 +1,18 @@
 # frozen_string_literal: true
 
 require_relative "../session"
+require_relative "../reply_wait"
 require_relative "output_guardrails"
 require_relative "peers"
 
 module Samagotchi
-  # Loaded on first use: session_manager requires terminal_ui, which
-  # requires KernelLoop and so these tools (a require cycle otherwise).
-  autoload :SessionManager, File.expand_path("../session_manager", __dir__)
-
   module Tools
     # Waiting for a delegated session's next reply, shared by delegate and
-    # delegate_result. A reply is the child's output/<timestamp>.txt file
-    # (the worker writes one per turn that ended with visible text, just
-    # before its idle save), so "new" means a filename past the cursor: the
-    # newest one this parent was already given. The cursors live in this
-    # process (a worker runs one session), keyed by parent and child; a
-    # worker respawn loses them, which only repeats the newest reply once.
+    # delegate_result: ReplyWait in the tools' words, with a cursor per
+    # child (the newest reply this parent was already given). The cursors
+    # live in this process (a worker runs one session), keyed by parent and
+    # child; a worker respawn loses them, which only repeats the newest reply
+    # once.
     module DelegateWait
       TIMEOUT_DEFAULT = 600
       POLL_INTERVAL = 0.5
@@ -40,70 +36,34 @@ module Samagotchi
       def call(child_id, peers:, timeout: TIMEOUT_DEFAULT, poll_interval: POLL_INTERVAL)
         sd = peers.state_dir || Session.default_state_dir
         key = [peers.session_id, child_id]
-        cursor = seen[key]
-        deadline = monotonic + timeout.to_i
-        seen_running = false
-
-        loop do
-          session = Session.load(child_id, state_dir: sd)
-
-          if (file = newest_reply(child_id, state_dir: sd)) && newer?(file, cursor)
-            seen[key] = file
-            return reply_result(child_id, File.read(File.join(reply_dir(child_id, state_dir: sd), file)))
-          end
-
-          case session.status
-          when Session::STATUS_ERROR
-            return result(child_id, "error", "the child's worker failed: #{session.last_prompt.to_s.strip}; its session shows what happened")
-          when Session::STATUS_STOPPED
-            return result(child_id, "stopped", "the child was stopped (chi sessions stop); delegate with session: #{child_id} starts it again with a message")
-          end
-
-          if (pending = session.pending_question)
-            return result(child_id, "waiting_for_answer", waiting_text(child_id, pending))
-          end
-
-          if peers.respond_to?(:cancelled?) && peers.cancelled?
-            return result(child_id, "canceled", "wait canceled; the child keeps running; delegate_result #{child_id} waits again")
-          end
-
-          if session.status == Session::STATUS_RUNNING
-            seen_running = true
-          elsif seen_running
-            # It ran and is idle again with no new reply: canceled, failed or
-            # empty. Before it was ever seen running, idle means a
-            # file-delivered follow-up its worker has not picked up yet.
-            return result(child_id, "no_reply", "the child's turn ended without a reply (canceled, failed or empty); its session shows what happened")
-          end
-
-          return timeout_result(child_id, timeout) if monotonic > deadline
-
-          sleep(poll_interval)
+        cancelled = -> { peers.respond_to?(:cancelled?) && peers.cancelled? }
+        wait = ReplyWait.call(child_id, state_dir: sd, cursor: seen[key], timeout: timeout.to_i,
+                                        poll_interval: poll_interval, cancelled: cancelled)
+        case wait.status
+        when :done
+          seen[key] = wait.file
+          reply_result(child_id, wait.text)
+        when :error
+          result(child_id, "error", "the child's worker failed: #{wait.text}; its session shows what happened")
+        when :stopped
+          result(child_id, "stopped", "the child was stopped (chi sessions stop); delegate with session: #{child_id} starts it again with a message")
+        when :waiting_for_answer
+          result(child_id, "waiting_for_answer", waiting_text(child_id, wait.question))
+        when :canceled
+          result(child_id, "canceled", "wait canceled; the child keeps running; delegate_result #{child_id} waits again")
+        when :no_reply
+          result(child_id, "no_reply", "the child's turn ended without a reply (canceled, failed or empty); its session shows what happened")
+        else
+          timeout_result(child_id, timeout)
         end
       rescue ArgumentError => e
         "Error: #{e.message}"
       end
 
-      # @return [String, nil] the newest reply filename (sortable timestamps)
-      def newest_reply(child_id, state_dir:)
-        dir = reply_dir(child_id, state_dir: state_dir)
-        return nil unless Dir.exist?(dir)
-
-        Dir.children(dir).select { |f| f.end_with?(".txt") }.max
-      end
-
       # Point the cursor at the newest reply now, so only a later one counts
       # (a follow-up sent to a child that already answered).
       def mark_seen(parent_id, child_id, state_dir:)
-        seen[[parent_id, child_id]] = newest_reply(child_id, state_dir: state_dir)
-      end
-
-      def reply_dir(child_id, state_dir:)
-        File.join(Session.session_dir(child_id, state_dir: state_dir), SessionManager::OUTPUT_DIR)
-      end
-
-      def newer?(file, cursor)
-        cursor.nil? || file > cursor
+        seen[[parent_id, child_id]] = ReplyWait.newest_reply(child_id, state_dir: state_dir)
       end
 
       def reply_result(child_id, text)
@@ -145,9 +105,6 @@ module Samagotchi
         ].join("\n")
       end
 
-      def monotonic
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
     end
   end
 end