samagotchi 0.92.0 → 0.94.0

data/lib/samagotchi/hook_routes.rb

@@ -31,14 +31,13 @@ module Samagotchi
     end
 
     # The things a hook can do beyond reading its event. Each gets the
-    # hook's label (event[:hook]) from the registry.
+    # hook's label (event[:hook]) from the registry; ask_user gets it inside
+    # the HookQuestion.
     # @return [Hooks::Runtime]
     def runtime
       Hooks::Runtime.new(
         notify: ->(text:, level:, hook:, fallback_for: nil) { notify(text, level, hook, fallback_for: fallback_for) },
-        ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:, effects: nil|
-          ask_user(question, options, header, allow_freeform, hook, effects: effects)
-        },
+        ask_user: ->(question) { ask_user(question) },
         stop_turn: ->(reason:, hook:) { stop_turn(reason, hook) },
         steer: ->(text:, hook:) { @steer.call(text, source(hook)) },
         stop_generation: ->(reason:, hook:) { stop_generation(reason, hook) }
@@ -87,9 +86,10 @@ module Samagotchi
     # web), single-select, kind "hook". A --non-interactive run has no one
     # to ask: nil at once. Anything but an answer (a sync handler's text, no
     # answer, cancelled) is nil too.
+    # @param question [HookQuestion]
     # @return [Hash, nil] {selected:, freeform:, selected_indices:}
-    def ask_user(question, options, header, allow_freeform, hook, effects: nil)
-      @question_desk.call.ask_for_hook(question, options, header, allow_freeform, hook, effects: effects)
+    def ask_user(question)
+      @question_desk.call.ask_for_hook(question)
     end
 
     # Cancel the running turn (reason :hook), after a notice that says why.

data/lib/samagotchi/hooks/registry.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "monitor"
+require_relative "../hook_question"
 require_relative "../log"
 
 module Samagotchi
@@ -113,8 +114,8 @@ module Samagotchi
     # callables, each given the hook's label. +notify+ takes
     # (text:, level:, hook:, and fallback_for: when the hook gave one: what
     # the line stands in for, HookRoutes#notify) and shows one line to the
-    # user; +ask_user+ takes (question:, options:, header:, allow_freeform:, hook:, and
-    # effects: when the hook gave them) and returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
+    # user; +ask_user+ takes a HookQuestion (the hook's label in it) and
+    # returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
     # cancels the running turn (true when it did); +steer+ takes (text:,
     # hook:) and puts the text into the running turn (Engine#steer, true
     # when queued); +stop_generation+ takes (reason:, hook:) and cuts the
@@ -392,9 +393,8 @@ module Samagotchi
           nil
         }
         event[:ask_user] ||= lambda { |question:, options:, header: nil, allow_freeform: false, effects: nil|
-          @runtime&.ask_user&.call(question: question, options: options, header: header,
-                                   allow_freeform: allow_freeform, hook: event[:hook],
-                                   **(effects.nil? ? {} : { effects: effects }))
+          @runtime&.ask_user&.call(HookQuestion.new(question: question, options: options, header: header,
+                                                    allow_freeform: allow_freeform, hook: event[:hook], effects: effects))
         }
         event[:stop_turn] ||= lambda { |reason|
           next false if TURN_OVER_EVENTS.include?(event[:type])

data/lib/samagotchi/host_registry.rb

@@ -68,7 +68,7 @@ module Samagotchi
       def api_base_url
         return openai_base_url unless api&.to_sym == :anthropic
 
-        (url || root_url).chomp("/").delete_suffix("/v1")
+        LLM::AnthropicMessages.api_root(url || root_url)
       end
 
       # The header the host's key goes in: auth: when set, else the api's

data/lib/samagotchi/llm/anthropic_messages.rb

@@ -87,6 +87,11 @@ module Samagotchi
 
       attr_reader :base_url, :host_name, :api_key_env, :models_ttl, :first_token_timeout, :dialect
 
+      # The Messages API root a base URL names: without a trailing / and a
+      # trailing /v1 (as ANTHROPIC_BASE_URL), so requests never go to
+      # /v1/v1. HostEntry#api_base_url and the bootstrap probe both use it.
+      def self.api_root(url) = url.to_s.chomp("/").delete_suffix("/v1")
+
       # @param entry [HostRegistry::HostEntry]
       def self.for(entry, **)
         new(base_url: entry.api_base_url, host_name: entry.name, api_key_env: entry.api_key_env, auth: entry.auth,

data/lib/samagotchi/memory_bundle/profile.rb

@@ -25,9 +25,14 @@ module Samagotchi
     # shipped meta expands: includes: in any other bundle is ignored.
     module Profile
       # installed: members installed now; already: members found installed
-      # (recorded, not reinstalled); skipped and failed: name => why.
-      InstallResult = Struct.new(:name, :version, :installed, :already, :skipped, :failed, keyword_init: true) do
+      # (recorded, not reinstalled); skipped and failed: name => why;
+      # kept_own: member installed now => its memory files the user already
+      # had, left as they are and not owned (Installer#skip_existing).
+      InstallResult = Struct.new(:name, :version, :installed, :already, :skipped, :failed, :kept_own, keyword_init: true) do
         def failed? = !failed.empty?
+
+        # One line per kept file (Profile.kept_own_line).
+        def kept_own_lines = (kept_own || {}).flat_map { |member, files| files.map { |file| Profile.kept_own_line(member, file) } }
       end
       # removed: members uninstalled; blocked: name => why; gone: the meta
       # itself was removed (only once every member is); trash: member =>
@@ -69,6 +74,15 @@ module Samagotchi
 
       def installed_names = Provenance.each_installed.map { |name, _| name }
 
+      # What a profile's install says of a member's memory file the user
+      # already had: chi bundle install says "Skipped … (already exists)",
+      # which a profile's member install would leave unsaid (docs/memory.md,
+      # "Shipped notes").
+      def kept_own_line(member, file)
+        "#{member}: kept your own #{file} (not the bundle's; to take the bundle's, remove yours with " \
+          "memory_write remove: true, then chi bundle install #{member})"
+      end
+
       # The one rule.
       def to_install(manifest, bundle = Provenance.new(name: manifest.name).record, installed: installed_names)
         manifest.includes - recorded(bundle, manifest) - installed
@@ -84,7 +98,7 @@ module Samagotchi
         was = recorded(bundle, manifest)
         installed = installed_names
         result = InstallResult.new(name: manifest.name, version: manifest.version, installed: [],
-                                   already: (manifest.includes - was) & installed, skipped: {}, failed: {})
+                                   already: (manifest.includes - was) & installed, skipped: {}, failed: {}, kept_own: {})
 
         to_install(manifest, bundle, installed: installed).each do |member|
           install_member(member, shipped_dir, chi_version, dry_run, force, result)
@@ -109,8 +123,12 @@ module Samagotchi
         return result.skipped[member] = failure if failure
         return result.installed << member if dry_run
 
-        Installer.new(source: member_dir, name: member, scope: "system", force: force, strict: true, shipped_dir: shipped_dir).run
+        installer = Installer.new(source: member_dir, name: member, scope: "system", force: force, strict: true,
+                                  shipped_dir: shipped_dir)
+        installer.run
         result.installed << member
+        kept = installer.results.select { |_, entry| entry[:status] == "skipped" && entry[:reason] == "already exists" }.keys
+        result.kept_own[member] = kept.sort unless kept.empty?
       rescue StandardError => e
         result.failed[member] = e.message.lines.first.to_s.strip
       end

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -37,7 +37,10 @@ module Samagotchi
       # :failed. note says why for skipped/failed. kept and replaced are
       # file names; under plan they are what apply would keep or replace.
       # adds is nil but for a profile: the members it installs.
-      Row = Struct.new(:name, :from, :to, :status, :note, :kept, :replaced, :source_dir, :scope, :adds, keyword_init: true)
+      # kept_own is nil but for a profile that installed a member: its
+      # Profile.kept_own_line lines.
+      Row = Struct.new(:name, :from, :to, :status, :note, :kept, :replaced, :source_dir, :scope, :adds, :kept_own,
+                       keyword_init: true)
 
       module_function
 
@@ -84,6 +87,7 @@ module Samagotchi
         result = Profile.install(row.source_dir, shipped_dir: File.dirname(row.source_dir))
         row.dup.tap do |r|
           r.adds = result.installed
+          r.kept_own = result.kept_own_lines
           r.status = result.failed? ? :failed : :updated
           r.note = result.failed.map { |member, why| "#{member}: #{why}" }.join("; ") if result.failed?
         end

data/lib/samagotchi/parent_answers_command.rb

@@ -25,10 +25,11 @@ module Samagotchi
       return [:show] if words.empty?
       return [:usage] if words.size > 1
 
-      word = words.first.downcase
-      return [:set, nil] if word == Guardrails::ParentPolicy::UNSET
-
-      Guardrails::ParentPolicy::ORDER.include?(word) ? [:set, word] : [:usage]
+      case (level = Guardrails::ParentPolicy.parse_level(words.first))
+      when :unset then [:set, nil]
+      when :invalid then [:usage]
+      else [:set, level]
+      end
     end
 
     # Whether the command line +line+ loosens a session whose own value is
@@ -72,8 +73,7 @@ module Samagotchi
       effective = Guardrails::ParentPolicy.for_session(session)
       own = session.parent_answers || "none"
       # A hand-edited value that isn't a level: fail-closed, said here.
-      own = "#{own} (unreadable value, read as hard)" if session.parent_answers &&
-                                                         !Guardrails::ParentPolicy::ORDER.include?(session.parent_answers)
+      own = "#{own} (unreadable value, read as hard)" if Guardrails::ParentPolicy.unknown_level?(session.parent_answers)
       "parent answers: #{effective.name} (this session: #{own}; config.yml #{config.label})"
     end
   end

data/lib/samagotchi/plugin/context.rb

@@ -5,6 +5,7 @@ require_relative "../log"
 require_relative "../paths"
 require_relative "../session_metrics/cost"
 require_relative "../guardrails/context"
+require_relative "../hook_question"
 require_relative "../idle_client"
 require_relative "service"
 require_relative "side_question"
@@ -28,8 +29,8 @@ module Samagotchi
 
     # The Engine's side of a Context: callables, so the Engine itself is
     # never handed out. +messages+ returns the conversation, +notify+ takes
-    # (text, level, label, fallback_for:), +ask_user+ takes (question:, options:, header:,
-    # allow_freeform:, hook:, and effects: when the plugin gave them) like the hook runtime's, +card+ takes
+    # (text, level, label, fallback_for:), +ask_user+ takes a HookQuestion
+    # (the plugin's label in it) like the hook runtime's, +card+ takes
     # Engine#show_card's keywords and returns the id, +ask_model+ takes
     # (chat messages, timeout:, max_tokens:, cancel_controller:, model:: a
     # configured model ref, nil for the session's) and returns the answer
@@ -363,13 +364,13 @@ module Samagotchi
       # @return [Hash, nil] {selected:, freeform:, selected_indices:}, or nil
       #   (no one to ask, cancelled, bad options or effects)
       def ask_user(question:, options:, header: nil, allow_freeform: false, effects: nil)
-        tags = effects.nil? ? {} : { effects: effects }
         if (helper = event_helper(:ask_user))
+          tags = effects.nil? ? {} : { effects: effects }
           return helper.call(question: question, options: options, header: header, allow_freeform: allow_freeform, **tags)
         end
 
-        @host.ask_user.call(question: question, options: options, header: header, allow_freeform: allow_freeform,
-                            hook: @label, **tags)
+        @host.ask_user.call(HookQuestion.new(question: question, options: options, header: header,
+                                             allow_freeform: allow_freeform, hook: @label, effects: effects))
       end
 
       # Whether the running turn was cancelled (a long tool should stop).

data/lib/samagotchi/plugin/http_transport.rb

@@ -12,8 +12,10 @@ module Samagotchi
     class Http
       # Plugin::Http's wire: one LLM::HTTP request per call (chi's TLS,
       # proxies, User-Agent, cancel by closing the socket, and one log line
-      # without query, headers or body), with chi's retries off. Every error
-      # but a cancel becomes an HttpError, so a plugin rescues one type.
+      # without query, headers or body), with chi's retries off. Every
+      # network, TLS, protocol or provider error but a cancel becomes an
+      # HttpError, so a plugin rescues one type; anything else is a bug in
+      # chi, logged with its backtrace and raised as it is.
       #
       # Loaded with the first real request (it pulls in net/http and the
       # LLM layer). Stateless.
@@ -29,6 +31,12 @@ module Samagotchi
           Net::ProtocolError => "protocol error", Zlib::Error => "bad compressed body"
         }.freeze
 
+        # The errors a request's wire may raise: each becomes an HttpError.
+        WIRE_ERRORS = [
+          *REASONS.keys, *LLM::HTTP::NETWORK_ERRORS, SystemCallError, IOError, OpenSSL::OpenSSLError,
+          LLM::ProviderError
+        ].uniq.freeze
+
         def initialize(bundle:)
           @bundle = bundle.to_s
         end
@@ -47,8 +55,11 @@ module Samagotchi
           raise HttpCancelled, "#{method} #{where(uri)}: cancelled"
         rescue HttpError
           raise
-        rescue StandardError => e
+        rescue *WIRE_ERRORS => e
           raise HttpError, "#{method} #{where(uri)}: #{reason(e)}"
+        rescue StandardError => e
+          Log.exception(:plugins, "http_transport_failed", e, bundle: @bundle)
+          raise
         end
 
         private

data/lib/samagotchi/plugin/sessions.rb

@@ -80,11 +80,10 @@ module Samagotchi
         sid = resolve(id, state_dir)
         delivered = SessionManager.deliver_turn(sid, prompt: text.to_s, client_id: ClientId::PLUGIN, state_dir: state_dir,
                                                      delivery: wire)
-        case delivered[:status]
+        case delivered.status
         when :accepted then sid
         when :refused
-          ack = delivered[:ack] || {}
-          raise Error, "session #{sid[0, 8]} refused the message (#{ack["error"]}#{": #{ack["detail"]}" if ack["detail"]})"
+          raise Error, "session #{sid[0, 8]} refused the message (#{delivered.error}#{": #{delivered.detail}" if delivered.detail})"
         when :timeout then raise Error, "session #{sid[0, 8]}'s worker did not answer in time; the message was not sent"
         else raise Error, "the message to session #{sid[0, 8]} could not be written"
         end

data/lib/samagotchi/question_desk.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "time"
 
 require_relative "client_id"
+require_relative "hook_question"
 require_relative "log"
 require_relative "pending_question"
 require_relative "question_answer"
@@ -404,30 +405,32 @@ module Samagotchi
     # web), single-select, kind "hook". A --non-interactive run has no one
     # to ask: nil at once. Anything but an answer (a sync handler's text, no
     # answer, cancelled) is nil too.
-    # @param effects [Hash, nil] label => effect for a parent agent's answer
-    #   (Guardrails::ParentPolicy); a label left out is "answer". A label
+    # @param asked [HookQuestion] its effects (label => effect for a parent
+    #   agent's answer, Guardrails::ParentPolicy; a label left out is
+    #   "answer") become the pending question's per-option tags. A label
     #   the options don't have, or an effect it doesn't know, makes the ask
     #   invalid (nil, warned), like bad options.
     # @return [Hash, nil] {selected:, freeform:, selected_indices:} (a plain
     #   Hash: the bundle boundary)
-    def ask_for_hook(question, options, header, allow_freeform, hook, effects: nil)
+    def ask_for_hook(asked)
       return nil if @interface_lookup.call == :non_interactive
 
-      opts = Tools::AskUserQuestion.normalize_options(options)
+      hook = asked.hook.to_s
+      opts = Tools::AskUserQuestion.normalize_options(asked.options)
       unless opts
-        Log.warn(:hooks, "ask_user_invalid", echo: "[samagotchi:hooks] #{hook} asked with invalid options (2-8 strings)", hook: hook.to_s)
+        Log.warn(:hooks, "ask_user_invalid", echo: "[samagotchi:hooks] #{hook} asked with invalid options (2-8 strings)", hook: hook)
         return nil
       end
-      tags = Guardrails::ParentPolicy.option_tags(opts, effects)
+      tags = Guardrails::ParentPolicy.option_tags(opts, asked.effects)
       if tags == false
         Log.warn(:hooks, "ask_user_invalid",
                  echo: "[samagotchi:hooks] #{hook} asked with invalid effects (option label => " \
-                       "#{Guardrails::ParentPolicy::EFFECTS.join("|")})", hook: hook.to_s)
+                       "#{Guardrails::ParentPolicy::EFFECTS.join("|")})", hook: hook)
         return nil
       end
 
-      fields = { question: question.to_s, options: opts, header: header, multi_select: false,
-                 allow_freeform: !!allow_freeform, effects: tags, kind: "hook", hook: hook.to_s }.compact
+      fields = { question: asked.question.to_s, options: opts, header: asked.header, multi_select: false,
+                 allow_freeform: !!asked.allow_freeform, effects: tags, kind: "hook", hook: hook }.compact
       answer = open_question(fields)
       return nil unless answer.is_a?(QuestionAnswer)
 

data/lib/samagotchi/reply_wait/poll.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../session_inbox"
+require_relative "../turn_checkpoint"
+
+module Samagotchi
+  module ReplyWait
+    # One ReplyWait.call: what the wait learned so far (the turn's input
+    # claimed, its turn seen running, any turn seen running, the worker
+    # gone since) and one look at the session per poll. Each check returns
+    # a Result that ends the wait, or nil to go on, in the order #look runs
+    # them. ReplyWait.call's parameters say what each means.
+    class Poll
+      def initialize(id, state_dir:, cursor:, timeout:, poll_interval:, cancelled:, baseline:, owner_grace:, interject:,
+                     turn:, queued:, ended_before:)
+        @id = id
+        @state_dir = state_dir
+        @cursor = cursor
+        @poll_interval = poll_interval
+        @cancelled = cancelled
+        @baseline = baseline
+        @owner_grace = owner_grace
+        @interject = interject
+        @ended_before = ended_before
+        @deadline = timeout && (ReplyWait.monotonic + timeout.to_f)
+        @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
+        @seen_running = false
+        @gone_since = nil
+      end
+
+      # @return [Result]
+      def run
+        loop do
+          result = look
+          return result if result
+
+          if @interject
+            started = ReplyWait.monotonic
+            @interject.call
+            @deadline += ReplyWait.monotonic - started if @deadline
+            next if @cancelled.call
+          end
+          sleep(@poll_interval)
+        end
+      end
+
+      private
+
+      # One poll: the input file, then the session as loaded now.
+      # @return [Result, nil]
+      def look
+        look_at_input
+        session = Session.load(@id, state_dir: @state_dir)
+        if (result = removed(session))
+          return result
+        end
+
+        note_own_running(session)
+        follow_merge(session)
+        reply(session) || settled_turn(session) || status_end(session) || question(session) || canceled ||
+          ended_before_reply(session) || ended_before_turn(session) || turn_end(session) || owner_gone(session) ||
+          timed_out
+      end
+
+      def look_at_input
+        return unless @turn && !@claimed
+
+        waiting = SessionInbox.waiting_input(@session_dir, @turn)
+        @own_turn_input ||= waiting == :turn_end
+        @claimed = waiting.nil?
+      end
+
+      # Taken back before it ran (POST turn/dequeue): no turn will come. A
+      # tombstone with the claimed file still there is a removal not done
+      # yet (or one a turn's claim beat): looked at again next poll. One
+      # whose turn ran anyway (its reply, or last_turn its own) is a stray:
+      # a worker killed between the tombstone and the claim left it, or a
+      # short turn won the claim and ended before the removal took it back.
+      def removed(session)
+        return nil unless @turn && @claimed && !@seen_own && SessionInbox.removed?(@session_dir, @turn)
+        return nil if SessionInbox.claimed_input?(@session_dir, @turn) || turn_ran?(session)
+
+        Result.new(status: :no_reply, outcome: "removed", session: session)
+      end
+
+      def turn_ran?(session)
+        session.last_turn&.enqueued_id == @turn || !SessionInbox.reply_for(@session_dir, @turn).nil?
+      end
+
+      def note_own_running(session)
+        return unless @turn && !@seen_own && own_running?(session)
+
+        @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.
+      def follow_merge(session)
+        return unless @turn && @claimed && !@seen_own && !@own_turn_input &&
+                      ReplyWait.merged_elsewhere?(session, @turn, @baseline, @session_dir)
+
+        @turn = nil
+        @seen_running = running?(session)
+      end
+
+      def reply(session)
+        reply = if @turn
+                  ReplyWait.reply_for_turn(@id, state_dir: @state_dir, turn: @turn)
+                else
+                  ReplyWait.reply_past(@id, state_dir: @state_dir, cursor: @cursor)
+                end
+        return nil unless reply
+
+        reply.session = ReplyWait.settled(session, @id, state_dir: @state_dir)
+        reply
+      end
+
+      # Its worker died in it and the next one settled it, or an input
+      # command finished without a turn. After the reply check: a worker
+      # killed between writing the reply and its idle save left the reply.
+      def settled_turn(session)
+        settled = @turn && TurnCheckpoint.settled_turn(@session_dir, @turn)
+        return nil unless settled
+
+        Result.new(status: :no_reply, outcome: settled.outcome, session: session, origin: settled.origin,
+                   **settled.stop_facts)
+      end
+
+      def status_end(session)
+        case session.status
+        when Session::STATUS_ERROR then Result.new(status: :error, text: session.last_prompt.to_s.strip, session: session)
+        when Session::STATUS_STOPPED then Result.new(status: :stopped, session: session)
+        end
+      end
+
+      # Only a question a live worker holds waits for an answer (the lists'
+      # rule): one a dead worker left waits for no one, and a chi REPL's is
+      # answered there.
+      def question(session)
+        pending = session.pending_question
+        return nil unless pending && !@baseline&.question?(pending.id) &&
+                          (@turn.nil? || ReplyWait.own_question?(session, @turn, @claimed)) &&
+                          session.waiting_question(live: SessionManager.worker_live?(@id, state_dir: @state_dir))
+
+        Result.new(status: :waiting_for_answer, question: pending, session: session)
+      end
+
+      def canceled = @cancelled.call ? Result.new(status: :canceled) : nil
+
+      # 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.
+      def ended_before_reply(session)
+        return nil unless @ended_before && @turn.nil? && session.status == Session::STATUS_IDLE && baseline_end?(session)
+
+        file = ReplyWait.newest_reply(@id, state_dir: @state_dir)
+        path = File.join(ReplyWait.reply_dir(@id, state_dir: @state_dir), file) if file
+        if file && ReplyWait.reply_is_turns?(path, session.last_turn.ended_at)
+          reply = Result.new(status: :done, text: File.read(path), file: file)
+          reply.session = ReplyWait.settled(session, @id, state_dir: @state_dir)
+          return reply
+        end
+
+        ReplyWait.no_reply(session, @baseline, fresh: true)
+      end
+
+      # The same for a turn: wait whose turn is that last one (not running
+      # again). The turn's own reply lookup (#reply) already found its file,
+      # if one exists; without it the newest file is no fallback: it could
+      # be another turn's.
+      def ended_before_turn(session)
+        return nil unless @ended_before && @turn && session.last_turn&.enqueued_id == @turn && !own_running?(session) &&
+                          baseline_end?(session)
+
+        ReplyWait.no_reply(session, @baseline, fresh: true)
+      end
+
+      def turn_end(session)
+        return own_turn_end(session) if @turn
+
+        if running?(session)
+          @seen_running = true
+          return nil
+        end
+        # 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 message its worker has not picked up yet. With a
+        # baseline only a turn that ended since counts: a session left
+        # running by a worker that died goes idle when the next worker
+        # settles that turn (TurnCheckpoint.settle), before the sent
+        # message's turn runs.
+        return nil unless (@seen_running && @baseline.nil?) || ReplyWait.turn_ended_since?(session, @baseline)
+
+        # The worker writes the reply before its idle save, so the read
+        # above has it; one more look costs nothing should that change.
+        ReplyWait.reply_past(@id, state_dir: @state_dir, cursor: @cursor)&.tap { |r| r.session = session } ||
+          ReplyWait.no_reply(session, @baseline)
+      end
+
+      # 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.
+      def own_turn_end(session)
+        if session.last_turn&.enqueued_id == @turn && ReplyWait.ended_since_baseline?(session, @baseline)
+          return ReplyWait.reply_for_turn(@id, state_dir: @state_dir, turn: @turn)&.tap { |r| r.session = session } ||
+                 ReplyWait.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 && ReplyWait.past_own?(session, @turn, @own_base)
+
+        nil
+      end
+
+      def owner_gone(session)
+        return nil unless @owner_grace
+
+        if SessionManager.session_owner(@id, state_dir: @state_dir)
+          @gone_since = nil
+        elsif ReplyWait.monotonic - (@gone_since ||= ReplyWait.monotonic) > @owner_grace
+          return Result.new(status: :worker_gone, session: session)
+        end
+        nil
+      end
+
+      def timed_out = @deadline && ReplyWait.monotonic > @deadline ? Result.new(status: :timeout) : nil
+
+      # Whether the session's last turn is the one that had ended at the
+      # baseline (its ended_at set and unchanged).
+      def baseline_end?(session)
+        ended = session.last_turn&.ended_at
+        (!ended.to_s.empty? && @baseline&.ended_at?(ended)) || false
+      end
+
+      def running?(session) = session.status == Session::STATUS_RUNNING
+
+      def own_running?(session) = running?(session) && session.interrupted_turn&.enqueued_id == @turn
+    end
+  end
+end