samagotchi 0.80.0 → 0.82.0

data/lib/samagotchi/idle_client.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "llm/adapters"
 require_relative "log"
+require_relative "side_usage"
 
 module Samagotchi
   # Standalone summarizer for the idle session-recap feature.
@@ -54,9 +55,12 @@ module Samagotchi
     # @param api [Symbol] the wire to talk (LLM::Adapters; IdleTarget#api)
     # @param auth [Symbol, nil] the header the key goes in (IdleTarget#auth)
     # @param dialect [String, nil] a Messages host's dialect (IdleTarget#dialect)
+    # @param price [ModelPrice, nil] the model's price on its host
+    #   (IdleTarget#price), on each SideUsage the on_usage callbacks get
     def initialize(model:, base_url: nil, api_key_env: nil, timeout: DEFAULT_TIMEOUT_SECONDS, env: ENV, purpose: "recap",
-                   api: :openai, auth: nil, dialect: nil)
+                   api: :openai, auth: nil, dialect: nil, price: nil)
       @model = model
+      @price = price
       # A recap is best-effort: one short attempt, no retries. The idle job
       # tries again after the next activity, never on its own. Only the
       # Messages adapter takes a dialect.
@@ -70,7 +74,7 @@ module Samagotchi
     # @return [IdleClient]
     def self.for(target, **)
       new(model: target.model, base_url: target.base_url, api_key_env: target.api_key_env, api: target.api,
-          auth: target.auth, dialect: target.dialect, **)
+          auth: target.auth, dialect: target.dialect, price: target.price, **)
     end
 
     THINK_RE = /<\|think\|.*?\|think\|>/m
@@ -100,11 +104,13 @@ module Samagotchi
     # @return [Summary, nil]
     # +session_id+: the session it is about, sent as the turns send it
     # (Session-Id, a dialect's affinity header), nil for none.
-    def summarize(prompt, session_id: nil)
+    # +on_usage+: called with the request's SideUsage (kind "recap") once a
+    # reply came back, see #ask.
+    def summarize(prompt, session_id: nil, on_usage: nil)
       messages = prompt.is_a?(Array) ? prompt : [{ role: "user", content: prompt.to_s.strip }]
       return nil if messages.all? { |m| m[:content].to_s.strip.empty? }
 
-      response = generate(messages, session_id: session_id)
+      response = generate(messages, session_id: session_id, on_usage: on_usage)
       cleaned = response.text.to_s.strip
       cleaned.empty? ? nil : Summary.new(text: cleaned, model: response.model)
     rescue SummarizeError
@@ -121,14 +127,18 @@ module Samagotchi
     # @param options [Hash] more request body fields (logprobs: true,
     #   top_logprobs: 5)
     # @param session_id [String, nil] the session it is about (#summarize)
+    # @param on_usage [#call, nil] called with the request's SideUsage
+    #   (+kind+, the counts, the reported cost, the client's price) once a
+    #   reply came back, a billed one with no usable text too; never for a
+    #   request that got no reply. Its errors are logged, never raised.
     # @return [Summary] the answer ("" when the model said nothing)
     # @raise [SummarizeError] any failure but a cancel; its #cause is an
     #   LLM::BadRequest when the host refused the request (+options+ it
     #   doesn't take, say)
     # @raise [LLM::RequestCancelled] +cancel_controller+ was cancelled
-    def ask(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, kind: "ask", options: {}, session_id: nil)
+    def ask(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, kind: "ask", options: {}, session_id: nil, on_usage: nil)
       response = generate(messages, max_tokens: max_tokens, cancel_controller: cancel_controller, whole_sentences: false,
-                                    kind: kind, options: options, session_id: session_id)
+                                    kind: kind, options: options, session_id: session_id, on_usage: on_usage)
       Summary.new(text: response.text.to_s.strip, model: response.model, top_logprobs: response.top_logprobs)
     rescue SummarizeError, LLM::RequestCancelled
       raise
@@ -146,7 +156,7 @@ module Samagotchi
     # +max_tokens+, the text keeps its finished sentences (+whole_sentences+)
     # or all of it, with "…".
     def generate(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, whole_sentences: true, kind: "recap", options: {},
-                 session_id: nil)
+                 session_id: nil, on_usage: nil)
       response = begin
         request(messages, max_tokens, cancel_controller, options, session_id)
       rescue LLM::BadRequest => e
@@ -156,6 +166,7 @@ module Samagotchi
         retry
       end
       log_usage(response, kind)
+      report_usage(on_usage, response, kind)
       content = response.text
       reasoning = response.reasoning
       raise SummarizeError, "server returned no parseable assistant content" if content.empty? && reasoning.empty?
@@ -176,14 +187,28 @@ module Samagotchi
       raise SummarizeError, "server returned no parseable assistant content (#{e.message})"
     end
 
-    # The request's prompt-cache counts (a side request on the session's
-    # host can evict the session's cached prompt there).
+    # Log reported request usage when cache counts are present; session
+    # side-usage counting is handled separately by #report_usage.
     def log_usage(response, kind)
-      fields = response.usage&.cache_fields || {}
+      usage = response.usage
+      fields = usage&.cache_fields || {}
       return if fields.empty?
 
       Log.info(:recap, "request_usage", kind: kind, model: @model, prompt: fields[:prompt_tokens],
-                                        cached: fields[:cached_tokens], cache_write: fields[:cache_write_tokens])
+                                        cached: fields[:cached_tokens], cache_write: fields[:cache_write_tokens],
+                                        # A cost as written: Log rounds Floats to 3 places.
+                                        completion: usage.completion_tokens, cost: usage.cost&.to_s)
+    end
+
+    # The request's SideUsage to +on_usage+ (a session counts it in its side
+    # line); a reply without counts is one request with zero tokens.
+    # Counting never fails the side answer: a callback's error is logged.
+    def report_usage(on_usage, response, kind)
+      return unless on_usage
+
+      on_usage.call(SideUsage.from_usage(response.usage, kind: kind, model: @model, price: @price))
+    rescue StandardError => e
+      Log.warn(:recap, "usage_callback_failed", kind: kind, model: @model, error: "#{e.class}: #{e.message}")
     end
 
     # After a host refused this step's thinking fields: the next step, kept

data/lib/samagotchi/idle_recap.rb

@@ -288,12 +288,17 @@ module Samagotchi
                    client: nil,
                    store: nil,
                    session_id: -> {},
+                   on_usage: nil,
                    clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       raise ArgumentError, "IdleRecap requires an engine" unless engine
 
       @engine = engine
       # The recapped session's id, sent with the request (IdleClient#summarize).
       @session_id = session_id
+      # Called with each recap request's SideUsage (IdleClient#summarize),
+      # a dropped recap's too: it was billed (RecapSetup: the Engine's
+      # side line).
+      @on_usage = on_usage
       @target = target || lambda {
         IdleTarget.new(base_url: base_url, api_key_env: api_key_env, model: model, label: model)
       }
@@ -547,7 +552,7 @@ module Samagotchi
 
     def spawn_summarize(client, prompt)
       Thread.new do
-        client.summarize(prompt, session_id: @session_id.call)
+        client.summarize(prompt, session_id: @session_id.call, on_usage: @on_usage)
       rescue StandardError => e
         # No recap this time (the next idle window tries again); say why.
         Log.exception(:recap, "summarize_failed", e)

data/lib/samagotchi/idle_target.rb

@@ -14,8 +14,14 @@ module Samagotchi
   #   auth:, LLM::ApiKey::SCHEMES); nil: the api's own default
   # @!attribute dialect [String, nil] an api: anthropic host's dialect:
   #   (LLM::Dialect), so a side request gets its auth and fields
-  IdleTarget = Data.define(:base_url, :api_key_env, :model, :label, :api, :auth, :dialect) do
-    def initialize(api: :openai, auth: nil, dialect: nil, **) = super
+  # @!attribute price [ModelPrice, nil] the host's models: price for the
+  #   id asked for (as EffectiveModel#price), what a side request's cost is
+  #   estimated from; nil for none, and for a bare base_url target
+  IdleTarget = Data.define(:base_url, :api_key_env, :model, :label, :api, :auth, :dialect, :price) do
+    def initialize(api: :openai, auth: nil, dialect: nil, price: nil, **) = super
+
+    # +entry+'s models: price for +id+ (the id asked for, case-insensitively).
+    def self.price_of(entry, id) = entry.models&.dig(id.to_s.strip.downcase)&.price
 
     # The api a side request to +entry+ talks: a chat host's own, else the
     # OpenAI API (a raw host's llama.cpp serves /v1 too).
@@ -49,7 +55,8 @@ module Samagotchi
       resolved = host_registry.resolve(name)
       entry = resolved.entry
       new(base_url: entry.api_base_url, api_key_env: entry.api_key_env, model: resolved.bare_model,
-          label: name.to_s.strip, api: api_of(entry), auth: entry.auth, dialect: dialect_of(entry))
+          label: name.to_s.strip, api: api_of(entry), auth: entry.auth, dialect: dialect_of(entry),
+          price: price_of(entry, resolved.bare_model))
     end
 
     # A side model's settings (recap.*, broadcast.triage_*) as a target:
@@ -74,6 +81,7 @@ module Samagotchi
       api = :openai
       auth = nil
       dialect = nil
+      entry = nil
       if host_ref
         entry = host_registry.find_entry(host_ref)
         raise self::Unresolved.new(:host_ref_unknown, model: model, host_ref: host_ref) unless entry
@@ -95,7 +103,7 @@ module Samagotchi
       raise self::Unresolved.new(:incomplete, model: model, host_ref: host_ref) if blank(base_url).nil? || blank(model).nil?
 
       new(base_url: base_url.to_s.strip, api_key_env: api_key_env, model: model.to_s.strip, label: label.strip, api: api, auth: auth,
-          dialect: dialect)
+          dialect: dialect, price: entry && price_of(entry, model))
     end
 
     # Whether the settings fix a host (+base_url+, +host_ref+, or a model

data/lib/samagotchi/llm/http.rb

@@ -390,7 +390,7 @@ module Samagotchi
                 end
         Log.public_send(failure_level, :http, event, **log_base(current), status: e.is_a?(ProviderError) ? e.status : nil,
                                                      ms: elapsed_ms(current), attempts: current[:attempts], error: e.class.name,
-                                                     msg: (e.respond_to?(:summary) ? e.summary : e.message).to_s[0, 300])
+                                                     msg: log_message(e.respond_to?(:summary) ? e.summary : e.message))
         raise
       end
 
@@ -410,13 +410,18 @@ module Samagotchi
       def retry_after(error, attempts, delay, on_retry, cancel_controller, current)
         Log.warn(:http, "retry", **log_base(current), attempt: attempts, max_retries: @retry_policy.max, delay_s: delay,
                                  status: error.is_a?(ProviderError) ? error.status : nil, error: error.class.name,
-                                 msg: error.message.to_s[0, 300])
+                                 msg: log_message(error.message))
         on_retry&.call(attempt: attempts, max_retries: @retry_policy.max, next_delay: delay,
                        error_class: error.class.name, error_message: error.message,
                        status: error.is_a?(ProviderError) ? error.status : nil)
         wait(delay, cancel_controller)
       end
 
+      def log_message(value)
+        value.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+          .gsub(/[[:cntrl:]\u2028\u2029]+/, " ").split.join(" ")[0, 300]
+      end
+
       def check_status!(response)
         status = response.code.to_i
         return if status.between?(200, 299)

data/lib/samagotchi/llm/usage.rb

@@ -8,7 +8,11 @@ module Samagotchi
     # (:server), else zeros (:none). +cached_tokens+ is the prompt the server
     # reused from its cache, +cache_write_tokens+ what it wrote to it
     # (OpenRouter reports those for Anthropic models); 0 when not reported.
-    Usage = Data.define(:prompt_tokens, :completion_tokens, :source, :cached_tokens, :cache_write_tokens) do
+    # +reasoning_tokens+ is the completion's reasoning part (0 when not
+    # reported), +cost+ the provider's reported cost in USD (OpenRouter's
+    # usage.cost; nil when not reported, a reported 0 stays 0).
+    Usage = Data.define(:prompt_tokens, :completion_tokens, :source, :cached_tokens, :cache_write_tokens,
+                        :reasoning_tokens, :cost) do
       # @return [Usage, nil] nil when the payload carries no counts
       def self.from_payload(payload)
         counts = TokenUsage.from_payload(payload)
@@ -16,12 +20,14 @@ module Samagotchi
 
         new(prompt_tokens: counts.prompt_tokens.to_i, completion_tokens: counts.completion_tokens.to_i,
             source: :server, cached_tokens: counts.cached_tokens.to_i,
-            cache_write_tokens: counts.cache_write_tokens.to_i)
+            cache_write_tokens: counts.cache_write_tokens.to_i, reasoning_tokens: counts.reasoning_tokens.to_i,
+            cost: counts.cost)
       end
 
       def self.none = new(prompt_tokens: 0, completion_tokens: 0, source: :none)
 
-      def initialize(prompt_tokens:, completion_tokens:, source:, cached_tokens: 0, cache_write_tokens: 0)
+      def initialize(prompt_tokens:, completion_tokens:, source:, cached_tokens: 0, cache_write_tokens: 0,
+                     reasoning_tokens: 0, cost: nil)
         super
       end
 

data/lib/samagotchi/model_price.rb

@@ -34,6 +34,22 @@ module Samagotchi
     end
     private_class_method :warn_once
 
+    # The cost rule, one place for a turn's generation (SessionMetrics) and
+    # a side request (SessionMetrics::SideTotals): a reported cost wins; a
+    # reported 0, or none, with a price is estimated from the price (a
+    # gateway that doesn't bill per call reports 0). The reported cost
+    # itself is summed apart, a 0 included.
+    # @param price [ModelPrice, nil]
+    # @param reported_cost [Numeric, nil] the provider's cost (usage.cost)
+    # @return [Float, nil] the estimate, nil when none applies (no price, or
+    #   a positive reported cost), so a sum without one stays as it was
+    def self.estimate(price, reported_cost:, prompt_tokens:, cached_tokens:, cache_write_tokens:, completion_tokens:)
+      return nil unless price && (reported_cost.nil? || reported_cost.zero?)
+
+      price.cost(prompt_tokens: prompt_tokens, cached_tokens: cached_tokens, cache_write_tokens: cache_write_tokens,
+                 completion_tokens: completion_tokens)
+    end
+
     # USD for one generation, OpenAI usage semantics: +prompt_tokens+ holds
     # the cached reads and the cache writes (OpenRouter keeps that for
     # Anthropic models), and reasoning is inside +completion_tokens+.

data/lib/samagotchi/parent_report.rb

@@ -76,6 +76,7 @@ module Samagotchi
     # @return [Hash] the --format json object
     def json(result, session_id:, timeout: nil, extra: {})
       report = { status: status(result), session_id: session_id }
+      report[:turn_id] = result.turn_id unless result.turn_id.to_s.empty?
       case report[:status]
       when "answered" then report[:text] = result.text.to_s
       when "question"
@@ -122,7 +123,7 @@ module Samagotchi
         text = if result.status == :waiting_for_answer
                  question_text(result.question, session_id: session_id)
                else
-                 "#{detail(result, session_id: session_id, timeout: timeout)}\n"
+                 "#{detail(result, session_id: session_id, timeout: timeout, turn_id: result.turn_id)}\n"
                end
         stderr.print("#{command}: #{text}")
       end
@@ -200,7 +201,7 @@ module Samagotchi
     end
 
     # What a wait that ended without an answer says, one line.
-    def detail(result, session_id:, timeout: nil)
+    def detail(result, session_id:, timeout: nil, turn_id: nil)
       attach = "chi --attach #{session_id}"
       case result.status
       when :waiting_for_answer
@@ -217,7 +218,10 @@ module Samagotchi
       when :error then "the worker failed: #{result.text}; #{attach} shows what happened"
       when :worker_gone then "the worker is gone; #{attach} shows what happened"
       when :stopped then "the session was stopped (chi sessions stop)"
-      else timeout ? "still running after #{format("%g", timeout)} s: #{attach}" : "still running: #{attach}"
+      else
+        wait_again = "chi send --wait --turn #{turn_id} #{session_id}" unless turn_id.to_s.empty?
+        hint = wait_again || attach
+        timeout ? "still running after #{format("%g", timeout)} s: #{hint}" : "still running: #{hint}"
       end
     end
 

data/lib/samagotchi/plugin/context.rb

@@ -5,6 +5,7 @@ require_relative "../log"
 require_relative "../paths"
 require_relative "../guardrails/context"
 require_relative "../idle_client"
+require_relative "service"
 require_relative "side_question"
 
 module Samagotchi
@@ -76,7 +77,7 @@ module Samagotchi
     # handler started) they act on the session now, through the Host.
     class Context
       # Thread.current key: {Context => the event its handler runs for}.
-      CURRENT_EVENTS = :samagotchi_plugin_current_events
+      CURRENT_EVENTS = Service::CURRENT_EVENTS
       # Debug-log records tagged plugins, with bundle=<bundle> (tags are a
       # closed list, LogLine::TAGS).
       class Logger
@@ -294,7 +295,7 @@ module Samagotchi
         request = SideQuestion.request(messages: messages, prompt: prompt, system: system)
         limit = max_tokens.nil? ? ASK_MAX_TOKENS : Integer(max_tokens)
         @host.ask_model.call(request, timeout: Float(timeout), max_tokens: limit, cancel_controller: cancel,
-                                      model: model&.strip).to_s
+                                      model: model&.strip, source: @bundle).to_s
       rescue IdleClient::SummarizeError => e
         raise ModelError, e.message
       rescue LLM::RequestCancelled
@@ -318,7 +319,7 @@ module Samagotchi
       # @return [Http]
       def http
         @http ||= Http.new(bundle: @bundle, transport: @http_transport,
-                           cancel_lookup: -> { @host.cancel_controller&.call(handler: in_handler?) })
+                           cancel_lookup: -> { http_cancel_controller })
       end
 
       # This session's attached context: attach a URL or a command, list
@@ -387,6 +388,12 @@ module Samagotchi
       # Whether this plugin's handler runs on this thread (#with_event).
       def in_handler? = !!Thread.current[CURRENT_EVENTS]&.key?(self)
 
+      # The controller a ctx.http call without cancel: stops with: nil inside
+      # a service's start block, even on the turn's thread.
+      def http_cancel_controller
+        Service.starting? ? nil : @host.cancel_controller&.call(handler: in_handler?)
+      end
+
       # The event[:x] helper of the event this plugin's handler runs for on
       # this thread, or nil (not in a handler).
       def event_helper(name)

data/lib/samagotchi/plugin/service.rb

@@ -15,6 +15,16 @@ module Samagotchi
       # again.
       class Stopped < StandardError; end
 
+      # The thread-local Context#with_event keeps its handler events in;
+      # the start block runs with it cleared.
+      CURRENT_EVENTS = :samagotchi_plugin_current_events
+      # Thread.current key: true while a start block runs (the turn's own
+      # thread too: a ctx.http call there isn't the turn's).
+      STARTING = :samagotchi_plugin_service_starting
+
+      # Whether a service's start block runs on this thread.
+      def self.starting? = !!Thread.current[STARTING]
+
       # @return [String] "<bundle>:<name>"
       attr_reader :name
 
@@ -37,7 +47,7 @@ module Samagotchi
           return @value if @state == :running
 
           begin
-            @value = @start.call(self)
+            @value = start_outside_handler
             @state = :running
             Log.info(:plugins, "service_started", service: @name)
             @value
@@ -81,6 +91,19 @@ module Samagotchi
 
       private
 
+      # The start block is the service's, not the handler's whose first
+      # #value started it: no event helper or ctx.http turn cancel inside.
+      def start_outside_handler
+        events = Thread.current[CURRENT_EVENTS]
+        starting = Thread.current[STARTING]
+        Thread.current[CURRENT_EVENTS] = nil
+        Thread.current[STARTING] = true
+        @start.call(self)
+      ensure
+        Thread.current[CURRENT_EVENTS] = events
+        Thread.current[STARTING] = starting
+      end
+
       def run_on_stop
         callbacks = @on_stop.reverse
         @on_stop = []

data/lib/samagotchi/recap_setup.rb

@@ -66,7 +66,8 @@ module Samagotchi
         timeout: recap_number_setting(kwarg_config, :timeout, "recap.timeout", IdleRecap::DEFAULT_TIMEOUT_SECONDS, :float),
         sentences: recap_sentences(string_config(kwarg_config, :sentences) || registry_string("recap.sentences")),
         store: RecapStore.new(session_id_lookup: -> { session_id.call }, state_dir_lookup: -> { state_dir.call }),
-        session_id: -> { session_id.call }
+        session_id: -> { session_id.call },
+        on_usage: ->(usage) { engine.note_side_usage(usage) }
       )
     end
 

data/lib/samagotchi/reply_wait.rb

@@ -52,8 +52,10 @@ module Samagotchi
     # @!attribute session [Session, nil] the session as the look that
     #   decided the outcome loaded it (a caller's next baseline); nil for
     #   :canceled and :timeout
+    # @!attribute turn_id [String, nil] the id of the turn this result is
+    #   about, when known
     Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, :error_kind, :retryable, :cancel_reason,
-                        :stopped_by, :kept_steps, :session, keyword_init: true)
+                        :stopped_by, :kept_steps, :session, :turn_id, keyword_init: true)
 
     module_function
 
@@ -94,10 +96,18 @@ module Samagotchi
     # @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
+    # @param ended_before [Boolean] a last_turn that ended before the
+    #   baseline (chi send --wait with no message, on a session that went
+    #   idle in the gap between waits) is the turn's end too: with the
+    #   session idle and its last_turn still the baseline's, its end is
+    #   the answer — its reply, or its no-reply outcome. Its reply file
+    #   sorts at the cursor, not past it, and its end precedes the
+    #   baseline, so without it the wait would time out "running" again.
+    #   Not for a turn: wait (chi answer) whose own end it waits for.
     # @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, turn: nil, queued: false)
+             baseline: nil, owner_grace: nil, interject: nil, turn: nil, queued: false, ended_before: false)
       deadline = timeout && (monotonic + timeout.to_f)
       seen_running = false
       gone_since = nil
@@ -159,6 +169,34 @@ module Samagotchi
 
         return Result.new(status: :canceled) if cancelled.call
 
+        # The turn that ended before this wait (ended_before: chi send
+        # --wait with no message, on a session that went idle in the gap
+        # between waits): its last_turn still stands, the session is idle,
+        # so its end is the answer, not a wait that times out "running"
+        # again. Its reply file sorts at the cursor (the newest), not past
+        # it: it is the turn's when it is at least as new as the turn's
+        # end (the worker writes it after recording the ended_at), else the
+        # turn left no reply and an earlier turn's file is not its.
+        if ended_before && turn.nil? && session.status == Session::STATUS_IDLE &&
+           (ended = session.last_turn&.ended_at) && !ended.to_s.empty? &&
+           baseline && ended == baseline[:last_turn]
+          file = newest_reply(id, state_dir: state_dir)
+          if file && reply_is_turns?(file, ended)
+            reply = Result.new(status: :done, text: File.read(File.join(reply_dir(id, state_dir: state_dir), file)), file: file)
+            reply.session = settled(session, id, state_dir: state_dir)
+            return reply
+          end
+
+          return no_reply(session, baseline, fresh: true)
+        end
+
+        if ended_before && turn && session.last_turn&.enqueued_id == turn &&
+           !(session.status == Session::STATUS_RUNNING && session.interrupted_turn&.enqueued_id == turn) &&
+           (ended = session.last_turn&.ended_at) && !ended.to_s.empty? &&
+           baseline && ended == baseline[:last_turn]
+          return no_reply(session, baseline, fresh: true)
+        end
+
         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
@@ -257,6 +295,18 @@ module Samagotchi
       session.last_turn&.enqueued_id
     end
 
+    # Whether +turn+ is a turn the caller can wait for: running now, queued
+    # as its own turn, or the last one to have ended.
+    def known_turn?(session, session_dir:, turn:)
+      id = turn.to_s
+      return false if id.empty?
+
+      running = session.status == Session::STATUS_RUNNING && session.interrupted_turn&.enqueued_id == id
+      queued = SessionInbox.waiting_input(session_dir, id) == :turn_end
+      ended = session.last_turn&.enqueued_id == id
+      running || queued || ended
+    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
@@ -390,6 +440,22 @@ module Samagotchi
       cursor.nil? || file > cursor
     end
 
+    # Whether the reply file +file+ is the turn that ended at +ended_at+'s,
+    # not an earlier turn's: the worker records the ended_at, then writes
+    # the reply (SessionInbox.write_output: the name's timestamp is the
+    # write time, at least the ended_at); every earlier turn's file is
+    # older than the turn's end. The wait and the session run on one
+    # machine, so the name's local-time read is the writer's. A name that
+    # doesn't read as a time isn't the turn's.
+    def reply_is_turns?(file, ended_at)
+      name = file.to_s
+      return false if name.length < 23
+
+      Time.parse(ended_at.to_s) <= Time.strptime(name[0, 14], "%Y%m%d%H%M%S") + (name[14, 9].to_f / (10**9))
+    rescue ArgumentError
+      false
+    end
+
     def monotonic
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end