samagotchi 0.2.0 → 0.3.0

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -12,6 +12,7 @@ require_relative "reline_seam"
 require_relative "../bridge_client"
 require_relative "../log"
 require_relative "../context_note"
+require_relative "../steer"
 require_relative "../model_profile"
 require_relative "../output_formatter"
 require_relative "../session_commands"
@@ -41,6 +42,8 @@ module Samagotchi
       DELETE_FLAG = "--delete"
       # How long /exit --delete waits for the worker to let go.
       DELETE_WAIT = 10
+      # Leave, and archive the session (hidden from the lists, kept for good).
+      ARCHIVE_COMMAND = "/archive"
       # A second Ctrl-C at an empty idle prompt within this many seconds detaches.
       DETACH_WINDOW = 2.0
       DETACH_HINT = "Ctrl-D to detach, /exit stops the worker"
@@ -82,11 +85,15 @@ module Samagotchi
       #   the first read (a new session with no -p, as the REPL)
       # @param clock [#call] monotonic seconds (the Ctrl-C detach window)
       # @param delete_session [#call] session id -> deletes it (/exit --delete)
+      # @param archive_session [#call] session id -> archives it (/archive);
+      #   SessionManager.archive_session's result
       def initialize(client:, screen:, client_id:, first_prompt: nil, first_command: nil, no_interrupt: false,
                      default_input: false, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
-                     delete_session: ->(id) { SessionManager.delete_session(id, stop: true, wait: DELETE_WAIT) })
+                     delete_session: ->(id) { SessionManager.delete_session(id, stop: true, wait: DELETE_WAIT) },
+                     archive_session: ->(id) { SessionManager.archive_session(id, wait: DELETE_WAIT) })
         @client = client
         @delete_session = delete_session
+        @archive_session = archive_session
         @screen = screen
         @client_id = client_id
         @view = AttachedView.new(screen)
@@ -198,7 +205,7 @@ module Samagotchi
         # Another client's anytime command: its line now, before the cards
         # it shows (its command_ran comes when it's done).
         when :command_queued
-          @screen.commit(prompt_line(event[:client_id], event[:line])) if event[:anytime] && !own?(event[:client_id])
+          @screen.commit(prompt_line(event[:client_id], event[:line])) if event[:anytime] && !own?(event[:client_id]) && !event[:card]
         when :command_ran
           command_ran(event)
           return first_command_ran(event) if @first_command_id && event[:command_id] == @first_command_id
@@ -266,6 +273,7 @@ module Samagotchi
         return submit(nil) if DETACH_COMMANDS.include?(text.downcase)
         return exit_worker if exit_command?(text)
         return exit_and_delete if exit_command?(text.delete_suffix(DELETE_FLAG).rstrip) && text.end_with?(" #{DELETE_FLAG}")
+        return exit_and_archive if text.casecmp?(ARCHIVE_COMMAND)
         command = text.split(/\s+/, 2).first
         if @continue_offer
           return answer_continue(text) unless command_registry.command?(text) || [STATS_COMMAND, RECAP_COMMAND].include?(command)
@@ -329,6 +337,27 @@ module Samagotchi
         detach("Detached; the worker is stopping, but session #{id} was not deleted (#{e.message}): chi sessions delete #{id}")
       end
 
+      # /archive: the worker is asked to exit as for /exit, then the session
+      # is archived. A worker staying up for another UI (or reminders, a
+      # queued prompt) is stopped by the archive, as the web's archive
+      # stops it; a turn running refuses it. An empty session: the worker
+      # deletes it as it leaves.
+      def exit_and_archive
+        reply = @client.request_exit(client_id: @client_id)
+        id = @client.session_id
+        return detach("Detached; the session was empty, so it is discarded.") if reply.status == 200 && discards?(reply)
+        return detach("#{exit_line(reply)} Not archived.") unless [200, 409].include?(reply.status)
+
+        result = @archive_session.call(id)
+        return detach("Detached; the session was empty, so it is discarded.") if result[:discarded].include?(id)
+
+        detach("Detached; archived session #{id}. chi sessions list --archived finds it.")
+      rescue SystemCallError, IOError => e
+        detach("#{exit_failed_line(e.message)} Not archived.")
+      rescue SessionManager::ArchiveRefused, SessionManager::OwnedByTUI, ArgumentError => e
+        detach("Detached; session #{id} was not archived (#{e.message}). Re-attach with: chi --attach #{id}")
+      end
+
       def exit_line(reply)
         id = @client.session_id
         error = reply.json&.fetch("error", nil)
@@ -401,7 +430,7 @@ module Samagotchi
       end
 
       def command_ran(event)
-        @screen.commit(prompt_line(event[:client_id], event[:line])) unless own?(event[:client_id]) || event[:anytime]
+        @screen.commit(prompt_line(event[:client_id], event[:line])) unless own?(event[:client_id]) || event[:anytime] || event[:card]
         output = event[:output].to_s
         if output.empty?
           nil
@@ -816,12 +845,15 @@ module Samagotchi
         # The id stays findable: the detach line and chi sessions list show it.
         Log.session_id = @client.session_id
         Log.info(:attached, "joined", session: @client.session_id, messages: exchange.size)
-        last_user = exchange.rindex { |m| m[:role].to_s == "user" }
+        last_user = exchange.rindex { |m| Steer.prompt?(m) }
         render_join_notes(messages)
         return unless last_user
 
         @screen.commit(prompt_line(nil, exchange[last_user][:content]))
         Array(exchange[last_user][:images]).each { |ref| @screen.commit(format_image_line(ref)) }
+        exchange[(last_user + 1)..].select { |m| Steer.steer?(m) }.each do |m|
+          @screen.commit(format_steer_line(source: m[:source], text: m[:content]))
+        end
         # The saved answer is raw: the latest keeps its thinking, and one may
         # be only a tool call.
         answer = exchange[(last_user + 1)..].reverse_each
@@ -834,7 +866,7 @@ module Samagotchi
       # The context notes that came since the last prompt (all of them in a
       # session with none), after the exchange the header shows.
       def render_join_notes(messages, after_exchange: false)
-        last_user = messages.rindex { |m| m[:role].to_s == "user" }
+        last_user = messages.rindex { |m| Steer.prompt?(m) }
         return if after_exchange != !last_user.nil?
 
         messages[(last_user ? last_user + 1 : 0)..].select { |m| ContextNote.note?(m) }.each do |m|
@@ -894,6 +926,7 @@ module Samagotchi
               @screen.commit(snapshot_tool_line(part))
             end
           when "input" then @screen.commit("input> #{part[:text]}")
+          when "steer" then @screen.commit(format_steer_line(source: part[:source], text: part[:text]))
           when "reminder" then @screen.commit(reminder_line(part[:reminders]))
           when "hook_notice" then @screen.commit(EventRenderer.hook_notice_line(part))
           end
@@ -1029,7 +1062,7 @@ module Samagotchi
         params = part[:params].to_s.strip
         params_suffix = params.empty? ? "" : " #{paint(params, 90)}"
         status = part[:status].to_s
-        "#{paint('tool>', 36)} #{part[:tool]}#{params_suffix}: #{paint(status, status == "ok" ? 32 : 31)}" \
+        "#{paint('tool>', 36)} #{part[:tool]}#{params_suffix}: #{paint(status, status_color(status))}" \
           "#{format_tool_image_suffix(part[:images])}"
       end
     end

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -63,6 +63,9 @@ module Samagotchi
           @view.generation_feedback_finished
         when :pending_input_merged
           render_merge(event)
+        when :empty_answer_retry
+          @view.finish_thinking_spinner
+          @view.print_line(@view.format_empty_retry_line(event))
         when :turn_completed
           render_turn_summary(event[:turn_summary]) if event[:turn_summary]
         when :guardrail_warning
@@ -146,14 +149,16 @@ module Samagotchi
         @view.print_line("iteration limit reached") if summary[:resumable]
       end
 
-# Steering merged into the running turn: the answer it follows first
-# (the turn summary shows only the last one), then the note.
-def render_merge(event)
-  @view.finish_thinking_spinner
-  @view.print_line(event[:answer]) unless event[:answer].to_s.strip.empty?
-  count = event[:count].to_i
-  @view.print_line("(#{count} message#{"s" unless count == 1} merged into the running turn)")
-end
+      # Steering merged into the running turn: the answer it follows first
+      # (the turn summary shows only the last one), then the note, then a
+      # line per plugin steer (none for a steer-only merge).
+      def render_merge(event)
+        @view.finish_thinking_spinner
+        @view.print_line(event[:answer]) unless event[:answer].to_s.strip.empty?
+        count = event[:count].to_i
+        @view.print_line("(#{count} message#{"s" unless count == 1} merged into the running turn)") if count.positive?
+        Array(event[:steers]).each { |steer| @view.print_line(@view.format_steer_line(source: steer[:source], text: steer[:text])) }
+      end
 
 private
 

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -13,9 +13,13 @@ module Samagotchi
         params = activity[:params].to_s.strip
         params_suffix = params.empty? ? "" : " #{paint(params, 90)}"
         status = activity[:status].to_s
-        status_color = status == "ok" ? 32 : 31
         elapsed_suffix = duration_ms.nil? ? "" : " (#{format_elapsed_duration(duration_ms)})"
-        "#{paint('tool>', 36)} #{activity[:action]} (#{activity[:tool]}#{params_suffix}): #{paint(status, status_color)}#{elapsed_suffix}"
+        "#{paint('tool>', 36)} #{activity[:action]} (#{activity[:tool]}#{params_suffix}): #{paint(status, status_color(status))}#{elapsed_suffix}"
+      end
+
+      # Green ok, yellow stopped (a wait the user's Stop ended), red the rest.
+      def status_color(status)
+        { "ok" => 32, "stopped" => 33 }.fetch(status, 31)
       end
 
       # "[image shot.png 1280×800 · ~1.3k tokens]", dim: a turn's image.
@@ -23,6 +27,21 @@ module Samagotchi
         paint("[image #{ImageRef.label(ImageStore.symbolize(ref))}]", 90)
       end
 
+      STEER_PREVIEW = 80
+
+      # "check-in> nudged: <text>", dim, one line cut: a plugin's steer
+      # (Steer) in the running turn or the join's last exchange.
+      def format_steer_line(source:, text:)
+        first = text.to_s.strip.split("\n").first.to_s
+        first = "#{first[0, STEER_PREVIEW - 1]}…" if first.length > STEER_PREVIEW || text.to_s.strip.include?("\n")
+        paint("#{source.to_s.empty? ? "plugin" : source}> nudged: #{first}", 90)
+      end
+
+      # "↻ empty answer, asking again (1/1)": the loop retries an empty answer.
+      def format_empty_retry_line(event)
+        paint("↻ empty answer, asking again (#{event[:attempt]}/#{event[:of]})", 90)
+      end
+
       # " → image 1280×800" after a tool line whose tool read an image.
       def format_tool_image_suffix(images)
         refs = Array(images).map { |ref| ImageStore.symbolize(ref) }
@@ -229,11 +248,11 @@ module Samagotchi
       def format_session_metrics(snapshot)
         return "(no metrics yet)" unless snapshot.is_a?(Hash)
 
-        # A symbol locally; a string when the snapshot came over the Bridge.
-        token_src = snapshot[:token_source]&.to_s
-        token_src_label = case token_src
+        tokens = snapshot[:tokens] || {}
+        token_src_label = case tokens[:source]
                           when "server" then "server-reported"
                           when "estimate" then "estimated (chars/4)"
+                          when "mixed" then "server-reported, some estimated"
                           else "n/a"
                           end
 
@@ -245,13 +264,17 @@ module Samagotchi
           lines << "  by tool:        #{by_tool.map { |k, v| "#{k}=#{v}" }.join(", ")}"
         end
         lines << "iterations:       #{snapshot[:iterations_total]}"
-        lines << "tokens in/out:    #{snapshot[:tokens_in]}/#{snapshot[:tokens_out]} (total #{snapshot[:tokens_total]}, #{token_src_label})"
+        # Summed over every request: each prompt is sent in full again.
+        lines << "tokens in/out:    #{tokens[:prompt_sum].to_i}/#{tokens[:completion_sum].to_i} (all requests, #{token_src_label})"
         lines << "gen latency (ms): #{snapshot[:gen_latency_ms]}"
         lines << "cancellations:    #{snapshot[:cancellations]}"
         lines << "retries:          #{snapshot[:retries]}"
-        if snapshot[:context_window_tokens]
-          lines << "context window:   #{snapshot[:context_window_tokens]} tokens (#{snapshot[:context_window_source]})"
+        context = snapshot[:context] || {}
+        if context[:used_tokens]
+          pct = context[:window_tokens].to_i.positive? ? format(" (%.1f%%)", context[:used_tokens] * 100.0 / context[:window_tokens]) : ""
+          lines << "context used:     #{context[:used_tokens]} tokens#{pct}"
         end
+        lines << "context window:   #{context[:window_tokens]} tokens (#{context[:window_source]})" if context[:window_tokens]
         lines << "prompt profile:   #{snapshot[:profile]} (#{snapshot[:profile_source]})" if snapshot[:profile]
         if snapshot[:served_model]
           asked = snapshot[:served_model_for]

data/lib/samagotchi/terminal_ui/input_support.rb

@@ -240,7 +240,10 @@ module Samagotchi
         nil
       end
 
+      # A scratch session keeps nothing, its typed lines neither.
       def persist_recent_history(input)
+        return if @scratch
+
         entries = normalize_history_entries(load_history_entries_from_disk)
         entries << input
         trimmed_entries = entries.last(PROMPT_HISTORY_LIMIT)

data/lib/samagotchi/terminal_ui.rb

@@ -52,6 +52,9 @@ module Samagotchi
     STATS_COMMAND = "/stats"
     # /exit --delete: delete the session on the way out.
     EXIT_DELETE_FLAG = "--delete"
+    # Leave, then archive the session (hidden from the lists, kept for good).
+    ARCHIVE_COMMAND = "/archive"
+    SCRATCH_ARCHIVE_REFUSED = "a scratch session is deleted when you leave; nothing to archive"
     RECAP_COMMAND = "/recap"
     # The prompt while a question waits for its answer (its choices are in
     # the notes slot).
@@ -103,9 +106,12 @@ module Samagotchi
       Engine.system_prompt_for(profile)
     end
 
+    # @param scratch [Boolean] `chi scratch`: a new session that is deleted
+    #   however the REPL ends, saves no memories and writes no recap
     def initialize(mode: :assist, prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
-                   spinner_tick_interval: THINKING_TICK_INTERVAL)
+                   spinner_tick_interval: THINKING_TICK_INTERVAL, scratch: false)
       @mode           = mode.to_sym
+      @scratch        = scratch
       # nil: no ticker thread (specs that compare exact frames).
       @spinner_tick_interval = spinner_tick_interval
       @spinner_lock = Monitor.new
@@ -176,7 +182,8 @@ module Samagotchi
         memories: @requested_memories,
         muted_memories: @muted_memory_names,
         kernel: @kernel,
-        recap: recap_config,
+        recap: scratch ? nil : recap_config,
+        scratch: scratch,
         reminders: {
           callback: lambda { |due_names|
             # When a reminder is due, queue a synthetic turn that
@@ -242,15 +249,20 @@ module Samagotchi
         model_name: @effective_model_name,
         working_directory: Dir.pwd,
         preloaded_memory_names: @requested_memories,
-        muted_memory_names: @muted_memory_names
+        muted_memory_names: @muted_memory_names,
+        scratch: @scratch
       )
       claim_session!(session.id) unless @owner_lock
+      # Saved at once, so a process killed before its first turn leaves a
+      # file the sweep knows to delete.
+      session.save if @scratch
       # Attach before building the prompt so it can name the session id.
       @engine.session = session
       messages = messages_for(session)
 
       if @prompt && @non_interactive
         # Headless / CI mode: run directly without TTY rendering.
+        ArchiveStore.user_input(session.id, state_dir: Session.default_state_dir)
         result = @engine.run_turn(
           session,
           @prompt,
@@ -259,6 +271,13 @@ module Samagotchi
           cancel_controller: nil,
           images: ImageInput.extract(@prompt)
         )
+        if empty_answer?(result)
+          # Nothing to print: say so on stderr and fail, so a script that
+          # pipes the answer doesn't take the silence for one.
+          session.save
+          warn EMPTY_ANSWER_ERROR
+          exit 1
+        end
         @surface.commit(result.output)
         session.save
         return
@@ -266,10 +285,14 @@ module Samagotchi
 
       assist_loop(session: session, messages: messages)
       # After the idle layer has stopped: nothing writes the session now.
-      if @delete_on_exit
+      if @scratch
+        nil # deleted below, however the REPL ended
+      elsif @delete_on_exit
         delete_after_exit(session)
       elsif @discard_on_exit
         discard_after_exit(session)
+      elsif @archive_on_exit
+        archive_after_exit(session)
       else
         keep_after_exit(session)
       end
@@ -278,6 +301,32 @@ module Samagotchi
       # #initialize): the anytime commands finish, the plugins' services
       # stop (a server process).
       @engine&.shutdown
+      # A scratch session goes on every way out: /exit, Ctrl-D, an error,
+      # SIGTERM or SIGHUP (Ruby raises those here). Only kill -9 leaves it
+      # to the sweep.
+      delete_scratch(session, quiet: @non_interactive || !$!.nil?) if @scratch && session
+    end
+
+    EMPTY_ANSWER_ERROR = "chi: the model gave an empty answer"
+
+    # A -p --non-interactive turn that ended with no answer (the empty-answer
+    # retries used up): no text, or the chat loop's placeholder.
+    def empty_answer?(result)
+      return false if result.respond_to?(:canceled?) && result.canceled?
+      return false if result.respond_to?(:resumable?) && result.resumable?
+
+      result.output.to_s.strip.empty? || (result.respond_to?(:empty_answer?) && result.empty_answer?)
+    end
+
+    # Delete the scratch session, the last thing the REPL does. Quiet after
+    # a one-shot or on the way out of an error or a signal.
+    def delete_scratch(session, quiet:)
+      @owner_lock&.release
+      @owner_lock = nil
+      SessionManager.delete_session(session.id)
+      @surface.commit("Scratch session deleted.") unless quiet
+    rescue StandardError => e
+      warn "Scratch session #{session.id} was not deleted (#{e.message}): chi sessions delete #{session.id}"
     end
 
     # The session stays: the recap first, then the resume line, last.
@@ -330,6 +379,17 @@ module Samagotchi
       @surface.commit("Session #{session.id} was not deleted (#{e.message}): chi sessions delete #{session.id}")
     end
 
+    # /archive: give up the session, then archive it (hidden from the lists,
+    # kept for good). An empty one is discarded instead (#discard_on_exit?).
+    def archive_after_exit(session)
+      @owner_lock&.release
+      @owner_lock = nil
+      SessionManager.archive_session(session.id)
+      @surface.commit("Archived session #{session.id}. chi sessions list --archived finds it.")
+    rescue SessionManager::ArchiveRefused, SessionManager::OwnedByTUI, ArgumentError, SystemCallError => e
+      @surface.commit("Session #{session.id} was not archived (#{e.message}): chi sessions archive #{session.id}")
+    end
+
     # Take the session's OwnerLock for this process's lifetime: the TUI runs
     # its own Engine, so no worker may run the session meanwhile.
     # @raise [SessionBusy] when a worker or another TUI owns it
@@ -356,6 +416,9 @@ module Samagotchi
         @surface.commit("Resumed session: #{session.id}")
         saved = @engine.saved_recap
         @surface.commit(recap_block(saved[:text], turns_since: saved[:turns_since])) if saved
+      elsif @scratch
+        messages = [system_message]
+        @surface.commit("Scratch session: nothing is kept, it is deleted when you leave.")
       else
         messages = [system_message]
         @surface.commit("Session: #{session.id}")
@@ -500,6 +563,12 @@ module Samagotchi
           @delete_on_exit ||= delete_on_exit?(input)
           break
         end
+        if archive_command?(input)
+          next @surface.commit(SCRATCH_ARCHIVE_REFUSED) if @scratch
+
+          @archive_on_exit = true
+          break
+        end
         # Not an answer to a continue offer either.
         next detach_note if detach_command?(input)
 
@@ -1001,6 +1070,8 @@ module Samagotchi
 
     def detach_command?(input) = input.to_s.strip.casecmp?("/detach")
 
+    def archive_command?(input) = input.to_s.strip.casecmp?(ARCHIVE_COMMAND)
+
     def clone_messages(messages)
       Array(messages).map(&:dup)
     end
@@ -1024,6 +1095,8 @@ module Samagotchi
       # Build the (memoized) prompt now so --memory activations show in this
       # turn's status lines, including after /model rebuilt it.
       seed_system_prompt
+      # A prompt the user typed brings an archived session back to the lists.
+      ArchiveStore.user_input(session.id, state_dir: Session.default_state_dir) if prompt && !continue
       result = with_steering do
         @engine.run_turn(
           session,

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/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