samagotchi 0.11.0 → 0.13.0

data/lib/samagotchi/engine.rb

@@ -8,6 +8,7 @@ require "yaml"
 
 require_relative "config"
 require_relative "context_note"
+require_relative "context_status"
 require_relative "steer"
 require_relative "turn_note"
 require_relative "model_profile"
@@ -24,6 +25,7 @@ require_relative "client"
 require_relative "host_registry"
 require_relative "llm/backend"
 require_relative "llm/openai_chat"
+require_relative "llm/turn_settings"
 require_relative "session"
 require_relative "archive_store"
 require_relative "session_observer"
@@ -38,8 +40,11 @@ require_relative "idle_scheduler"
 require_relative "hooks"
 require_relative "guardrails"
 require_relative "reminder_store"
+require_relative "reminder_queue"
 require_relative "tools/memory"
 require_relative "muted_memories"
+require_relative "used_memories"
+require_relative "turn_state"
 require_relative "bundle_needs"
 require_relative "model_overlay"
 require_relative "served_model"
@@ -95,6 +100,10 @@ module Samagotchi
     #   delegate (a child would outlive it) nor plugin fork
     def initialize(client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, model_name: nil, memories: [], muted_memories: [], kernel: nil, recap: nil, reminders: nil,
                    plugins: true, scratch: false, model_typed: nil)
+      # The turn as other threads see it (flag, cancel controller, sink,
+      # steers) and the idle layer's activity clock. Built first: a plugin
+      # may steer or ask whether a turn runs while it loads.
+      @turn_state = TurnState.new(clock: -> { monotonic_now })
       @scratch = scratch
       @no_interrupt = no_interrupt
       @chat_backend = nil
@@ -189,47 +198,39 @@ module Samagotchi
       @shut_down = false
       load_plugins if plugins
       guardrail_rules
-      # Use the KernelLoop's reminder_store if provided (TerminalUI path),
-      # otherwise create our own (SessionManager/one-shot paths). This ensures
-      # tool calls via KernelLoop and reminder injection via Engine read/write
-      # the same store.
-      if kernel && kernel.respond_to?(:reminder_store)
-        @reminder_store = kernel.reminder_store
-      else
-        @reminder_store = ReminderStore.new
-      end
+      # The Engine owns the reminder store; its kernel (built here, or a
+      # spec's) gets it, so tool calls via KernelLoop and reminder injection
+      # via Engine read/write the same store.
+      @reminder_store = ReminderStore.new
+      # The due reminders on their way into a turn, and the names the idle
+      # tick queued for a reminder turn.
+      @reminder_queue = ReminderQueue.new(store: @reminder_store)
       # Build the idle reminders detector (wired to reminder_store)
       callback = reminders.is_a?(Hash) && reminders[:callback] ? reminders[:callback] : nil
       @reminders = build_reminders(auto_turn_callback: callback)
       # Track whether this is the first turn in the session (for session_start event)
       @first_turn = true
+      # A given kernel (specs) gets the Engine's store, hooks and tools, as
+      # the one built here does.
       @kernel = kernel || KernelLoop.new(client: @client, profile: @given_profile, hooks: @hooks, reminder_store: @reminder_store,
                                          tools: @tools)
+      @kernel.reminder_store = @reminder_store
+      @kernel.hooks = @hooks
+      @kernel.tools = @tools
       sync_kernel_client!
       sync_model_key!
       # The mutes never change during a session, so no re-sync: the kernel's
       # memory_read guard reads the same list for every turn.
       @muted_memory_names = MutedMemories.normalize_list(muted_memories)
-      @kernel.muted_memory_names = @muted_memory_names if @kernel.respond_to?(:muted_memory_names=)
-      # Keep kernel client in sync with active host via setter
-      @kernel_client_synced = false
-      # Engine owns hooks; if a kernel was supplied externally (TUI path) propagate
-      # the Engine's registry so all UIs reuse the same instance. Without this the
-      # TUI's KernelLoop fires with nil hooks and before_generation/after_generation
-      # etc. never fire in interactive mode.
-      if kernel && @kernel.respond_to?(:hooks=)
-        @kernel.hooks = @hooks
-      end
-      # Likewise its tools: the REPL builds its kernel before the Engine.
-      @kernel.tools = @tools if kernel && @kernel.respond_to?(:tools=)
+      @kernel.muted_memory_names = @muted_memory_names
       # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
-      @kernel.question_handler = proc { |payload| request_question(payload) } if @kernel.respond_to?(:question_handler=)
+      @kernel.question_handler = proc { |payload| request_question(payload) }
       # Every tool call asks this gate first. The kernel is never rebuilt, so
       # it holds across model switches.
       self.guardrail_state_dir = Session.default_state_dir
       # list_sessions and send_note speak for whichever session runs now.
-      @kernel.peers = PeerView.new(self) if @kernel.respond_to?(:peers=)
-      @kernel.guardrail_gate = @guardrail_wiring.gate if @kernel.respond_to?(:guardrail_gate=)
+      @kernel.peers = PeerView.new(self)
+      @kernel.guardrail_gate = @guardrail_wiring.gate
       # What a hook can do beyond reading its event (event[:notify],
       # event[:ask_user], event[:stop_turn]): the Engine's routes to the UIs.
       @hooks.runtime = hook_runtime
@@ -244,29 +245,18 @@ module Samagotchi
       @session = nil
       @session_observer = SessionObserver.new
       @metrics = SessionMetrics.new
-      @used_memory_names = []
-      @used_memory_mutex = Monitor.new
+      @used_memories = UsedMemories.new
       # Hydrate from resumed session if present
-      if @resume_session && @resume_session.respond_to?(:used_memory_names)
-        @used_memory_names = Array(@resume_session.used_memory_names).map(&:to_s).reject(&:empty?).uniq
+      if @resume_session
+        @used_memories.absorb(@resume_session)
         @session = @resume_session
       end
-      # Shared inactivity clock + turn-running flag for the idle subsystems
-      # (session recap + reminders), all polled by the shared IdleScheduler.
-      # `record_activity` is the single seam every UI calls (run_turn itself,
-      # the REPL on keystrokes and after a reminder turn), so the idle
-      # layer's clock is identical across UIs.
-      @activity_mutex = Monitor.new
-      @last_activity_at = monotonic_now
-      @activity_seq = 0
-      @turn_running = false
-      @active_cancel_controller = nil
-      # Plugin steers ({text:, source:}) waiting for the running turn's next
-      # boundary (#steer); guarded by @activity_mutex.
-      @steers = []
-      # Reminder names the interactive REPL's IdleReminders callback marked due;
-      # the REPL polls them to decide when to run a synthetic reminder turn.
-      @due_reminder_names = []
+      # The idle subsystems' (session recap + reminders) inactivity clock
+      # starts now, after the plugins loaded. `record_activity` is the
+      # single seam every UI calls (run_turn itself, the REPL on keystrokes
+      # and after a reminder turn), so the idle layer's clock is identical
+      # across UIs.
+      @turn_state.restart_clock!
       @recap = RecapSetup.build(recap, engine: self, host_registry: @host_registry,
                                 session_target: -> { session_model_recap_target },
                                 session_id: -> { @session&.id }, state_dir: -> { session_state_dir })
@@ -296,37 +286,29 @@ module Samagotchi
       backend_for(@host_registry.resolve(@effective_model_name))
     end
 
-    # Record that activity happened (user input or a completed turn). Shared,
-    # mutex-guarded seam for the idle recap detector. Idempotent-ish: each call
-    # advances both the last-activity timestamp and the activity sequence.
+    # Record that activity happened (user input or a completed turn): the
+    # idle jobs' seam (TurnState#record_activity). Each call advances both
+    # the last-activity timestamp and the activity sequence.
     # @param now [Float, nil] injectable monotonic time (defaults to now)
     def record_activity(now = nil)
-      @activity_mutex.synchronize do
-        @last_activity_at = now ? now.to_f : monotonic_now
-        @activity_seq += 1
-      end
+      @turn_state.record_activity(now)
     end
 
     # @return [Float] monotonic seconds of the last recorded activity
     def last_activity_at
-      @activity_mutex.synchronize { @last_activity_at }
+      @turn_state.last_activity_at
     end
 
     # @return [Integer] monotonically-increasing activity counter (advanced by
     #   #record_activity; lets the idle detector summarize once per idle window)
     def activity_seq
-      @activity_mutex.synchronize { @activity_seq }
+      @turn_state.activity_seq
     end
 
-    # Mark whether a turn is currently running (shared with the idle detector so
-    # a recap never fires, or renders, while the model is generating).
-    def set_turn_running(running)
-      @activity_mutex.synchronize { @turn_running = running }
-    end
-
-    # @return [Boolean] true while a turn is in flight
+    # @return [Boolean] true while a turn is in flight (the idle jobs never
+    #   fire, nor render, while the model is generating)
     def turn_running?
-      @activity_mutex.synchronize { @turn_running }
+      @turn_state.running?
     end
 
     # Put +text+ into the running turn, as a UI's steering does: it joins the
@@ -337,15 +319,7 @@ module Samagotchi
     # the turn ends first, it is dropped (logged).
     # @return [Boolean] whether it was queued
     def steer(text, source:)
-      text = text.to_s.strip
-      return false if text.empty?
-
-      @activity_mutex.synchronize do
-        return false unless @turn_running
-
-        @steers << { text: text, source: source.to_s }
-      end
-      true
+      @turn_state.steer(text, source: source)
     end
 
     # The drain a turn's loop gets: the caller's lines (a UI's steering; nil
@@ -362,11 +336,7 @@ module Samagotchi
     private :turn_drain
 
     def take_steers(drop)
-      steers = @activity_mutex.synchronize do
-        taken = @steers
-        @steers = []
-        taken
-      end
+      steers = @turn_state.take_steers
       return steers unless drop
 
       log_dropped_steers(steers, "answered")
@@ -383,41 +353,37 @@ module Samagotchi
 
     # @return [Array<String>] reminder names queued for a synthetic REPL turn
     def due_reminder_names
-      @activity_mutex.synchronize { @due_reminder_names.dup }
+      @reminder_queue.pending_names
     end
 
     # Queue reminder names for a synthetic REPL turn (IdleReminders callback).
     def note_due_reminders(names)
-      @activity_mutex.synchronize { @due_reminder_names = Array(names).dup }
+      @reminder_queue.note_pending(names)
     end
 
     def clear_due_reminder_names!
-      @activity_mutex.synchronize { @due_reminder_names = [] }
+      @reminder_queue.clear_pending!
     end
 
     # @return [CancellationController, nil] active turn's cancellation controller
     def active_cancel_controller
-      @activity_mutex.synchronize { @active_cancel_controller }
+      @turn_state.controller
     end
 
     # Cancel the currently running turn, if any.
     # @param reason [Symbol] cancellation reason
     # @return [Boolean] whether a cancellation was triggered
     def cancel_current_turn!(reason = :manual)
-      ctrl = active_cancel_controller
-      return false unless ctrl
-
-      ctrl.cancel!(reason)
+      @turn_state.cancel!(reason)
     end
 
     # Snapshot the current session messages as a JSON string for the idle
-    # recap. Reads the array reference under the mutex (a single atomic
-    # pointer read in CRuby) then serializes a dup'd copy OUTSIDE the lock so
-    # the brief serialization never blocks the main turn thread. Never mutates
-    # session.messages.
+    # recap. The array is never mutated in place (a turn or a note replaces
+    # it), so the reference read here is a consistent snapshot; a dup'd
+    # copy is serialized. Never mutates session.messages.
     # @return [String] JSON array of the messages
     def messages_json_for_recap
-      snapshot = @activity_mutex.synchronize { @session&.messages }
+      snapshot = @session&.messages
       return "[]" if snapshot.nil?
 
       JSON.generate(AnswerDisplay.strip_all(snapshot).map(&:dup))
@@ -453,7 +419,7 @@ module Samagotchi
     def store_model!(session)
       ref = effective_model_ref
       session.model_name = ref
-      session.model_typed = @typed_model_name.to_s == ref ? nil : @typed_model_name if session.respond_to?(:model_typed=)
+      session.model_typed = @typed_model_name.to_s == ref ? nil : @typed_model_name
       session
     end
 
@@ -495,7 +461,7 @@ module Samagotchi
       @model_key = ModelOverlay.key_for(bare_model_name(@effective_model_name))
       typed_key = ModelOverlay.key_for(@host_registry.parse_qualified_model(@typed_model_name).last)
       fallback = typed_key == @model_key ? nil : typed_key
-      @kernel.sync_model_key!(@model_key, fallback: fallback) if @kernel.respond_to?(:sync_model_key!)
+      @kernel.sync_model_key!(@model_key, fallback: fallback)
     end
     private :sync_model_key!
 
@@ -511,7 +477,7 @@ module Samagotchi
     def sync_kernel_client!
       target = @host_registry.resolve(@effective_model_name)
       @client = target.client
-      @kernel.client = target.client if @kernel.respond_to?(:client=) && @kernel.client != target.client
+      @kernel.client = target.client if @kernel.client != target.client
       backend_for(target)
     end
 
@@ -609,11 +575,7 @@ module Samagotchi
       # A plugin's init task (chi.init): never a running turn's event.
       return announce(card.merge(in_turn: false)) && card[:id] if current_init_task
 
-      sink = nil
-      in_turn = @activity_mutex.synchronize do
-        sink = @turn_event_sink
-        @turn_running
-      end
+      in_turn, sink = @turn_state.in_turn_sink
       card[:in_turn] = in_turn ? true : false
       if in_turn
         emit_event(sink, card)
@@ -819,7 +781,7 @@ module Samagotchi
       sync_model_key!
       @prompt_builder.reset!
       sync_kernel_client!
-      @client.invalidate_context_window! if @client.respond_to?(:invalidate_context_window!)
+      @client.invalidate_context_window!
       @metrics.forget_model_reports!
       ref = effective_model_ref
       if persist_default
@@ -858,53 +820,17 @@ module Samagotchi
     end
 
     # ── Reminders API ────────────────────────────────────────────────────────────
-
-    # Get and inject all due reminders into the conversation. Called at the top
-    # of run_turn (before set_turn_running(true)) so injection happens on the
-    # main thread, serially with the turn — no TOCTOU race.
-    #
-    # Returns the array of due reminder hashes (may be empty). Injects a
-    # [SYSTEM: REMINDERS DUE] message into the conversation when there are
-    # Get due reminders, inject them into the provided messages array as
-    # [SYSTEM: REMINDERS DUE], and atomically mark all as fired under one
-    # ReminderStore lock.
-    #
-    # This is the canonical method for reminder injection, called from
-    # Engine#run_turn after system prompt construction so the reminder text
-    # is never overwritten.
     #
-    # @param messages [Array<Hash>] the conversation messages (mutated in place)
-    # @return [Array<Hash>] [{name:, description:, interval_minutes:}, ...]
-    def collect_due_reminders(messages)
-      due = @reminders&.due_reminders
-      return [] if due.nil? || due.empty?
-
-      reminder_lines = due.map do |r|
-        "  #{r[:name]}: #{r[:description]} (interval: #{r[:interval_minutes]}m)"
-      end.join("\n")
-      reminder_text = "[SYSTEM: REMINDERS DUE]\n#{reminder_lines}\n[END REMINDERS]"
-      # Append as a tail message to preserve prefix KV cache. Mutating the
-      # head system prompt invalidates the cache for the entire conversation
-      # (prompt re-evaluated every interval). A tail append keeps the prefix
-      # intact — only the new reminder suffix is evaluated. Mirrors the
-      # context guidance line KernelLoop#run appends (ContextStatus#take_guidance).
-      messages << { role: "system", content: reminder_text }
-      # Atomically mark all due as fired under one lock and clear the
-      # IdleReminders latch so the next interval can be detected.
-      @reminder_store&.mark_fired_batch(due.map { |r| r[:name] })
-      @reminders&.clear_due
-      # Also clear the REPL's due-reminder queue (#note_due_reminders).
-      # Without this, a normal-turn injection leaves a stale entry, causing
-      # the next top-of-loop synthetic turn to fire empty and duplicate output.
-      clear_due_reminder_names!
-      due
-    end
+    # Each turn injects the reminders due then (#turn_messages,
+    # ReminderQueue#inject!). Between turns the idle tick (IdleReminders)
+    # finds them due and its callback queues their names
+    # (#note_due_reminders); the worker and the REPL run a reminder turn
+    # (a continue turn) for them.
 
     # @return [Boolean] whether any reminder is due now (the store's view,
-    #   which #collect_due_reminders would inject), regardless of the REPL queue
+    #   which a turn would inject), regardless of the queued names
     def reminders_due?
-      due = @reminders&.due_reminders
-      !(due.nil? || due.empty?)
+      @reminder_queue.due?
     end
 
     # @return [ReminderStore] the reminder store for inspection
@@ -941,9 +867,9 @@ module Samagotchi
     # no turn yet (it woke after an idle exit): nil when either count is
     # unknown or context.status is off.
     def saved_context_status(context)
-      return nil unless context && @kernel.respond_to?(:context_display)
+      return nil unless context
 
-      @kernel.context_display(used_tokens: context[:used_tokens], window_tokens: context[:window_tokens])
+      ContextStatus.new.display_for(used_tokens: context[:used_tokens], window_tokens: context[:window_tokens])
     end
 
     # The effective model is on a chat host (api: openai), whose loop uses
@@ -1008,7 +934,7 @@ module Samagotchi
         event_seq: @session_observer&.event_count,
         metrics: metrics,
         pending_question: @question_desk.pending,
-        used_memory_names: @used_memory_mutex.synchronize { @used_memory_names.dup },
+        used_memory_names: @used_memories.names,
         preloaded_memory_names: preloaded_memory_names,
         muted_memory_names: @muted_memory_names.dup,
         parent_id: @session&.parent_id,
@@ -1024,7 +950,7 @@ module Samagotchi
 
     # @return [Array<String>] deduped used memory names (thread-safe copy)
     def used_memory_names
-      @used_memory_mutex.synchronize { @used_memory_names.dup }
+      @used_memories.names
     end
 
     # @return [Array<String>] the memories hidden from this session (normalized names)
@@ -1039,77 +965,6 @@ module Samagotchi
       @prompt_builder.preloaded_memory_names
     end
 
-    def memory_muted?(name)
-      MutedMemories.muted?(name, @muted_memory_names)
-    end
-
-    def add_used_memory_names(names)
-      return if names.nil? || Array(names).empty?
-
-      @used_memory_mutex.synchronize do
-        Array(names).each do |n|
-          v = n.to_s.strip
-          next if v.empty?
-          next if @used_memory_names.include?(v)
-
-          @used_memory_names << v
-        end
-      end
-    end
-
-    def sync_used_memories_from_session(session)
-      return unless session && session.respond_to?(:used_memory_names)
-
-      add_used_memory_names(Array(session.used_memory_names))
-    end
-
-    def memory_name_from_tool_call(call)
-      return nil unless call.is_a?(Hash)
-
-      tool = call[:name].to_s
-      case tool
-      when Tools::MemoryRead::NAME
-        content = call[:content].to_s.strip
-        return nil if content.empty?
-
-        # comma-separated names
-        content.split(",").map { |s| normalize_memory_name(s) }.compact
-      when Tools::Read::NAME
-        path = call[:content].to_s.strip.tr("\\", "/")
-        return nil if path.empty?
-        return nil unless path.match?(/memories\/.+\.md\z/)
-
-        normalize_memory_name(path)
-      else
-        nil
-      end
-    end
-
-    def normalize_memory_name(raw)
-      v = raw.to_s.strip
-      return nil if v.empty?
-
-      # basename without .md, handle comma already split
-      base = File.basename(v, ".md").strip
-      base.empty? ? nil : base
-    end
-
-    # A memory read (memory_read, or read of a memories/*.md file) as it
-    # starts: its names join used_memory_names.
-    # @return [Array<String>, nil] the names this call read, nil for any other event
-    def capture_used_memory_from_event(event)
-      return unless event.is_a?(Hash) && event[:type] == :tool_call_started
-
-      call = event[:call].is_a?(Hash) ? event[:call] : {}
-      names = memory_name_from_tool_call(call)
-      # A refused read of a muted memory is not a use of it.
-      names = Array(names).reject { |n| memory_muted?(n) }
-      return if names.empty?
-
-      add_used_memory_names(names)
-      names
-    end
-
     # ── Guardrails ─────────────────────────────────────────────────────────────
 
     # Who can answer an approval: :repl, :worker or :non_interactive (the
@@ -1132,7 +987,7 @@ module Samagotchi
 
     # The metrics load the session's saved records from its state dir, once.
     def bind_metrics(session)
-      return unless session.respond_to?(:id) && session.id
+      return unless session&.id
 
       @metrics.state_dir = session_state_dir
       @metrics.session_id = session.id
@@ -1222,6 +1077,38 @@ module Samagotchi
     end
     private :record_last_turn
 
+    # How every turn ends (completed, canceled, failed): the session gets
+    # what the turn kept, goes idle and records the ending, and the end
+    # event is announced, as one step of the event log (a snapshot taken
+    # meanwhile, the Bridge's, shows the turn either in progress or in the
+    # messages, never both or neither). Then the metrics are persisted.
+    # The block runs in that step with the turn's seconds, once, and
+    # returns [the messages to keep (nil: leave the session's), the end
+    # event]. +save:+ also saves the session (a failed turn: a worker exits
+    # after it). The disk writes come after the step: every emitter waits
+    # for the event lock.
+    def end_turn(turn, outcome, save: false)
+      seconds = turn.elapsed
+      synchronize_events do
+        kept, event = yield(seconds)
+        replace_session_messages(turn.session, kept) if kept
+        turn.session.status = Session::STATUS_IDLE
+        record_last_turn(turn.session, outcome, seconds, turn.origin)
+        emit_event(turn.on_event, turn.tag(event))
+      end
+      turn.ended = true
+      save_quietly(turn.session) if save
+      @metrics.persist(state_dir: session_state_dir)
+    end
+    private :end_turn
+
+    def save_quietly(session)
+      session.save(state_dir: session_state_dir)
+    rescue StandardError
+      nil
+    end
+    private :save_quietly
+
     # Keep what the after_turn hooks presented as the answer's `display`
     # and tell the observers (:answer_display), after the turn_completed
     # they already had: the web re-reads the answer then. A turn_completed
@@ -1275,11 +1162,7 @@ module Samagotchi
       notice = { type: :hook_notice, hook: hook.to_s, text: text.to_s, level: level }
       return hold_load_event(notice) && nil if @loading_plugins
 
-      sink = nil
-      in_turn = @activity_mutex.synchronize do
-        sink = @turn_event_sink
-        @turn_running
-      end
+      in_turn, sink = @turn_state.in_turn_sink
       if anytime_thread?
         announce_anytime(notice.merge(between_turns: true))
       elsif current_init_task
@@ -1356,8 +1239,8 @@ module Samagotchi
 
     # Answer the pending question (called from UI thread; QuestionDesk#answer).
     # @return [Hash] normalized answer
-    def answer_question(id:, selected:, freeform: nil)
-      @question_desk.answer(id: id, selected: selected, freeform: freeform)
+    def answer_question(id:, selected:, freeform: nil, client_id: nil)
+      @question_desk.answer(id: id, selected: selected, freeform: freeform, client_id: client_id)
     end
 
     def set_question_sync_handler(&block)
@@ -1420,10 +1303,10 @@ module Samagotchi
     def session=(session)
       @session = session
       # One session per REPL/worker process: its records carry this sid.
-      Log.session_id = session.id if session.respond_to?(:id) && session.id
+      Log.session_id = session.id if session&.id
       # A woken worker's /stats and status line count the turns before it.
       bind_metrics(session)
-      sync_used_memories_from_session(session)
+      @used_memories.absorb(session)
     end
 
     # @return [IdleRecap, nil] the idle recap detector, or nil when disabled
@@ -1451,7 +1334,7 @@ module Samagotchi
       state = @recap&.state
       return nil unless state
 
-      messages = @activity_mutex.synchronize { @session&.messages } || []
+      messages = @session&.messages || []
       covered = state[:covered].to_i
       turns_since = Array(messages).drop(covered).count { |m| Steer.turn_prompt?(m) }
       { text: state[:text], covered: covered, turns_since: turns_since, created_at: state[:created_at] }
@@ -1473,10 +1356,27 @@ module Samagotchi
       self
     end
 
+    # One turn's values, for #run_turn and its endings. Per turn and
+    # single-threaded: the cross-thread turn state (the cancel slot, the
+    # sink, steers) stays on the Engine.
+    # +ended+: the end event is out (what follows is post-turn work).
+    # +settings+: the kernel's LLM::TurnSettings, made in #prepare_turn and
+    # set on the kernel in #generate.
+    Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
+                      :settings) do
+      # The turn's boundary events carry the origin only when there is one,
+      # so payloads stay unchanged for callers that don't pass it.
+      def tag(event) = origin ? event.merge(origin: origin) : event
+
+      # Seconds since the turn started (the cancel note says how long it ran).
+      def elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+    end
+    private_constant :Turn
+
     # Run a single turn with event emission.
     #
     # Builds the system prompt + user messages, runs the kernel loop with
-    # event forwarding, and returns a KernelLoop::Result.
+    # event forwarding, and returns its LLM::ModelResult.
     #
     # @param session  [Session] the session to operate on
     # @param prompt   [String] user input
@@ -1485,7 +1385,7 @@ module Samagotchi
     # @param cancel_controller [CancellationController, nil]
     # @param max_tool_output_chars [Integer, nil] per-output char cap for the
     #   :tool_call_completed event's `output:` (nil → max_tool_output_chars)
-    # @return [KernelLoop::Result]
+    # @return [LLM::ModelResult]
     # @param pending_input [#call, nil] optional drain proc returning
     #   Array<String> of steering messages queued while the turn runs; drained
     #   by the agentic loop at iteration boundaries (see KernelLoop#run).
@@ -1504,283 +1404,365 @@ module Samagotchi
     #
     # An Interrupt (SIGINT) cancels the turn: the pre-turn conversation plus
     # the prompt is kept in the session and :turn_canceled is emitted, then the
-    # Interrupt is re-raised so the caller still decides whether to exit. Any
+    # Interrupt is re-raised so the caller still decides whether to exit. One
+    # after the turn's end event (in its after_turn/session_end hooks) is
+    # only re-raised: the turn already ended; so is any error there. Any
     # other error (e.g. an LLM::ProviderError) emits :turn_failed and
     # re-raises; a provider error adds error_kind:, retryable:, host: and a
     # one-line summary:.
     def run_turn(session, prompt, on_event: nil, max_iterations: 100, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
                  images: [])
+      turn = begin_turn(session, prompt, on_event: on_event, cancel_controller: cancel_controller, origin: origin,
+                                         continue: continue)
+      begin
+        # A Stop cuts the /props probes this thread makes for the turn
+        # (window, served model, vision) instead of waiting their timeout.
+        probe_cancel_before = Client.swap_probe_cancel(turn.controller)
+        return stopped_before_model(turn) unless prepare_turn(turn, continue ? [] : images)
+
+        result = generate(turn, max_iterations: max_iterations, max_tool_output_chars: max_tool_output_chars,
+                                pending_input: pending_input)
+        publish_used_memories(session, on_event)
+        complete_turn(turn, result)
+        result
+      rescue Interrupt
+        # After the end event (in the after_turn/session_end hooks) the
+        # turn is over: no second ending, the answer stays.
+        raise if turn.ended
+
+        turn.controller.cancel!(:ctrl_c)
+        end_turn(turn, "canceled") do |seconds|
+          [ctrl_c_messages(turn, seconds), { type: :turn_canceled, cancellation_reason: :ctrl_c, duration_ms: (seconds * 1000).round }]
+        end
+        raise
+      rescue StandardError => e
+        # After the end event (post-turn work) likewise: logged and
+        # re-raised, no turn_failed over the turn that ended.
+        if turn.ended
+          Log.warn(:turn, "post_turn_error", error: "#{e.class}: #{e.message}")
+          raise
+        end
+
+        # Keep what the turn got to (the prompt plus the loop's completed
+        # tool iterations) like a cancel does, and save it: a worker exits
+        # after a failed turn. The REPL still rolls back to its checkpoint.
+        end_turn(turn, "failed", save: true) { |seconds| [failed_messages(turn, e), failed_event(e, seconds)] }
+        raise
+      ensure
+        release_turn(probe_cancel_before)
+      end
+    end
+
+    # The turn's state before anything can fail it: the session running,
+    # the turn flag, its cancel controller and sink. The cross-thread state
+    # is set here and cleared in #release_turn only.
+    def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:)
       # Track the active session for recap and status snapshot.
       @session = session
       # status is turn state: running now, idle again before the turn's end
       # is announced, so a UI reacting to that event reads the new state.
       session.status = Session::STATUS_RUNNING
-      sync_used_memories_from_session(session)
-      # Mark the turn running before generating so the idle recap detector does
-      # not fire (or render an invalidated recap) while the model is working,
-      # and drop a recap already in flight: the turn makes it stale.
-      set_turn_running(true)
+      @used_memories.absorb(session)
+      # Provide a cancellable controller for this turn (cross-process cancel via file flag)
+      effective_controller = cancel_controller || CancellationController.new
+      # The turn runs, with its controller and sink, in one step: a Stop
+      # or a plugin's card from another thread never sees a running turn
+      # without them. The idle recap detector does not fire (or render an
+      # invalidated recap) while the model is working. A hook's notice goes
+      # where the turn's events go (the REPL renders only its sink; a
+      # worker's observers carry it to the bridge).
+      @turn_state.begin!(controller: effective_controller, sink: on_event)
+      # Drop a recap already in flight: the turn makes it stale.
       @recap&.invalidate!
+      # The gate's context: who queued this turn, and git asked afresh.
+      @guardrail_wiring.begin_turn(origin)
+
+      Turn.new(session: session, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
+               controller: effective_controller, origin: origin, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC))
+    end
+    private :begin_turn
+
+    # Everything before the model is asked: :turn_started, the kernel's
+    # per-turn settings, the plugins' setup, the session_start/before_turn
+    # hooks, then the messages to send (#turn_messages). False when a Stop
+    # came before the hooks (the turn ends canceled there; before the
+    # load-failure warnings when it came during the probes), else true.
+    def prepare_turn(turn, images)
+      session = turn.session
+      image_refs, image_error = turn_image_refs(session, images)
+      # Emit turn_started event
+      bind_metrics(session)
+      turn_started = { type: :turn_started, session_id: session.id, prompt: turn.prompt }
+      turn_started[:continue] = true if turn.continue
+      turn_started[:images] = image_refs unless image_refs.empty?
+      emit_event(turn.on_event, turn.tag(turn_started))
+      raise image_error if image_error
+
       # Ask the server for its window again each turn (one short /props GET,
       # cached across the turn's generations): a restart with another -c
-      # between turns raises no error that would drop the cache.
-      @client.invalidate_context_window! if @client.respond_to?(:invalidate_context_window!)
+      # between turns raises no error that would drop the cache. The
+      # profile may probe too (a first turn, a retry). Both run after
+      # run_turn's probe-cancel swap, so a Stop cuts them, and a failure
+      # ends the turn as turn_failed.
+      @client.invalidate_context_window!
       refresh_profile!
-      # Provide a cancellable controller for this turn (cross-process cancel via file flag)
-      effective_controller = cancel_controller || CancellationController.new
-      @activity_mutex.synchronize do
-        @active_cancel_controller = effective_controller
-        # A hook's notice goes where the turn's events go (the REPL renders
-        # only its sink; a worker's observers carry it to the bridge).
-        @turn_event_sink = on_event
+
+      # Before anything of the turn is kept or a reminder is used up.
+      turn.settings = turn_settings(session)
+      refuse_images!(turn.settings.vision) unless image_refs.empty?
+      # A Stop during the probes: the turn ends before the load-failure
+      # warnings, which show once, so the next turn still shows them.
+      return false if turn.controller.cancelled?
+
+      announce_guardrail_failures(turn.on_event)
+      # Plugins' slow setup that brings tools (an MCP server's first
+      # start): the turn waits for it here, before the system prompt
+      # declares the tools; a Ctrl-C ends the wait (the turn is cancelled
+      # at its first request).
+      start_init_tasks!
+      await_init_tasks(turn.controller, turn.on_event)
+      # Plugins' tool sets that changed since the last turn.
+      apply_staged_tools!
+      # A Stop during the wait above: the turn ends here,
+      # before the hooks run or a reminder is used up.
+      return false if turn.controller.cancelled?
+
+      # Fire :session_start on the very first turn
+      if @first_turn
+        @hooks.fire(:session_start, { type: :session_start, session_id: session.id })
+        @first_turn = false
       end
-      # The gate's context: who queued this turn, and git asked afresh.
-      @guardrail_wiring.begin_turn(origin)
 
-      prompt = nil if continue
-      # For the cancel note: how long the turn ran.
-      turn_started_clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      turn_seconds = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) - turn_started_clock }
-      messages = nil
-      # Boundary events carry the origin only when there is one, so payloads
-      # stay unchanged for callers that don't pass it.
-      with_origin = origin ? ->(event) { event.merge(origin: origin) } : ->(event) { event }
-      begin
-        # A Stop cuts the /props probes this thread makes for the turn
-        # (window, served model, vision) instead of waiting their timeout.
-        probe_cancel_before = Client.swap_probe_cancel(effective_controller)
-        image_refs, image_error = turn_image_refs(session, continue ? [] : images)
-        # Emit turn_started event
-        bind_metrics(session)
-        turn_started = { type: :turn_started, session_id: session.id, prompt: prompt }
-        turn_started[:continue] = true if continue
-        turn_started[:images] = image_refs unless image_refs.empty?
-        emit_event(on_event, with_origin.call(turn_started))
-        raise image_error if image_error
-
-        # Before anything of the turn is kept or a reminder is used up.
-        vision = turn_vision(session)
-        @kernel.vision = vision if @kernel.respond_to?(:vision=)
-        @kernel.sampling = turn_sampling if @kernel.respond_to?(:sampling=)
-        thinking_target = @host_registry.resolve(@effective_model_name)
-        @turn_thinking = [thinking_level(thinking_target), thinking_target]
-        @kernel.thinking = @turn_thinking.first if @kernel.respond_to?(:thinking=)
-        announce_thinking_level(*@turn_thinking)
-        refuse_images!(vision) unless image_refs.empty?
-        announce_guardrail_failures(on_event)
-        # Plugins' slow setup that brings tools (an MCP server's first
-        # start): the turn waits for it here, before the system prompt
-        # declares the tools; a Ctrl-C ends the wait (the turn is cancelled
-        # at its first request).
-        start_init_tasks!
-        await_init_tasks(effective_controller, on_event)
-        # Plugins' tool sets that changed since the last turn.
-        apply_staged_tools!
-
-        # Fire :session_start on the very first turn
-        if @first_turn
-          @hooks.fire(:session_start, { type: :session_start, session_id: session.id })
-          @first_turn = false
-        end
+      # Fire :before_turn hook, with a read-only copy of the history so far
+      # and the prompt (nil on a continue).
+      @hooks.fire(:before_turn, { type: :before_turn, session_id: session.id, prompt: turn.prompt,
+                                  messages: hook_messages(session.messages) })
 
-        # Fire :before_turn hook, with a read-only copy of the history so far
-        # and the prompt (nil on a continue).
-        @hooks.fire(:before_turn, { type: :before_turn, session_id: session.id, prompt: prompt,
-                                    messages: hook_messages(session.messages) })
-
-        messages = session.messages.dup
-        # Built once per Engine (and again after a model switch) so the prompt
-        # prefix, and the model server's KV cache for it, stay stable.
-        messages = ContextNote.with_system_head(messages, { role: "system", content: system_prompt })
-        # Explicit --memory preloads are now known after system prompt build.
-        add_used_memory_names(activated_memory_names)
-        sync_used_memories_from_session(session)
-
-        # Inject due reminders as a tail system message (after history, before
-        # the new user prompt) to preserve prefix KV cache. Mutating the head
-        # system prompt invalidates cache for the entire prefix.
-        due_reminders = collect_due_reminders(messages)
-        if due_reminders.any?
-          emit_event(on_event, {
-            type: :reminder_injected,
-            reminders: due_reminders
-          })
-        end
+      turn_messages(turn, image_refs)
+      true
+    end
+    private :prepare_turn
 
-        unless continue
-          user_message = { role: "user", content: prompt }
-          user_message[:images] = image_refs unless image_refs.empty?
-          messages << user_message
-          session.last_prompt = prompt
-        end
+    # A turn stopped before the model was asked (#prepare_turn returned
+    # false): canceled with nothing kept, like a Ctrl-C there; the result
+    # has no conversation, so a UI's checkpoint stands.
+    def stopped_before_model(turn)
+      reason = turn.controller.reason
+      end_turn(turn, "canceled") do |seconds|
+        [nil, { type: :turn_canceled, cancellation_reason: reason, duration_ms: (seconds * 1000).round }]
+      end
+      LLM::ModelResult.new(text: "", canceled: true, cancellation_reason: reason)
+    end
+    private :stopped_before_model
+
+    # The turn's settings for the kernel (LLM::TurnSettings): vision,
+    # sampling and thinking, the thinking resolved before the hooks run.
+    # The model name is added in #generate, after the hooks that may switch
+    # the model.
+    def turn_settings(session)
+      vision = turn_vision(session)
+      sampling = turn_sampling
+      thinking_target = @host_registry.resolve(@effective_model_name)
+      @turn_thinking = [thinking_level(thinking_target), thinking_target]
+      announce_thinking_level(*@turn_thinking)
+      LLM::TurnSettings.new(vision: vision, sampling: sampling, thinking: @turn_thinking.first, model_name: nil)
+    end
+    private :turn_settings
+
+    # The messages the turn sends: the history under the system head, due
+    # reminders, the prompt. turn.messages is set first and grown in place,
+    # so a Ctrl-C or a failure meanwhile keeps what is there.
+    def turn_messages(turn, image_refs)
+      session = turn.session
+      turn.messages = session.messages.dup
+      # Built once per Engine (and again after a model switch) so the prompt
+      # prefix, and the model server's KV cache for it, stay stable.
+      turn.messages = ContextNote.with_system_head(turn.messages, { role: "system", content: system_prompt })
+      # Explicit --memory preloads are now known after system prompt build.
+      @used_memories.add(activated_memory_names).absorb(session)
+
+      # Inject due reminders as a tail system message (after history, before
+      # the new user prompt) to preserve prefix KV cache. Mutating the head
+      # system prompt invalidates cache for the entire prefix.
+      due_reminders = @reminder_queue.inject!(turn.messages)
+      if due_reminders.any?
+        emit_event(turn.on_event, {
+          type: :reminder_injected,
+          reminders: due_reminders
+        })
+      end
 
-        sync_kernel_client!
-        # Route model name as bare (without host prefix) to the transport;
-        # host selection already done via active client.
-        bare_for_backend = bare_model_name(@effective_model_name)
-        # The chat loop dispatches tools through the kernel without its #run:
-        # tag those dumps with this turn's model, not the last native one.
-        @kernel.current_model_name = bare_for_backend if @kernel.respond_to?(:current_model_name=)
-
-        result = backend.complete(
-          messages: messages,
-          max_iterations: @no_interrupt ? NO_INTERRUPT_MAX_ITERATIONS : max_iterations,
-          on_stream_event: build_stream_event_handler(on_event, cancel_controller: effective_controller),
-          cancel_controller: effective_controller,
-          model_name: bare_for_backend,
-          max_tool_output_chars: max_tool_output_chars,
-          pending_input: turn_drain(pending_input)
-        )
-
-        # Persist deduped used memories onto the session for Web + reload.
-        begin
-          session.used_memory_names = used_memory_names
-        rescue StandardError
-          nil
-        end
-        # Notify live observers of the updated memory list (so yellow bar refreshes
-        # even without a tool_call event if the preload was the only addition).
-        # Only emit when there is something to report to avoid noisy event_count drift.
-        if used_memory_names.any?
-          begin
-            emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names })
-          rescue StandardError
-            nil
-          end
-        end
+      return if turn.continue
 
-        response = result.respond_to?(:output) ? result.output.to_s : result.to_s
-        canceled = result.respond_to?(:canceled?) && result.canceled?
-        conversation = result.conversation if result.respond_to?(:conversation) && result.conversation.is_a?(Array)
-        # Bring the turn into the session and announce its end as one step of
-        # the event log: a snapshot taken meanwhile (the Bridge's) shows the
-        # turn either in progress or in the messages, never both or neither.
-        # A turn that ran out of iterations ends at its tool results, so a
-        # continue resumes from them rather than after a made-up reply.
-        resumable = result.respond_to?(:resumable?) && result.resumable?
-        # Nothing visible (the native loop: no text; the chat loop: its
-        # placeholder text) is a turn the model should know ended that way.
-        empty = !canceled && !resumable &&
-                (response.strip.empty? || (result.respond_to?(:empty_answer?) && result.empty_answer?))
-        # after_turn hooks run below and may present the answer (the web
-        # holds its pop until it knows).
-        display_pending = !canceled && @hooks.any?(:after_turn)
-        synchronize_events do
-          if empty
-            # The placeholder is for the UIs (a new array: it must not leak
-            # into the result); the note is for the model, so it goes on the
-            # result's conversation too, which the REPL keeps as-is.
-            # A retry's nudge at the tail goes: this note says it all.
-            note = TurnNote.empty
-            conversation&.replace(TurnNote.without_trailing(conversation))
-            saved = TurnNote.without_trailing(conversation || session.messages)
-            saved << { role: "model", content: "[No response]" } if response.strip.empty?
-            replace_session_messages(session, saved + [note])
-            conversation << note if conversation
-          elsif canceled && conversation
-            conversation << TurnNote.cancelled(result.cancellation_reason, seconds: turn_seconds.call,
-                                                                          stopped_by: effective_controller.detail,
-                                                                          shown: TurnNote.interrupted_tail?(conversation),
-                                                                          running_tasks: Tools::TaskRuntime.running_created_in(conversation))
-            replace_session_messages(session, conversation)
-          elsif conversation
-            replace_session_messages(session, conversation)
-          end
-          session.status = Session::STATUS_IDLE
-          record_last_turn(session, canceled ? "canceled" : "completed", turn_seconds.call, origin)
-          if canceled
-            emit_event(on_event, with_origin.call({
-              type: :turn_canceled,
-              cancellation_reason: result.cancellation_reason,
-              duration_ms: (turn_seconds.call * 1000).round
-            }))
-          else
-            # For a client that attaches later (session_state_snapshot).
-            @last_context_status = result.context_status.dup if result.context_status
-            emit_event(on_event, with_origin.call({
-              type: :turn_completed,
-              result: result,
-              turn_summary: turn_summary(result),
-              display_pending: display_pending
-            }))
-          end
-        end
-        @metrics.persist(state_dir: session_state_dir)
+      user_message = { role: "user", content: turn.prompt }
+      user_message[:images] = image_refs unless image_refs.empty?
+      turn.messages << user_message
+      session.last_prompt = turn.prompt
+    end
+    private :turn_messages
 
-        # Fire :after_turn hook (runs even on cancel/success), with a read-only
-        # copy of the conversation the turn stored, and event[:present] for
-        # a display version of the answer (AnswerDisplay).
-        display = AnswerDisplay.new(session.messages)
-        after_turn = { type: :after_turn, status: canceled ? "canceled" : "completed",
-                       messages: hook_messages(session.messages) }
-        after_turn[:present] = display.presenter(after_turn)
-        @hooks.fire(:after_turn, after_turn)
-        store_answer_display(session, display, pending: display_pending)
+    # Ask the effective model's backend.
+    def generate(turn, max_iterations:, max_tool_output_chars:, pending_input:)
+      sync_kernel_client!
+      # Route model name as bare (without host prefix) to the transport;
+      # host selection already done via active client.
+      bare_for_backend = bare_model_name(@effective_model_name)
+      # The turn's settings, set once here. The chat loop dispatches tools
+      # through the kernel without its #run: tag those dumps with this
+      # turn's model, not the last native one.
+      @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend)
+
+      backend.complete(
+        messages: turn.messages,
+        max_iterations: @no_interrupt ? NO_INTERRUPT_MAX_ITERATIONS : max_iterations,
+        on_stream_event: build_stream_event_handler(turn.on_event, cancel_controller: turn.controller),
+        cancel_controller: turn.controller,
+        model_name: bare_for_backend,
+        max_tool_output_chars: max_tool_output_chars,
+        pending_input: turn_drain(pending_input)
+      )
+    end
+    private :generate
 
-        # Fire :session_end after every turn (turn-level lifecycle)
-        @hooks.fire(:session_end, { type: :session_end, session_id: session.id })
+    def publish_used_memories(session, on_event)
+      # Persist deduped used memories onto the session for Web + reload.
+      begin
+        session.used_memory_names = used_memory_names
+      rescue StandardError
+        nil
+      end
+      # Notify live observers of the updated memory list (so yellow bar refreshes
+      # even without a tool_call event if the preload was the only addition).
+      # Only emit when there is something to report to avoid noisy event_count drift.
+      return unless used_memory_names.any?
 
-        result
-      rescue Interrupt
-        effective_controller.cancel!(:ctrl_c)
-        synchronize_events do
-          # Only the pre-turn messages survive here, so tasks this turn
-          # started are missed (plan wait-stop §6).
-          if messages
-            note = TurnNote.cancelled(:ctrl_c, seconds: turn_seconds.call,
-                                               running_tasks: Tools::TaskRuntime.running_created_in(messages))
-            replace_session_messages(session, TurnNote.replace_trailing(messages, note))
-          end
-          session.status = Session::STATUS_IDLE
-          record_last_turn(session, "canceled", turn_seconds.call, origin)
-          emit_event(on_event, with_origin.call({ type: :turn_canceled, cancellation_reason: :ctrl_c,
-                                                   duration_ms: (turn_seconds.call * 1000).round }))
-        end
-        @metrics.persist(state_dir: session_state_dir)
-        raise
-      rescue StandardError => e
-        # Keep what the turn got to (the prompt plus the loop's completed
-        # tool iterations) like a cancel does, and save it: a worker exits
-        # after a failed turn. The REPL still rolls back to its checkpoint.
-        kept = e.respond_to?(:partial_conversation) && e.partial_conversation.is_a?(Array) ? e.partial_conversation : messages
-        # The model reads why on its next turn (a UI that rolls the turn back
-        # leaves its own note, TurnFlow#prompt_turn_failed). Nothing when the
-        # turn never reached the model (kept is nil).
-        if kept
-          summary = e.respond_to?(:summary) ? e.summary : e.message
-          kept = TurnNote.replace_trailing(kept, TurnNote.failed(summary, continued: continue))
-        end
-        replace_session_messages(session, kept) if kept
-        session.status = Session::STATUS_IDLE
-        record_last_turn(session, "failed", turn_seconds.call, origin)
-        begin; session.save(state_dir: session_state_dir); rescue StandardError; nil; end
-        failed = { type: :turn_failed, error_class: e.class.name, message: e.message,
-                   duration_ms: (turn_seconds.call * 1000).round }
-        # A provider error says what kind it is, for one line per kind in the UIs.
-        if e.is_a?(LLM::ProviderError)
-          failed.merge!(error_kind: e.kind, retryable: e.retryable?, host: e.host, summary: e.summary)
-        end
-        emit_event(on_event, with_origin.call(failed))
-        @metrics.persist(state_dir: session_state_dir)
-        raise
-      ensure
-        # A completed turn is activity: release the turn flag and advance the
-        # shared inactivity clock so the idle recap detector (shared with the REPL)
-        # treats the just-finished turn as activity and re-arms its window.
-        # Always runs, even if an exception occurred.
-        set_turn_running(false)
-        Client.swap_probe_cancel(probe_cancel_before)
-        left = @activity_mutex.synchronize do
-          @active_cancel_controller = nil
-          @turn_event_sink = nil
-          @steers.tap { @steers = [] }
+      begin
+        emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names })
+      rescue StandardError
+        nil
+      end
+    end
+    private :publish_used_memories
+
+    # The normal ending (an answer, an empty answer, a Stop, the iteration
+    # limit), then the after-turn hooks.
+    def complete_turn(turn, result)
+      canceled = result.canceled?
+      # after_turn hooks run below and may present the answer (the web
+      # holds its pop until it knows).
+      display_pending = !canceled && @hooks.any?(:after_turn)
+      end_turn(turn, canceled ? "canceled" : "completed") do |seconds|
+        kept = kept_messages(turn, result, seconds)
+        if canceled
+          [kept, { type: :turn_canceled, cancellation_reason: result.cancellation_reason,
+                   duration_ms: (seconds * 1000).round }]
+        else
+          # For a client that attaches later (session_state_snapshot).
+          @last_context_status = result.context_status.dup if result.context_status
+          [kept, { type: :turn_completed, result: result, turn_summary: turn_summary(result),
+                   display_pending: display_pending }]
         end
-        log_dropped_steers(left, "turn_ended")
-        record_activity
-        # Clear hooks so they remain turn-scoped and never leak into the next turn.
-        clear_hooks
+      end
+
+      # Fire :after_turn hook (an answer or a Stop; an Interrupt or a failure
+      # ends the turn in #run_turn without it), with a read-only
+      # copy of the conversation the turn stored, and event[:present] for
+      # a display version of the answer (AnswerDisplay).
+      session = turn.session
+      display = AnswerDisplay.new(session.messages)
+      after_turn = { type: :after_turn, status: canceled ? "canceled" : "completed",
+                     messages: hook_messages(session.messages) }
+      after_turn[:present] = display.presenter(after_turn)
+      @hooks.fire(:after_turn, after_turn)
+      store_answer_display(session, display, pending: display_pending)
+
+      # Fire :session_end after the turn (turn-level lifecycle), as :after_turn
+      @hooks.fire(:session_end, { type: :session_end, session_id: session.id })
+    end
+    private :complete_turn
+
+    # What the session keeps of a turn that ended normally (nil: nothing to
+    # replace). Runs under the event lock: it also adds the turn's note to
+    # result.conversation, which the REPL keeps as-is.
+    # A turn that ran out of iterations ends at its tool results, so a
+    # continue resumes from them rather than after a made-up reply.
+    def kept_messages(turn, result, seconds)
+      conversation = result.conversation if result.conversation.is_a?(Array)
+      # Nothing visible (the native loop: no text; the chat loop: its
+      # placeholder text) is a turn the model should know ended that way.
+      if result.empty_answer?
+        # The placeholder is for the UIs (a new array: it must not leak
+        # into the result); the note is for the model, so it goes on the
+        # result's conversation too.
+        # A retry's nudge at the tail goes: this note says it all.
+        note = TurnNote.empty
+        conversation&.replace(TurnNote.without_trailing(conversation))
+        saved = TurnNote.without_trailing(conversation || turn.session.messages)
+        saved << { role: "model", content: "[No response]" } if result.output.to_s.strip.empty?
+        conversation << note if conversation
+        saved + [note]
+      elsif result.canceled? && conversation
+        conversation << TurnNote.cancelled(result.cancellation_reason, seconds: seconds,
+                                                                      stopped_by: turn.controller.detail,
+                                                                      shown: TurnNote.interrupted_tail?(conversation),
+                                                                      running_tasks: Tools::TaskRuntime.running_created_in(conversation))
+      else
+        conversation
       end
     end
+    private :kept_messages
+
+    # A Ctrl-C keeps the turn's messages so far with a cancel note (nil
+    # before there are any). Only the pre-turn messages survive here, so
+    # tasks this turn started are missed (plan wait-stop §6).
+    def ctrl_c_messages(turn, seconds)
+      return nil unless turn.messages
+
+      note = TurnNote.cancelled(:ctrl_c, seconds: seconds, running_tasks: Tools::TaskRuntime.running_created_in(turn.messages))
+      TurnNote.replace_trailing(turn.messages, note)
+    end
+    private :ctrl_c_messages
+
+    # A failure keeps the loop's partial conversation (else the turn's
+    # messages so far) with a failed note; nil when the turn never reached
+    # the model. The model reads why on its next turn (a UI that rolls the
+    # turn back leaves its own note, TurnFlow#prompt_turn_failed).
+    def failed_messages(turn, error)
+      kept = error.respond_to?(:partial_conversation) && error.partial_conversation.is_a?(Array) ? error.partial_conversation : turn.messages
+      return nil unless kept
+
+      summary = error.respond_to?(:summary) ? error.summary : error.message
+      TurnNote.replace_trailing(kept, TurnNote.failed(summary, continued: turn.continue))
+    end
+    private :failed_messages
+
+    def failed_event(error, seconds)
+      failed = { type: :turn_failed, error_class: error.class.name, message: error.message,
+                 duration_ms: (seconds * 1000).round }
+      # A provider error says what kind it is, for one line per kind in the UIs.
+      if error.is_a?(LLM::ProviderError)
+        failed.merge!(error_kind: error.kind, retryable: error.retryable?, host: error.host, summary: error.summary)
+      end
+      failed
+    end
+    private :failed_event
+
+    # However the turn ended (#run_turn's ensure): the turn flag off, the
+    # probe cancel restored, the cancel controller, sink and steers cleared
+    # (a steer left is logged as dropped), activity recorded, the
+    # turn-scoped hooks cleared.
+    def release_turn(probe_cancel_before)
+      # A completed turn is activity: release the turn flag and advance the
+      # shared inactivity clock so the idle recap detector (shared with the REPL)
+      # treats the just-finished turn as activity and re-arms its window.
+      left = @turn_state.finish!
+      Client.swap_probe_cancel(probe_cancel_before)
+      log_dropped_steers(left, "turn_ended")
+      record_activity
+      # Clear hooks so they remain turn-scoped and never leak into the next turn.
+      clear_hooks
+    end
+    private :release_turn
 
     # [refs, nil] for a turn's images, or [[], error] when one can't be used
     # (the turn then fails right after :turn_started).
@@ -1839,7 +1821,7 @@ module Samagotchi
       return unless target&.entry&.chat? && Thinking::EFFORTS.include?(level)
 
       client = target.client
-      props = client.respond_to?(:cached_server_props) ? client.cached_server_props(model: target.bare_model) : nil
+      props = client.cached_server_props(model: target.bare_model)
       return unless Thinking.effort_ignored?(level, props)
 
       thinking_notice_once(:unsupported, target, :info,
@@ -1964,8 +1946,16 @@ module Samagotchi
 
     private
 
+    # The one named seam for replacing a session's conversation (the
+    # array is replaced, never mutated in place). No lock: a reader gets
+    # the old array or the new one, and both are whole.
+    # The turn as other threads see it (TurnState).
+    attr_reader :turn_state
+    # The due reminders on their way into a turn (ReminderQueue).
+    attr_reader :reminder_queue
+
     def replace_session_messages(session, messages)
-      @activity_mutex.synchronize { session.messages = messages }
+      session.messages = messages
     end
 
     # Pick the loop for a target; the chat loop is pointed at the target
@@ -2008,7 +1998,8 @@ module Samagotchi
         end
         begin
           Hooks::BundleLoader.load(bundle_name: bundle_name, hooks_dir: hooks_dir, metadata: data[:hooks], registry: @hooks,
-                                   failures: @guardrail_failures, settings: settings[bundle_name.to_s] || {})
+                                   failures: @guardrail_failures, settings: settings[bundle_name.to_s] || {},
+                                   requires_chi: data[:requires_chi])
         rescue Exception => e
           Log.error(:hooks, "bundle_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' failed to load hooks: #{e.class}: #{e.message}", bundle: bundle_name, error: e.class.name)
         end
@@ -2081,11 +2072,9 @@ module Samagotchi
         ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:|
           hook_ask_user(question, options, header, allow_freeform, hook)
         },
-        # Nothing to cancel while the Engine is still being built (a
-        # server that starts as its plugin loads).
         # An init task's is its own (a Ctrl-C ends a turn, not the task).
         cancelled: lambda {
-          (task = current_init_task) ? task.cancelled? : @activity_mutex && active_cancel_controller&.cancelled?
+          (task = current_init_task) ? task.cancelled? : active_cancel_controller&.cancelled?
         },
         card: ->(**card) { show_card(**card) },
         steer: ->(text, label) { steer(text, source: hook_source(label)) },
@@ -2159,7 +2148,7 @@ module Samagotchi
       @auto_turn_callback = auto_turn_callback
       IdleReminders.new(
         engine: self,
-        reminder_store: @reminder_store,
+        queue: @reminder_queue,
         callback: @auto_turn_callback
       )
     end
@@ -2221,7 +2210,7 @@ module Samagotchi
     def emit_event(on_event, event)
       # Capture used memories synchronously in the turn thread.
       read_names = begin
-        capture_used_memory_from_event(event)
+        @used_memories.capture(event, muted: @muted_memory_names)
       rescue StandardError
         nil
       end
@@ -2253,7 +2242,7 @@ module Samagotchi
       adapter = nil
       if target.entry.chat?
         adapter = @host_registry.adapter_for(target.entry)
-        client = nil if adapter.respond_to?(:remote?) && adapter.remote?
+        client = nil if adapter.remote?
       end
       ContextWindow.resolve(client: client, model: target.bare_model, adapter: adapter)
     rescue StandardError
@@ -2271,9 +2260,9 @@ module Samagotchi
       client = target.client
       if target.entry.chat?
         adapter = @host_registry.adapter_for(target.entry)
-        return [nil, nil] if adapter.respond_to?(:remote?) && adapter.remote?
+        return [nil, nil] if adapter.remote?
       end
-      served = ServedModel.from_props(client.server_props(model: target.bare_model)) if client.respond_to?(:server_props)
+      served = ServedModel.from_props(client.server_props(model: target.bare_model))
       served ? [served, asked] : [nil, nil]
     rescue StandardError
       [nil, nil]
@@ -2300,7 +2289,7 @@ module Samagotchi
     # prompt format and parser, and the system prompts built for the old one.
     def apply_profile(resolution)
       @prompt_builder&.reset! if @profile_resolution && @profile_resolution.profile.name != resolution.profile.name
-      @kernel.use_profile!(resolution) if @kernel.respond_to?(:use_profile!)
+      @kernel.use_profile!(resolution)
       resolution
     end