samagotchi 0.154.0 → 0.155.0

data/lib/samagotchi/engine/objectives.rb

@@ -2,30 +2,15 @@
 
 module Samagotchi
   class Engine
-    # The session's objectives: their view announced when it changed, Check
-    # this's side request, the model's proposals kept as cards until the turn
-    # is over, System 1's audit of them (ObjectivesAudit). Writes
-    # @objectives_announced, @objectives_audit; reads @objective_proposals
-    # under @objective_proposals_mutex, @session, @side_judgments.
+    # The session's objectives (TurnStages::Objectives, forwarded): the view
+    # announced when it changed, the model's proposals kept as cards until
+    # the turn is over, System 1's audit of them (ObjectivesAudit); and
+    # Check this's side request. Reads @objectives_stage, @side_judgments,
+    # @host_registry, @session.
     module ObjectivesPart
-      # The session's objectives as the page draws them (Objectives.view), when
-      # that differs from the last announced: after an edit (its file written,
-      # pending), once a list note is in, at a turn's end (its moves) and after
-      # a rollback. A session with no list announces nothing. It only informs:
-      # a failure is logged, never the turn's.
-      def announce_objectives(session = @session)
-        return unless session
-
-        synchronize_events do
-          view = Objectives.view(session.id, session.messages, state_dir: session_state_dir, running: live_conversation&.dup)
-          next if view.nil? || view == @objectives_announced
-
-          @objectives_announced = view
-          announce({ type: :objectives_updated, session_id: session.id, **view })
-        end
-      rescue StandardError => e
-        Log.warn(:turn, "objectives_announce_failed", error: e.class.name, msg: e.message)
-      end
+      # The session's objectives as the page draws them, when that differs
+      # from the last announced (TurnStages::Objectives#announce).
+      def announce_objectives(session = @session) = @objectives_stage.announce(session)
 
       # Check this (ObjectivesCheck)'s one side request. Its usage is in the
       # session's side line. Raises as ctx.ask_model's request does.
@@ -38,79 +23,26 @@ module Samagotchi
       end
 
       # A change the model proposes (the objectives tool), kept until the turn
-      # is over, as #context_choice's cards are: a card shown then is a quiet one, between turns, with its Apply kept
-      # over a restart (CardStore), not a running turn's that says it waits on the
-      # user. The same change twice in a turn is one card.
+      # is over (TurnStages::Objectives#propose).
       # @return [Boolean] false past Objectives::PROPOSALS_PER_TURN
-      def propose_objective(proposal)
-        @objective_proposals_mutex.synchronize do
-          next true if @objective_proposals.any? { |p| p.line == proposal.line }
-          next false if @objective_proposals.size >= Objectives::PROPOSALS_PER_TURN
-
-          @objective_proposals << proposal
-          true
-        end
-      end
-
-      def show_objective_proposals
-        drain_objective_proposals.each do |proposal|
-          id = "objectives-#{SecureRandom.hex(4)}"
-          show_card(source: Objectives::SOURCE, id: id, title: proposal.title, body: proposal.body,
-                    actions: [{ label: "Apply", command: proposal.action_line(id) },
-                              { label: "Dismiss", command: "/objectives --card #{id} dismiss" }])
-        end
-      rescue StandardError => e
-        Log.warn(:turn, "objectives_proposal_failed", error: e.class.name, msg: e.message)
-      end
-      private :show_objective_proposals
-
-      # A turn that did not complete (canceled, failed) takes its proposals
-      # off the buffer without showing them: their Apply card would sit after a
-      # turn whose `objectives propose` call is not in the history (a rollback
-      # after Ctrl-C drops it), and leaving them in the buffer would show them
-      # at the end of the next turn.
-      def discard_objective_proposals(turn)
-        dropped = drain_objective_proposals
-        Log.info(:turn, "objectives_proposals_dropped", count: dropped.size, outcome: turn.outcome.to_s) unless dropped.empty?
-      end
-      private :discard_objective_proposals
-
-      def drain_objective_proposals
-        @objective_proposals_mutex.synchronize { @objective_proposals.slice!(0..) }
-      end
-      private :drain_objective_proposals
+      def propose_objective(proposal) = @objectives_stage.propose(proposal)
 
       private
 
-      # System 1 on the objectives, in audit (ObjectivesAudit): the owner's turns
-      # only, and for a message a person's: a reminder's or a delegate's prompt isn't one.
-      def audit_objectives_incoming(turn)
-        return unless turn.prompt.is_a?(String) && turn.origin.human? && OwnerPrompt.turn?(session: turn.session, author: turn.origin.author)
-
-        objectives_audit.incoming(turn.session, turn.prompt)
-      end
-      private :audit_objectives_incoming
-
-      def audit_objectives_outgoing(turn, result)
-        return unless OwnerPrompt.turn?(session: turn.session, author: turn.origin.author)
-
-        objectives_audit.outgoing(turn.session, result.text)
-      end
-      private :audit_objectives_outgoing
-
-      # With saving off nothing would come of an ask, so none is made.
-      def objectives_audit
-        @objectives_audit ||= ObjectivesAudit.new(
-          side: @side_judgments, state_dir: -> { session_state_dir },
-          client_for: lambda do |judgment, session|
-            next nil unless system_one_runs.on?
-
-            system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: ObjectivesAudit::MODE, tag: :system_one),
-                                 judgment, session)
-          end
+      # The objectives' stage (TurnStages::Objectives).
+      attr_reader :objectives_stage
+
+      # The stage over this Engine's side asks and its event lock (built in
+      # #initialize, once the host registry is).
+      def build_objectives_stage
+        TurnStages::Objectives.new(
+          side_judgments: @side_judgments, host_registry: @host_registry, state_dir: -> { session_state_dir },
+          recording: ->(client, judgment, session, mode:) { system_one_recording(client, judgment, session, mode: mode) },
+          runs: -> { system_one_runs }, synchronize: ->(&block) { synchronize_events(&block) },
+          announce: ->(event) { announce(event) }, running: -> { live_conversation },
+          show_card: ->(**card) { show_card(**card) }
         )
       end
-      private :objectives_audit
     end
   end
 end

data/lib/samagotchi/engine/participants.rb

@@ -5,13 +5,16 @@ module Samagotchi
     # The session's participants: the running turn's author, a pair turn's
     # stop check, who came or went, the system prompt's participants line and
     # a participant's author fields. Writes @participant_stop,
-    # @participants_line; reads @participants, @participants_watch,
-    # @guardrail_wiring.
+    # @participants_line; reads @participants, @participants_watch and the
+    # turn's TurnContext.
     module ParticipantsPart
       # The running turn's author when a participant wrote it, else nil
-      # (ctx.turn_author, the hooks' author).
+      # (ctx.turn_author, the hooks' author, the judgments' participant:,
+      # ObjectivesCheck): one read of the published TurnContext, so any
+      # thread sees the running turn's author from its first moment, never
+      # the last turn's.
       # @return [String, nil]
-      def turn_author = turn_running? ? @guardrail_wiring.turn_author : nil
+      def turn_author = turn_context&.author
 
       # Whether a participant's pair turn must stop, read before each of its
       # generations (#guard_participant_spend): author ("p:<id>") → why (their
@@ -20,7 +23,7 @@ module Samagotchi
       # nothing is checked mid-turn.
       attr_writer :participant_stop
 
-      # Before each generation (KernelLoop#generation_guard): a pair turn whose
+      # Before each generation (KernelLoop::Services#generation_guard): a pair turn whose
       # participant's link ended, or whose spend (Engine#metrics: their
       # finished turns, this one's finished generations, their side requests)
       # passed their cap, stops on the plugins' stop path (cost-cap's,
@@ -28,10 +31,11 @@ module Samagotchi
       # once it ends, so a turn can pass the cap by its last generation. The
       # turn-start check is the Worker's (Worker#participant_refusal); a
       # review turn only reads, and keeps to it.
-      def guard_participant_spend
-        author = turn_author
+      # @param context [TurnContext] the running turn's (the loop's)
+      def guard_participant_spend(context)
+        author = context&.author
         return if author.nil? || @participant_stop.nil?
-        return unless @guardrail_wiring.turn_mode == ParticipantMode::PAIR
+        return unless context.participant_mode == ParticipantMode::PAIR
 
         reason = @participant_stop.call(author) or return
         hook_stop_turn(reason, PARTICIPANTS_HOOK)
@@ -77,8 +81,9 @@ module Samagotchi
       # A participant's opening message keeps the rules it was delivered under
       # (ParticipantMode), stamped before any request carries it, so its header
       # never changes when the session's mode does.
-      def participant_mode_fields(author)
-        mode = Steer.participant_author?(author) && @guardrail_wiring.turn_mode
+      # @param context [TurnContext] the turn's
+      def participant_mode_fields(context)
+        mode = context.participant? && context.participant_mode
         mode ? { participant_mode: mode.to_s } : {}
       end
     end

data/lib/samagotchi/engine/plugins.rb

@@ -101,11 +101,13 @@ module Samagotchi
       # Apply the staged tool sets, on the turn thread, before the turn's
       # system prompt is built (PluginTasks#apply_staged_tools!). A changed
       # set may change the chi group the search tool's description counts
-      # (a plugin tool the toolkit leaves out).
+      # (a plugin tool the toolkit leaves out). Publishes the Registry it
+      # leaves (#publish_tools!).
       # @return [Boolean] whether the tools changed
       def apply_staged_tools!
         changed = @plugin_tasks.apply_staged_tools!
         @tool_index.refresh! if changed
+        publish_tools!
         changed
       end
       public :apply_staged_tools!

data/lib/samagotchi/engine/questions.rb

@@ -15,7 +15,7 @@ module Samagotchi
       end
 
       # Ask the model's question (ask_user_question): the kernel's
-      # question_handler, called on the turn thread with the payload
+      # Services#question_handler, called on the turn thread with the payload
       # Tools::AskUserQuestion.validate made (QuestionDesk#request), after
       # the :question_asked hooks (QuestionAsked) gave the step its refs; a
       # --non-interactive run has no one to ask, so they don't fire there.

data/lib/samagotchi/engine/side_requests.rb

@@ -42,9 +42,12 @@ module Samagotchi
       def side_author(kind)
         # Check this is only ever the owner's, whichever turn runs as it ends.
         return nil if kind.to_s == ObjectivesCheck::SOURCE
-        return nil unless turn_running? || kind.to_s == RECAP_SIDE_KIND
 
-        @guardrail_wiring.turn_author
+        # One read each of the published contexts (TurnState): any thread.
+        running = turn_context
+        return running.author if running
+
+        kind.to_s == RECAP_SIDE_KIND ? last_turn_context&.author : nil
       end
 
       private

data/lib/samagotchi/engine/toolkit.rb

@@ -4,9 +4,9 @@ module Samagotchi
   class Engine
     # The session's toolkit: the kits and what a turn declares
     # (ToolkitBinding, forwarded), ctx.load_tools and the staged loads a turn
-    # appends, and System 1's toolkit suggestion (start, settle, warm-up).
-    # Writes @toolkit_warmup_thread; reads @toolkit_binding, @tools,
-    # @tool_index, @tool_loads, @side_judgments, @session.
+    # appends, and System 1's toolkit suggestion (TurnStages::ToolkitSuggestion,
+    # forwarded). Reads @toolkit_binding, @tools, @tool_index, @tool_loads,
+    # @toolkit_suggestion, @session.
     module ToolkitPart
       private
 
@@ -17,22 +17,29 @@ module Samagotchi
       def toolkit_explained(toolkit = nil) = @toolkit_binding.explained(toolkit)
       def toolkit_summary = @toolkit_binding.summary
 
+      # The Registry published for readers off the turn thread
+      # (ToolkitBinding#publish!): at the end of the Engine's build, after a
+      # turn's staged tool sets and its toolkit apply.
+      def publish_tools! = @toolkit_binding.publish!
+
       # The tools this session registered (Tools::Registry), declared or not.
       attr_reader :tools
 
       public :tools, :toolkit_kits, :resolved_toolkit, :toolkit_explained, :toolkit_summary
 
       # A plugin's ctx.load_tools: stage the reachable tools +names+ names
-      # (Tools::ToolIndex#deferred_name) that the session neither declares
-      # nor loaded with an earlier tool change, for bundle +bundle+. A name
-      # that names no tool at all is logged; a declared or removed one is
-      # skipped quietly.
+      # (Tools::ToolIndex#deferred_name, on the published Registry) that the
+      # session neither declares nor loaded with an earlier tool change, for
+      # bundle +bundle+. A name that names no tool at all is logged; a
+      # declared or removed one is skipped quietly.
       # @return [Array<String>] the wire names staged
       def load_tools(names, bundle)
         added = ToolLoads.added(@session&.messages)
+        published = @toolkit_binding.published
+        surface = Tools::ToolSurface.for(published)
         wanted = names.filter_map do |name|
-          wire = @tool_index.deferred_name(name)
-          Log.info(:plugins, "load_tools_skipped", bundle: bundle, tool: name) unless wire || @tools.key?(name)
+          wire = @tool_index.deferred_name(name, surface)
+          Log.info(:plugins, "load_tools_skipped", bundle: bundle, tool: name) unless wire || published.key?(name)
           wire
         end
         @tool_loads.stage(wanted - added, by: bundle)
@@ -79,191 +86,27 @@ module Samagotchi
       def apply_toolkit!(session, on_event = nil) = @toolkit_binding.apply!(session, on_event)
       private :apply_toolkit!
 
-      # Start the toolkit classifier after :turn_started, for audit and on
-      # mode alike (one eligibility, one snapshot, one thread). All session
-      # and tool-registry reads happen here; the thread receives only this
-      # snapshot. Audit never blocks: the thread logs its line. On mode
-      # returns the ask's Pending, which the turn joins before apply_toolkit!
-      # (#settle_toolkit_suggestion), with the turn's controller as the
-      # request's cancel controller.
-      # @return [ToolkitSuggest::Pending, nil] nil unless the turn joins an ask
-      def start_toolkit_suggestion(turn)
-        mode = Config.get("toolkit.suggest.mode").to_s
-        return if mode == "off"
-
-        joined = mode == "on"
-        session = turn.session
-        default = Toolkit.of(session.toolkit)
-        log = toolkit_suggestion_log
-        # The predicate checks the session first; the kits (memory kits are
-        # read from disk) and the log (read whole) only when it gets there.
-        kits = nil
-        candidates = nil
-        return unless ToolkitSuggest.eligible?(
-          session: session, prompt: turn.prompt, author: turn.origin.author,
-          candidate_count: lambda {
-            kits = @toolkit_binding.kits
-            candidates = ToolkitSuggest.candidates(kits, default_name: default.name)
-            candidates.size
-          },
-          last_suggestion: -> { ToolkitSuggest.last_suggestion(log, session.id) },
-          defer_turns: Config.get("toolkit.suggest.defer_turns"),
-          defer_tokens: Config.get("toolkit.suggest.defer_tokens")
-        )
+      # System 1's toolkit suggestion (TurnStages::ToolkitSuggestion):
+      # prepare_turn starts, settles and abandons it; the Worker warms it.
+      attr_reader :toolkit_suggestion
+      private :toolkit_suggestion
 
-        # One ask at a time: an eligible turn while the last one still runs
-        # goes unasked, and says so.
-        if @side_judgments.in_flight?(:toolkit)
-          Log.info(:toolkit, "toolkit_suggest_in_flight_skipped", session_id: session.id)
-          return
-        end
-
-        client = system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit),
-                                      ToolkitSuggest::JUDGMENT, session, mode: Config.get("toolkit.suggest.mode").to_s)
-        return unless client
-
-        # The warm-up's only value is the cache: the real ask never queues
-        # behind it.
-        stop_toolkit_warmup
-
-        # Rules, not tool lists: this runs before await_init_tasks and
-        # apply_staged_tools!, so a first turn's plugin/MCP tools aren't
-        # registered yet; the report expands the rules (ToolkitSuggest.rules).
-        snapshots = candidates.map do |kit|
-          ToolkitSuggest::Candidate.new(name: kit.name.dup.freeze, description: kit.description.dup.freeze,
-                                        rules: ToolkitSuggest.rules(Toolkit.resolve_kit(kit.name, kits)))
-        end.freeze
-        default_snapshot = ToolkitSuggest::Candidate.new(name: default.name.dup.freeze, description: nil,
-                                                         rules: ToolkitSuggest.rules(default.resolve(kits)))
-        registered = @tools.entries(toolkit: nil).reject { |entry| entry.source == Tools::ToolIndex::SOURCE }
-        core_tools, plugin_tools = registered.partition(&:core?).map { |entries| entries.map { |entry| entry.name.dup.freeze }.freeze }
-        state = ToolkitSuggest.question(
-          default: default, kits: kits, project: File.basename(session.project_root.to_s),
-          prompt: turn.prompt
-        ).last
-        snapshot = ToolkitSuggest::Snapshot.new(
-          session_id: session.id.dup.freeze, turn_number: ToolkitSuggest.turn_number(session.messages),
-          default: default_snapshot, candidates: snapshots, core_tools: core_tools, plugin_tools: plugin_tools,
-          state: { project: state[:project].dup.freeze, prompt: state[:prompt].dup.freeze }.freeze
-        )
-        threshold = Config.get("toolkit.suggest.threshold")
-        runs = session.scratch ? nil : system_one_runs
-        pending = ToolkitSuggest::Pending.new(log: log, joined: joined,
-                                              acted: runs && ->(judged, did) { runs.acted(judged.fields[:run_id], did) },
-                                              timeout_seconds: SystemOne::Client.configured_timeout_ms / 1000.0)
-        # On mode: cut by a Stop while the turn waits (Pending#wait), not
-        # by one after it went on; audit's ask is never cut.
-        controller = joined ? pending.cancel_controller : nil
-        @side_judgments.start(:toolkit, warn: ToolkitSuggest.method(:warn), finish: pending.method(:finish)) do
-          ToolkitSuggest.judge(client: client, snapshot: snapshot, threshold: threshold,
-                               cancel_controller: controller)
-        end
-        joined ? pending : nil
-      rescue StandardError => e
-        ToolkitSuggest.warn(e)
-        nil
-      end
-      private :start_toolkit_suggestion
-
-      # On mode, before apply_toolkit!: wait for the ask (#start_toolkit_
-      # suggestion) up to System 1's timeout from its start, or until a Stop,
-      # and put the session on a candidate picked with confidence ≥ threshold
-      # (ToolkitBinding#suggest: origin suggested, saved, the notice). Any
-      # other outcome (the default, below threshold, undecided, no judgment,
-      # a timeout, a Stop) leaves the session on its default. Nothing here
-      # sends a request; prepare_turn's cancel check ends a stopped turn. A
-      # Stop wins over an answer already in (Pending#wait checks it first).
-      def settle_toolkit_suggestion(turn, pending)
-        return if pending.nil?
-
-        outcome, judged = pending.wait(turn.controller)
-        if outcome == :timeout
-          # The session starts on its default without a word otherwise: a
-          # slow System 1 host (a local one) is the usual cause.
-          timeout_ms = SystemOne::Client.configured_timeout_ms
-          Log.warn(:toolkit, "toolkit_suggest_timeout", session_id: turn.session.id, timeout_ms: timeout_ms,
-                                                        reason: "System 1 gave no answer within system_one.timeout_ms")
-          @toolkit_binding.fell_back(turn.session, "System 1 took over #{timeout_ms} ms")
-          return
-        end
-        unless outcome == :answered
-          Log.info(:toolkit, "toolkit_suggest_#{outcome}", session_id: turn.session.id)
-          return
-        end
-        return if judged.nil?
-
-        pending.record(toolkit_suggestion_outcome(turn.session, judged))
-      rescue StandardError => e
-        ToolkitSuggest.warn(e)
-        pending&.record("failed")
-      end
-      private :settle_toolkit_suggestion
-
-      # What the turn does with an answered ask, as the log line's did:
-      # suggested (switched), chosen (the toolkit isn't the default any
-      # more), unavailable (the kit is gone), defer or default.
-      def toolkit_suggestion_outcome(session, judged)
-        case judged.would
-        when "suggested"
-          return "chosen" unless session.toolkit_origin == "default"
-          return "unavailable" unless @toolkit_binding.kits.key?(judged.suggestion.kit)
-
-          switched = @toolkit_binding.suggest(session, judged.suggestion.kit, confidence: judged.suggestion.confidence,
-                                                                              deferred: ToolkitSuggest.model_reply?(session.messages))
-          switched ? "suggested" : "chosen"
-        when "defer" then "defer"
-        when "no_judgment"
-          # System 1 failed (its own warn) or answered nothing usable.
-          @toolkit_binding.fell_back(session, "System 1 gave no answer")
-          "default"
-        else "default"
-        end
-      end
-      private :toolkit_suggestion_outcome
-
-      # On mode, as an idle worker starts (Worker#start_background): one ask
-      # with the real question and a stand-in prompt, on its own thread,
-      # never logged and never waited for, so System 1's server has the
-      # question's prefix cached for the first prompt. Only for a session a
-      # first prompt could be asked for: origin default, no model reply, not
-      # a delegate child or a review session, at least two candidates; and
-      # not when the worker starts on a first prompt (that ask comes at once).
-      def warm_toolkit_suggestion!
-        return unless Config.get("toolkit.suggest.mode").to_s == "on"
-
-        session = @session
-        return if session.nil? || session.toolkit_origin != "default" || session.delegate? || session.review?
-        return if ToolkitSuggest.model_reply?(session.messages) || !session.last_prompt.to_s.strip.empty?
-
-        default = Toolkit.of(session.toolkit)
-        kits = @toolkit_binding.kits
-        return if ToolkitSuggest.candidates(kits, default_name: default.name).size < 2
-
-        client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
-        return unless client
-
-        project = File.basename(session.project_root.to_s)
-        @toolkit_warmup_thread = Thread.new do
-          ToolkitSuggest.warm(client: client, default: default, kits: kits, project: project)
-        end
-      rescue StandardError => e
-        ToolkitSuggest.warn(e)
-        nil
-      end
+      # On mode, as an idle worker starts (Worker#start_background): the
+      # warm-up ask (TurnStages::ToolkitSuggestion#warm!).
+      def warm_toolkit_suggestion! = @toolkit_suggestion.warm!(@session)
       public :warm_toolkit_suggestion!
 
-      # A still-running warm-up, stopped: a real ask (or the worker leaving)
-      # doesn't wait behind it.
-      def stop_toolkit_warmup
-        @toolkit_warmup_thread&.kill
-        @toolkit_warmup_thread = nil
-      end
-      private :stop_toolkit_warmup
-
-      def toolkit_suggestion_log
-        SideJudgments.log(ToolkitSuggest.log_path(session_state_dir), tag: :toolkit, event: "toolkit_suggest_log_failed")
+      # The stage over this Engine's side asks, binding and tools (built in
+      # #build_tools_and_plugins, before the plugins load).
+      def build_toolkit_suggestion
+        TurnStages::ToolkitSuggestion.new(
+          side_judgments: @side_judgments, host_registry: @host_registry, toolkit_binding: @toolkit_binding,
+          tools: @tools, state_dir: -> { session_state_dir },
+          recording: ->(client, judgment, session, mode:) { system_one_recording(client, judgment, session, mode: mode) },
+          runs: -> { system_one_runs }
+        )
       end
-      private :toolkit_suggestion_log
+      private :build_toolkit_suggestion
     end
   end
 end

data/lib/samagotchi/engine/turn_end.rb

@@ -117,7 +117,7 @@ module Samagotchi
         # a display version of the answer (AnswerDisplay) and event[:refs]
         # for refs on it (AnswerRefs).
         session = turn.session
-        audit_objectives_outgoing(turn, result) unless canceled || result.exhausted?
+        @objectives_stage.outgoing(turn, result) unless canceled || result.exhausted?
         display = AnswerDisplay.new(session.messages)
         refs = AnswerRefs.new(session.messages, cwd: session.working_directory)
         after_turn = { type: :after_turn, status: canceled ? "canceled" : "completed",

data/lib/samagotchi/engine/turn_helpers.rb

@@ -5,8 +5,9 @@ module Samagotchi
     # What a turn's steps use before and around the model: its settings,
     # images and vision, the model ref and resumed run start it generates
     # with, the used memories it publishes, and the turn-end warm-up of the
-    # next one. Writes @next_turn_waiting; reads @model_settings, @kernel,
-    # @prompt_warmup, @thinking_notices, @turn_state.
+    # next one (TurnStages::Warmup, built here). Writes @next_turn_waiting;
+    # reads @model_settings, @kernel, @prompt_warmup, @thinking_notices,
+    # @turn_state, @turn_warmup.
     module TurnHelpersPart
       # The turn's settings for the kernel (LLM::TurnSettings): vision,
       # sampling and thinking, the thinking resolved before the hooks run.
@@ -34,44 +35,20 @@ module Samagotchi
       # warm-up then. nil: neither.
       attr_accessor :next_turn_waiting
 
-      # After a completed turn, prefill the next turn's prompt up to its user
-      # message while the user reads (PromptWarmup, cache.warmup). Only on a
-      # local llama.cpp host on the native loop, and not when the next turn's
-      # start differs anyway or starts at once: a reminder due, a continue
-      # offer (the turn ran out of steps), a carried steer or queued input.
-      # Never fails the turn.
-      def warm_up_next_turn(turn, result)
-        return if result.canceled? || result.resumable?
-
-        model = effective_model
-        client = model.client
-        return unless warmup_target?(model, client)
-        return if reminders_due? || @turn_state.carried_steers? || @next_turn_waiting&.call
-
-        messages = ContextNote.with_system_head(turn.session.messages.dup, { role: "system", content: system_prompt(model) })
-        # Under the next turn's strategy (a /model switch may have changed it);
-        # the last turn's when it can't be resolved.
-        prompt, images = @kernel.warmup_prompt(messages, llm_context: @model_settings.turn_llm_context || @kernel.turn_settings&.llm_context)
-        return unless prompt
-
-        started = @prompt_warmup.start(client: client, prompt: prompt, model: @kernel.turn_settings.model_name,
-                                       slot: @kernel.last_slot, images: images)
-        @kernel.warmed_up! if started
-      rescue StandardError => e
-        Log.warn(:model, "warmup_skipped", error: e.class.name, msg: e.message.to_s[0, 200])
-      end
-      private :warm_up_next_turn
-
-      # Never a paid or remote host (cache.warmup auto means local only), nor
-      # the chat loop (Splash keeps its own cache; llama.cpp's chat path is
-      # not measured), nor a client that can't warm up (a spec's stub).
-      def warmup_target?(model, client)
-        return false if model.chat? || model.entry.remote?
-        return false unless client.respond_to?(:warm_up)
-
-        PromptWarmup.enabled?
+      # The turn-end warm-up's stage (TurnStages::Warmup).
+      attr_reader :turn_warmup
+      private :turn_warmup
+
+      # The stage over the kernel and the Engine's PromptWarmup (built in
+      # #initialize, once the kernel is).
+      def build_turn_warmup
+        TurnStages::Warmup.new(
+          prompt_warmup: @prompt_warmup, kernel: @kernel, turn_state: @turn_state, model_settings: @model_settings,
+          model: -> { effective_model }, system_prompt: ->(model) { system_prompt(model) },
+          reminders_due: -> { reminders_due? }, next_turn_waiting: -> { next_turn_waiting&.call }
+        )
       end
-      private :warmup_target?
+      private :build_turn_warmup
 
       # The ref (host:model, as asked) a turn's generations ran on: the model
       # #generate resolved, after the before_turn hooks (which may switch it).