samagotchi 0.63.0 → 0.64.0

data/lib/samagotchi/reply_wait.rb

@@ -3,6 +3,7 @@
 require_relative "session"
 require_relative "turn_note"
 require_relative "session_inbox"
+require_relative "worker_sidecar"
 
 module Samagotchi
   # Loaded on first use: session_manager requires terminal_ui, which
@@ -14,9 +15,15 @@ module Samagotchi
   # output/<timestamp>.txt file (one per turn that ended with visible text,
   # written just before its idle save), so "next" means a filename past the
   # cursor the caller holds: the newest one it already has, or nil for any.
+  # A wait for one input's turn (turn:, a queued message) looks for that
+  # turn's own file instead (output/<timestamp>-<enqueued_id>.txt).
   # The delegate tools and `chi send --wait` wrap it in their own words.
   module ReplyWait
     POLL_INTERVAL = 0.5
+    # A worker's sidecar feature (Bridge::FEATURES): its running turn's
+    # checkpoint mark (InterruptedTurn#enqueued_id), a continue turn and a
+    # Stop's last_turn carry the turn's enqueued_id (#own_turn).
+    TURN_IDS_FEATURE = "turn_ids"
 
     # @!attribute status [Symbol] :done, :waiting_for_answer, :no_reply,
     #   :error, :stopped, :canceled, :timeout or :worker_gone
@@ -38,7 +45,9 @@ module Samagotchi
     # @!attribute retryable [Boolean, nil] whether that error may pass on a
     #   retry
     # @!attribute cancel_reason [String, nil] a "canceled" turn's reason
-    #   (user, hook, ctrl_c, manual)
+    #   (user, hook, ctrl_c, manual, session_stopped: the session was
+    #   stopped mid-turn), passed through as the worker saved it; any
+    #   reason is a "canceled" outcome
     # @!attribute stopped_by [String, nil] the hook that canceled it
     #   (loop-guard)
     # @!attribute session [Session, nil] the session as the look that
@@ -70,18 +79,64 @@ module Samagotchi
     # @param interject [#call, nil] called once a poll, before the sleep
     #   (the delegate wait relays other children's approvals there); the
     #   time it takes doesn't count against +timeout+
+    # @param turn [String, nil] the enqueued_id of the input whose turn is
+    #   waited for (a queued message, which runs after the turn running
+    #   now). With it only that turn ends the wait: its reply file
+    #   (SessionInbox.reply_for), or an idle session whose last_turn has
+    #   that enqueued_id (failed, canceled, empty: #no_reply). Other turns'
+    #   replies and ends are not its, and a pending question counts only
+    #   when it is that turn's (#own_question?). A last_turn that ended
+    #   before the baseline's (the turn whose continue offer was just
+    #   answered) is not the end. An input a running turn merged as a
+    #   steer (taken, never run as its own) is waited for as without turn:
+    #   (that turn's reply or question). A turn seen running, then past
+    #   (another turn runs or ended, last_turn not it): :no_reply, outcome
+    #   unknown.
+    # @param queued [Boolean] the turn: input was sent as a queue (or with
+    #   images), which a running turn never merges: no fallback, even when
+    #   its file was taken before the first look
     # @return [Result]
     # @raise [ArgumentError] no such session
     def call(id, state_dir:, cursor:, timeout: nil, poll_interval: POLL_INTERVAL, cancelled: -> { false },
-             baseline: nil, owner_grace: nil, interject: nil)
+             baseline: nil, owner_grace: nil, interject: nil, turn: nil, queued: false)
       deadline = timeout && (monotonic + timeout.to_f)
       seen_running = false
       gone_since = nil
+      turn = turn.to_s.empty? ? nil : turn.to_s
+      session_dir = Session.session_dir(id, state_dir: state_dir) if turn
+      # Whether the turn's input file has been taken (latched): looked at
+      # before each load, so a running session seen after it is that turn
+      # or a later one, never the turn that ran when the message was sent.
+      claimed = false
+      # Its input runs a turn of its own (a queue, images: +queued+, or seen
+      # waiting as one): never merged into another turn.
+      own_turn_input = queued
+      # The turn was seen running (its mark's id), and last_turn's ended_at
+      # then: a later end that isn't its is a turn after it.
+      seen_own = false
+      own_base = nil
 
       loop do
+        if turn && !claimed
+          waiting = SessionInbox.waiting_input(session_dir, turn)
+          own_turn_input ||= waiting == :turn_end
+          claimed = waiting.nil?
+        end
         session = Session.load(id, state_dir: state_dir)
+        if turn && !seen_own && session.status == Session::STATUS_RUNNING && session.interrupted_turn&.enqueued_id == turn
+          seen_own = true
+          own_base = session.last_turn&.ended_at
+        end
+        # Taken but never run as a turn of its own: a running turn's drain
+        # merged it as a steer, so that turn's reply (or question) is its
+        # answer. Waited for as the next reply past the cursor, as without
+        # turn:, never as a turn that will not come.
+        if turn && claimed && !seen_own && !own_turn_input && merged_elsewhere?(session, turn, baseline, session_dir)
+          turn = nil
+          seen_running = session.status == Session::STATUS_RUNNING
+        end
 
-        if (reply = reply_past(id, state_dir: state_dir, cursor: cursor))
+        if (reply = turn ? reply_for_turn(id, state_dir: state_dir, turn: turn) : reply_past(id, state_dir: state_dir, cursor: cursor))
           reply.session = settled(session, id, state_dir: state_dir)
           return reply
         end
@@ -98,13 +153,31 @@ module Samagotchi
         # REPL's is answered there.
         pending = session.pending_question
         if pending && !(baseline && pending[:id] == baseline[:question_id]) &&
+           (turn.nil? || own_question?(session, turn, claimed)) &&
            session.waiting_question(live: SessionManager.worker_live?(id, state_dir: state_dir))
           return Result.new(status: :waiting_for_answer, question: pending, session: session)
         end
 
         return Result.new(status: :canceled) if cancelled.call
 
-        if session.status == Session::STATUS_RUNNING
+        if turn
+          # Only the turn's own end: the session runs another turn when the
+          # wait starts, and that one's end is not the answer. A last_turn
+          # with its id is its end, even with a next queued turn running
+          # by now (the look between the two missed the idle).
+          # Only an end after the baseline: a continue offer answered from
+          # idle leaves the exhausted turn's last_turn, with the same id,
+          # until the continue turn (or a Stop) records its own.
+          if session.last_turn&.enqueued_id == turn && ended_since_baseline?(session, baseline)
+            return reply_for_turn(id, state_dir: state_dir, turn: turn)&.tap { |r| r.session = session } ||
+                   no_reply(session, baseline, fresh: true)
+          end
+          # Seen running, and now another turn runs or a later turn ended
+          # while last_turn (looked at first) isn't its: lost (its worker
+          # died), or it ended with no reply and a next turn ran and ended
+          # between two looks. Waiting on would sit through those turns.
+          return Result.new(status: :no_reply, session: session) if seen_own && past_own?(session, turn, own_base)
+        elsif session.status == Session::STATUS_RUNNING
           seen_running = true
         elsif (seen_running && !baseline&.key?(:last_turn)) || turn_ended_since?(session, baseline)
           # It ran and is idle again with no new reply: canceled, failed or
@@ -164,11 +237,103 @@ module Samagotchi
       !!(baseline[:messages] && session.messages.size > baseline[:messages])
     end
 
+    # The turn a caller that sent nothing means (chi answer, chi send --wait
+    # with no message): the one running now (its checkpoint mark's
+    # enqueued_id), or, idle, the turn whose continue offer stands (its
+    # last_turn's), when the worker's sidecar says it ties a continue turn
+    # to that id (TURN_IDS_FEATURE). nil otherwise (no id known, a worker
+    # from before): the caller waits for the next reply as before.
+    # @param session [Session] the session as loaded now
+    # @return [String, nil] an enqueued_id for call's turn:
+    def own_turn(session, session_dir:)
+      if session.status == Session::STATUS_RUNNING
+        # Only a worker that writes it has one: no feature check.
+        return session.interrupted_turn&.enqueued_id
+      end
+
+      pending = session.pending_question
+      return nil unless pending && pending[:kind].to_s == "continue"
+      return nil unless turn_ids?(session_dir)
+
+      session.last_turn&.enqueued_id
+    end
+
+    # Whether the session's worker sidecar names TURN_IDS_FEATURE.
+    def turn_ids?(session_dir)
+      WorkerSidecar.read(session_dir)&.features&.include?(TURN_IDS_FEATURE) || false
+    end
+
+    # A pending question is a turn: wait's (its enqueued_id) only when that
+    # turn asked it. While a turn runs its checkpoint mark says which turn
+    # that is (a continue turn carries its offer turn's id); a mark with no
+    # id (a worker from before) falls back to the claimed rule (its input
+    # claimed, the session running, last_turn not already it). Idle: only
+    # its own continue offer (last_turn has the id). Any other is another
+    # turn's, whose questions are the user's: the wait goes on.
+    def own_question?(session, turn, claimed)
+      ended = session.last_turn&.enqueued_id == turn
+      return ended unless session.status == Session::STATUS_RUNNING
+
+      running_id = session.interrupted_turn&.enqueued_id
+      return running_id == turn if running_id
+
+      # Ended, running again: a next turn.
+      !ended && claimed
+    end
+
+    # The turn's end, after the baseline was taken (with no baseline, or
+    # one without last_turn, any).
+    def ended_since_baseline?(session, baseline)
+      return true unless baseline&.key?(:last_turn)
+
+      session.last_turn&.ended_at != baseline[:last_turn]
+    end
+
+    # A turn: wait's taken input ran in another turn (a steer its drain
+    # merged): that turn runs (its mark has another id, or none from a
+    # worker that writes ids), or, idle, a turn not its ended since the
+    # baseline. last_turn or a reply file being its own is never that.
+    def merged_elsewhere?(session, turn, baseline, session_dir)
+      return false if session.last_turn&.enqueued_id == turn || SessionInbox.reply_for(session_dir, turn)
+
+      if session.status == Session::STATUS_RUNNING
+        running_id = session.interrupted_turn&.enqueued_id
+        return running_id != turn if running_id
+
+        return turn_ids?(session_dir)
+      end
+      baseline&.key?(:last_turn) ? turn_ended_since?(session, baseline) : false
+    end
+
+    # A turn seen running (+own_base+: last_turn's ended_at then) is past:
+    # last_turn isn't its, and another turn runs (a mark with another id)
+    # or a turn ended since.
+    def past_own?(session, turn, own_base)
+      return false if session.last_turn&.enqueued_id == turn
+
+      running_id = session.status == Session::STATUS_RUNNING ? session.interrupted_turn&.enqueued_id : nil
+      return true if running_id && running_id != turn
+
+      ended = session.last_turn&.ended_at
+      !ended.nil? && ended != own_base
+    end
+
+    # @return [Result, nil] :done with the reply of the turn that ran the
+    #   input +turn+ (its enqueued_id)
+    def reply_for_turn(id, state_dir:, turn:)
+      file = SessionInbox.reply_for(Session.session_dir(id, state_dir: state_dir), turn)
+      return nil unless file
+
+      Result.new(status: :done, text: File.read(File.join(reply_dir(id, state_dir: state_dir), file)), file: file)
+    end
+
+    # @param fresh [Boolean, nil] the last_turn is known to be the turn
+    #   waited for (a turn: wait); nil decides it from the baseline
     # @return [Result] :no_reply with the outcome the session's last_turn
     #   records, when it is the turn waited for
-    def no_reply(session, baseline)
+    def no_reply(session, baseline, fresh: nil)
       last = session.last_turn || LastTurn.new
-      fresh = baseline.nil? || !baseline.key?(:last_turn) || (last.ended_at && last.ended_at != baseline[:last_turn])
+      fresh = baseline.nil? || !baseline.key?(:last_turn) || (last.ended_at && last.ended_at != baseline[:last_turn]) if fresh.nil?
       outcome = fresh ? last.outcome : nil
       return Result.new(status: :no_reply, outcome: "exhausted", limit: last.limit, session: session) if fresh && last.exhausted
 

data/lib/samagotchi/send_command.rb

@@ -38,10 +38,11 @@ module Samagotchi
     CUT_OUTCOMES = %w[now waits off].freeze
 
     USAGE = <<~TEXT
-      Usage: chi send [-m TEXT] [--image PATH]... [--cut] (ID|PREFIX)...
+      Usage: chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...
              chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [--thinking LEVEL] [-m TEXT] [--image PATH]...
              chi send --new --continues (ID|PREFIX|last:ID) [-m TEXT] [--image PATH]...
              chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
+             chi send --queue --wait [--timeout S] [--format json] [-m TEXT] ID
              chi send --wait [--timeout S] [--format json] ID
         Sends a message to each session, as if typed in it: a turn starts,
         or a running one takes it at its next step. A stopped session's
@@ -92,6 +93,12 @@ module Samagotchi
                     next step and cuts nothing. To an idle session it
                     sends normally. Refused with --wait into a running
                     turn (the steer's turn is the running one)
+        --queue     run the message as a turn of its own after the running
+                    turn ends, instead of merging it at its next step. To
+                    an idle session it runs at once. With --wait it
+                    waits for that turn's own answer, so a running turn
+                    is fine. Not with --cut. Refused for a worker older
+                    than queueing (it would steer; restart it)
         --timeout S (--wait) give up after S seconds, exit 4 (the turn
                     goes on); default no limit
         --format json
@@ -99,8 +106,9 @@ module Samagotchi
                     status answered (text), question (question,
                     answer_with), running, or failed, canceled,
                     limit, no_answer, error, worker_gone, stopped,
-                    command (detail); with --cut also delivery (what
-                    the worker applied) and cut (now, waits, off)
+                    command (detail); with --cut or --queue also
+                    delivery (what the worker applied: next_step, cut,
+                    queue), with --cut also cut (now, waits, off)
         Exit with --wait: 0 answered, 1 failed or gone, 2 usage, 3 a
         question waits, 4 still running (--timeout), 130 Ctrl-C.
         Only sessions on this machine. Answers show in the attached TUI
@@ -121,6 +129,7 @@ module Samagotchi
       f.value "--image", key: :images, repeat: true
       f.switch "--wait"
       f.switch "--cut"
+      f.switch "--queue"
       f.value "--timeout"
       f.value "--format"
       # Starting a turn in every live session at once is too easy to do
@@ -181,6 +190,7 @@ module Samagotchi
       # With --wait stdout is the answer alone.
       @info = options[:wait] ? @stderr : @stdout
       @cut = options[:cut] == true
+      @queue = options[:queue] == true
       prompt = compose(utf8(read_stdin), utf8(options[:message]))
       # Before the wait-only case, which would drop the images.
       return usage_error("--image needs a message: pass -m TEXT or pipe it in") if prompt.nil? && !options[:images].empty?
@@ -236,6 +246,8 @@ module Samagotchi
       return parsed if parsed.is_a?(Integer)
 
       options = parsed.options.merge(ids: parsed.args)
+      return usage_error("--cut and --queue: choose one") if options[:cut] && options[:queue]
+
       if options[:format]
         return usage_error("--format needs --wait") unless options[:wait]
         return usage_error("--format takes text or json") unless FORMATS.include?(options[:format])
@@ -385,12 +397,15 @@ module Samagotchi
     # are taken before the message goes in, so neither an older reply nor a
     # turn that ends before the first look is mistaken for the answer. A
     # running turn is refused: a message that misses it runs next, and the
-    # running one's reply would come back as the answer.
+    # running one's reply would come back as the answer. Not with --queue:
+    # the message's own turn is waited for (ReplyWait's turn:, its
+    # enqueued_id), whatever runs before it.
     # @return [Integer] the exit status
     def run_wait(prompt, options)
       id = resolve(options[:ids].first) or return 1
       session = Session.load(id, state_dir: @state_dir)
-      if session.status == Session::STATUS_RUNNING && (owner = SessionManager.session_owner(id, state_dir: @state_dir))
+      if session.status == Session::STATUS_RUNNING && (owner = SessionManager.session_owner(id, state_dir: @state_dir)) &&
+         (!@queue || session.waiting_question(live: owner.worker?))
         # The turn waits on a question: the message would only queue
         # behind it, and the answer goes in with chi answer.
         if (waiting = session.waiting_question(live: owner.worker?))
@@ -412,7 +427,11 @@ module Samagotchi
       return 1 unless deliver(id, prompt)
       return report_command(id) if @sent_command
 
-      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout])
+      # The ack's id names the queued message's turn, also when the turn
+      # running at the check ended before it went in (an idle worker's ack
+      # says next_step, and the file still runs as that turn).
+      turn = @queue ? @sent_enqueued_id : nil
+      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout], turn: turn, queued: !turn.nil?)
     end
 
     # --wait with no message: the session's next reply, sending nothing,
@@ -421,15 +440,18 @@ module Samagotchi
     # was already reported. No message count: a note landing between turns
     # grows the messages without a turn. An idle session with no worker
     # waits for whatever wakes one (the web, chi send) rather than calling
-    # it gone.
+    # it gone. The turn running now, or the one whose continue offer
+    # stands, is the one waited for (ReplyWait.own_turn): its reply, not a
+    # turn's queued behind it; with none known, the next reply.
     # @return [Integer] the exit status
     def run_wait_only(options)
       id = resolve(options[:ids].first) or return 1
       session = Session.load(id, state_dir: @state_dir)
       live = session.status == Session::STATUS_RUNNING || SessionManager.session_owner(id, state_dir: @state_dir)
+      turn = ReplyWait.own_turn(session, session_dir: Session.session_dir(id, state_dir: @state_dir))
       wait_for_reply(id, cursor: ReplyWait.newest_reply(id, state_dir: @state_dir),
                          baseline: baseline_of(session).merge(messages: nil),
-                         timeout: options[:timeout], owner_grace: live ? self.class::WORKER_GONE_AFTER : nil)
+                         timeout: options[:timeout], owner_grace: live ? self.class::WORKER_GONE_AFTER : nil, turn: turn)
     end
 
     # The session as it was before the message went in (ReplyWait's
@@ -535,13 +557,21 @@ module Samagotchi
       owner = SessionManager.session_owner(id, state_dir: @state_dir)
       running = owner && session.status == Session::STATUS_RUNNING
       refs = copy_images(Session.session_dir(id, state_dir: @state_dir))
-      # --cut asks the running turn for a cut; to an idle session it is an
-      # ordinary message (there is nothing to cut).
-      delivery = @cut && running ? Delivery::CUT : nil
+      # --cut asks the running turn for a cut (to an idle session an
+      # ordinary message: nothing to cut). --queue always goes as a queue,
+      # idle or not: the Bridge acks next_step to an idle worker and the
+      # file still carries it, so a turn another client starts first never
+      # merges it, and its turn and reply carry its enqueued_id (the
+      # --wait's turn:); a worker older than queueing is refused.
+      delivery = if @queue then Delivery::QUEUE
+                 elsif @cut && running then Delivery::CUT
+                 end
       result = SessionManager.deliver_turn(id, prompt: prompt, client_id: CLIENT_ID, images: refs, state_dir: @state_dir,
                                                delivery: delivery)
       unless result[:status] == :accepted
-        @info.puts("#{short}  failed: #{result.dig(:ack, "detail") || "could not queue it"}")
+        # A worker older than queueing would steer it: refused, not sent.
+        word = result.dig(:ack, "error") == Delivery::QUEUE_UNAVAILABLE["error"] ? "refused" : "failed"
+        @info.puts("#{short}  #{word}: #{result.dig(:ack, "detail") || "could not queue it"}")
         return false
       end
 
@@ -556,6 +586,7 @@ module Samagotchi
       # (next_step for an idle session) and a cut's outcome.
       @sent_delivery = ack["delivery"] || delivery
       @sent_cut = ack["cut"]
+      @sent_enqueued_id = (ack["enqueued_id"] || ack[:enqueued_id])&.to_s
       @info.puts("#{short}  sent#{with_images}#{delivery_note(ack, delivery: delivery, running: running, owner: owner)}")
       true
     rescue SessionManager::OwnedByTUI
@@ -568,12 +599,14 @@ module Samagotchi
 
     # What the line says became of the message: a plain one goes in at the
     # running turn's next step (nothing cuts by default); a --cut one names
-    # the outcome from the ack (now, waits, off); images keep their own
-    # wording; an idle session's turn simply runs.
+    # the outcome from the ack (now, waits, off); a --queue one runs after
+    # the turn (or now, when the turn ended before it went in); images keep
+    # their own wording; an idle session's turn simply runs.
     # @param ack [Hash] the Bridge's 202 body ({} for the input file)
     # @return [String] "" or " (...)"
     def delivery_note(ack, delivery:, running:, owner:)
       return " (started its worker)" if owner.nil?
+      return queue_note(ack, running: running) if Delivery.queue?(delivery)
       return "" unless running
 
       # A busy worker runs a message with images as its own next turn
@@ -589,12 +622,23 @@ module Samagotchi
       " #{TerminalUI::Formatting.steer_cut_note(outcome.to_sym, ack["cut_after"])}"
     end
 
-    # More keys for --format json, with --cut only (the line is unchanged
-    # otherwise): the delivery the worker applied (next_step to an idle
-    # session) and a cut's outcome (now, waits, off). In P1 --cut --wait is
-    # refused for a running turn, so the json line says next_step.
+    # A --queue, worded from the Bridge's ack: queue when a turn ran as it
+    # went in (one another client started too), next_step when none did
+    # (it runs now). The input file (no Bridge) carries the queue to
+    # whichever turn runs: worded from the session as chi read it.
+    def queue_note(ack, running:)
+      queued = ack.key?("delivery") ? ack["delivery"] == Delivery::QUEUE : running
+      return " (queued: runs after the current turn)" if queued
+
+      running ? " (the running turn had ended: it runs now)" : " (nothing running: it runs now)"
+    end
+
+    # More keys for --format json, with --cut or --queue only (the line is
+    # unchanged otherwise): the delivery the worker applied (next_step to
+    # an idle session) and a cut's outcome (now, waits, off). --cut --wait
+    # is refused for a running turn, so its json line says next_step.
     def report_extra
-      return {} unless @cut
+      return {} unless @cut || @queue
 
       extra = { delivery: @sent_delivery || Delivery::NEXT_STEP }
       extra[:cut] = @sent_cut if @sent_cut

data/lib/samagotchi/session_commands.rb

@@ -116,7 +116,7 @@ module Samagotchi
       registry.register("/detach", "leave and keep the worker running", local: true, uis: [:attached],
                                                                         match: ->(text) { text.casecmp?("/detach") })
       # /cut TEXT and /queue TEXT while a turn runs: a delivery the UIs parse
-      # themselves (Formatting#steer_choice) before any command check; the
+      # themselves (ComposerRoute.steer_choice) before any command check; the
       # entries exist for Tab completion and /help. The web composer sends
       # /cut too. /queue is a real after-the-turn list only in the local
       # REPL (the attached TUI's worker doesn't skip queued files yet), so

data/lib/samagotchi/session_inbox.rb

@@ -158,11 +158,39 @@ module Samagotchi
       nil
     end
 
-    def self.write_output(session_dir, response)
+    # A turn's reply: output/<timestamp>.txt, or
+    # output/<timestamp>-<enqueued_id>.txt for a turn that ran an input
+    # with an id, so a wait for that input's turn (ReplyWait's turn:) finds
+    # its own reply. The names still sort by time ("-" sorts before ".",
+    # so an id'd name and a bare one of the same timestamp keep order);
+    # every reader globs *.txt.
+    # @param enqueued_id [String, nil] the turn's input id (LastTurn#enqueued_id)
+    def self.write_output(session_dir, response, enqueued_id: nil)
       output_dir = File.join(session_dir, OUTPUT_DIR)
       FileUtils.mkdir_p(output_dir)
       timestamp = Time.now.strftime("%Y%m%d%H%M%S%9N")
-      AtomicFile.write(File.join(output_dir, "#{timestamp}.txt"), response.to_s)
+      AtomicFile.write(File.join(output_dir, "#{output_name(timestamp, enqueued_id)}.txt"), response.to_s)
+    end
+
+    # An id that is safe in a file name (a Bridge's or deliver_turn's
+    # uuid); anything else leaves the name bare.
+    ENQUEUED_ID_NAME = /\A[A-Za-z0-9_-]{1,64}\z/
+
+    def self.output_name(timestamp, enqueued_id)
+      id = enqueued_id.to_s
+      ENQUEUED_ID_NAME.match?(id) ? "#{timestamp}-#{id}" : timestamp
+    end
+    private_class_method :output_name
+
+    # @return [String, nil] the reply filename of the turn that ran the
+    #   input +enqueued_id+, or nil while it has none
+    def self.reply_for(session_dir, enqueued_id)
+      dir = File.join(session_dir, OUTPUT_DIR)
+      id = enqueued_id.to_s
+      return nil if id.empty? || !Dir.exist?(dir)
+
+      suffix = "-#{id}.txt"
+      Dir.children(dir).select { |f| f.end_with?(suffix) }.max
     end
 
     # The output files' text, oldest first; with +since_time+ only files
@@ -218,12 +246,40 @@ module Samagotchi
     end
 
     # Whether a mid-turn drain leaves this unclaimed input file for a turn
-    # of its own instead of merging it at a step boundary. Today that is an
-    # image message (steering merges text only); the drain's file filter
-    # reads this one predicate, so what a boundary refuses changes in one
-    # place.
+    # of its own instead of merging it at a step boundary: a queued message
+    # (`delivery: queue`) or an image message (steering merges text only).
+    # The drain skips such a file without stopping at it, so a later text
+    # line still merges; the drain's file filter reads this one predicate,
+    # so what a boundary leaves changes in one place.
     def self.waits_for_turn_end?(input_file)
-      input_has_images?(input_file)
+      data = JSON.parse(File.read(input_file))
+      data.is_a?(Hash) && (Array(data["images"]).any? || Delivery.queue?(data["delivery"]))
+    rescue JSON::ParserError, SystemCallError
+      false
+    end
+
+    # Whether an input file carrying +enqueued_id+ still waits unclaimed in
+    # input/ (no worker has taken it for a turn or a step yet).
+    def self.input_waiting?(session_dir, enqueued_id) = !waiting_input(session_dir, enqueued_id).nil?
+
+    # How the unclaimed input file carrying +enqueued_id+ waits: :turn_end
+    # (a queue or an image message: it runs as a turn of its own, never
+    # merged, #waits_for_turn_end?), :merges (a running turn's drain may
+    # take it as a steer), or nil when none waits.
+    # @return [Symbol, nil]
+    def self.waiting_input(session_dir, enqueued_id)
+      id = enqueued_id.to_s
+      return nil if id.empty?
+
+      find_new_input_files(session_dir).each do |file|
+        data = JSON.parse(File.read(file))
+        next unless data.is_a?(Hash) && data["enqueued_id"] == id
+
+        return Array(data["images"]).any? || Delivery.queue?(data["delivery"]) ? :turn_end : :merges
+      rescue JSON::ParserError, SystemCallError
+        next
+      end
+      nil
     end
 
     def self.claim_input_file(input_file)