samagotchi 0.154.0 → 0.155.0

data/lib/samagotchi/engine/verify.rb

@@ -2,152 +2,16 @@
 
 module Samagotchi
   class Engine
-    # Verify and Revise anchors at a turn's end: the opening's stamp, a Revise
-    # turn's draft checked, a Verify turn's quote checked against its source
-    # session and its verdict recorded. No ivars of its own: it reads the turn,
-    # and the sessions it loads through Engine methods.
+    # Verify and Revise anchors (TurnStages::VerifyAnchors): #begin_turn
+    # checks a Verify turn's claim, #end_turn's event step stamps the opening
+    # and records the verdict. Reads @verify_anchors.
     module VerifyPart
-      # The turn's anchors, stamped on its opening message (the prompt, or a
-      # wake turn's note) in the messages it keeps: display metadata, never
-      # in the prompt (LLM::ChatLoop#plain keeps them, no wire sends them).
-      # A Verify turn's claim however it ended; a Revise turn's draft only
-      # once it completed with an answer (#revision_target). Returns the
-      # stamped ReviseAnchor (the end event's revises), or nil.
-      def stamp_opening(messages, turn, outcome)
-        return unless messages.is_a?(Array)
+      private
 
-        revises = revision_target(messages, turn, outcome)
-        fields = { verify: turn.verify&.to_h, revises: revises&.to_h }.compact
-        return if fields.empty?
+      # The anchors' stage (TurnStages::VerifyAnchors).
+      attr_reader :verify_anchors
 
-        opening = messages.reverse.find do |message|
-          Steer.turn_prompt?(message) && (message[:turn_id] || message["turn_id"]).to_s == turn.id
-        end
-        return unless opening
-
-        opening.merge!(fields)
-        revises
-      end
-      private :stamp_opening
-
-      # The turn a Revise turn revised (D6: "this turn revised that one"):
-      # only a completed turn with an answer (AnswerTail) has revised
-      # anything. A draft no prompt in the messages carries is no target (a
-      # stale page, a rolled-back turn); one a stamped turn already revised
-      # is re-targeted to its stack's top, the newest version, which the
-      # person meant ("this draft").
-      def revision_target(messages, turn, outcome)
-        return unless turn.revises && outcome == "completed"
-
-        slice = AnswerTail.turn_slice(messages, turn.id)
-        return unless slice&.any? { |message| AnswerTail.answer?(message) }
-
-        target = turn.revises.turn_id
-        seen = [turn.id]
-        until seen.include?(target)
-          return reject_revise_anchor(turn.revises, :turn_missing) unless AnswerTail.turn_slice(messages, target)
-
-          seen << target
-          newer = messages.reverse.find do |message|
-            Steer.turn_prompt?(message) && ReviseAnchor.from(message[:revises] || message["revises"])&.turn_id == target
-          end
-          return ReviseAnchor.new(turn_id: target) unless newer
-
-          target = (newer[:turn_id] || newer["turn_id"]).to_s
-        end
-        reject_revise_anchor(turn.revises, :cycle)
-      end
-      private :revision_target
-
-      def reject_revise_anchor(anchor, reason)
-        Log.warn(:turn, "revise_anchor_rejected", turn_id: anchor.turn_id, reason:)
-        nil
-      end
-      private :reject_revise_anchor
-
-      def verified_anchor(session, anchor)
-        return unless anchor
-
-        source = verify_anchor_source_session(session, anchor)
-        return unless source
-
-        turn = AnswerTail.turn_slice(Array(source.messages), anchor.turn_id)
-        return reject_verify_anchor(anchor, :turn_missing) unless turn
-
-        reply = turn.reverse.find { |message| AnswerTail.answer?(message) }
-        return reject_verify_anchor(anchor, :reply_missing) unless reply
-
-        quote_text = verify_comparison_text(anchor.quote)
-        quoted = !quote_text.empty? && verify_quote_in?(quote_text, (reply[:content] || reply["content"]).to_s, source)
-        return reject_verify_anchor(anchor, :quote_missing) unless quoted
-
-        anchor
-      end
-      private :verified_anchor
-
-      # Whether +quote_text+ is in +answer+ as the model wrote it, or as the
-      # pages show it: a page quotes its own text, which reads the session's
-      # folder relative, the home folder as ~ and a secret shape as
-      # [redacted] (a participant's page gets it so, Redact;
-      # the owner's page rewrites its quote the same way, claim_link.js
-      # normalizeClaim, so claim links match both pages). +source+ is the
-      # session whose folder that is.
-      def verify_quote_in?(quote_text, answer, source)
-        return true if verify_comparison_text(answer).include?(quote_text)
-
-        viewer = Redact::Viewer.new(cwd: source.working_directory)
-        verify_comparison_text(Redact.text(answer, viewer)).include?(quote_text)
-      end
-      private :verify_quote_in?
-
-      def verify_anchor_source_session(session, anchor)
-        return session unless session.verify_fresh
-
-        fresh = session.verify_fresh
-        return reject_verify_anchor(anchor, :fresh_anchor_mismatch) unless fresh.anchor == anchor
-        return reject_verify_anchor(anchor, :fresh_parent_missing) unless session.parent_id
-
-        Session.load(session.parent_id, state_dir: session_state_dir)
-      rescue ArgumentError, SystemCallError, IOError => e
-        Log.warn(:turn, "verify_anchor_rejected", turn_id: anchor.turn_id, reason: :source_session_unavailable,
-                                                   error: e.class.name)
-        nil
-      end
-      private :verify_anchor_source_session
-
-      def verify_comparison_text(text)
-        OutputFormatter.strip_markup(text)
-                      .gsub(/!\[([^\]]*)\]\([^)]+\)/, '\1')
-                      .gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
-                      .gsub(/^[ \t]*(?:\#{1,6}[ \t]+|>[ \t]?|[-+*][ \t]+|\d+[.)][ \t]+)/, "")
-                      .gsub(/(\*\*|__|~~|`+)(.+?)\1/m, '\2')
-                      .gsub(/(?<!\w)\*(\S(?:.*?\S)?)\*(?!\w)/m, '\1')
-                      .gsub(/(?<!\w)_(\S(?:.*?\S)?)_(?!\w)/m, '\1')
-                      .tr("|", " ") # a table row's cells; the page copies them without the pipes
-                      .gsub(/\s+/, " ")
-                      .strip
-      end
-      private :verify_comparison_text
-
-      def reject_verify_anchor(anchor, reason)
-        Log.warn(:turn, "verify_anchor_rejected", turn_id: anchor.turn_id, reason:)
-        nil
-      end
-      private :reject_verify_anchor
-
-      def record_verdict(turn, outcome)
-        return unless outcome == "completed" && turn.verify
-
-        answer = AnswerTail.find(turn.session.messages, turn_id: turn.id)
-        parsed = Verdict.parse(answer && (answer[:content] || answer["content"]))
-        return unless parsed
-
-        record = { anchor: turn.verify.to_h, verdict: parsed.verdict, reason: parsed.reason,
-                   by: turn.origin.author, check_turn_id: turn.id, at: Time.now.iso8601(3) }
-        turn.session.verdicts = turn.session.verdicts + [record]
-        record
-      end
-      private :record_verdict
+      def build_verify_anchors = TurnStages::VerifyAnchors.new(state_dir: -> { session_state_dir })
     end
   end
 end

data/lib/samagotchi/engine.rb

@@ -30,6 +30,7 @@ require_relative "kernel_loop"
 require_relative "tools/builtins"
 require_relative "tools/task_runtime"
 require_relative "tools/tool_index"
+require_relative "tools/tool_surface"
 require_relative "peer_sources"
 require_relative "session_commands"
 require_relative "plugin/loader"
@@ -55,6 +56,11 @@ require_relative "objectives_audit"
 require_relative "owner_prompt"
 require_relative "side_judgments"
 require_relative "toolkit_suggest"
+require_relative "turn_stages/context_judge"
+require_relative "turn_stages/objectives"
+require_relative "turn_stages/toolkit_suggestion"
+require_relative "turn_stages/verify_anchors"
+require_relative "turn_stages/warmup"
 require_relative "tool_loads"
 require_relative "answer_tail"
 require_relative "archive_store"
@@ -79,6 +85,7 @@ require_relative "tools/memory"
 require_relative "muted_memories"
 require_relative "used_memories"
 require_relative "turn_state"
+require_relative "turn_context"
 require_relative "steer_cut"
 require_relative "engine_peers"
 require_relative "engine_snapshots"
@@ -206,8 +213,6 @@ module Samagotchi
       # 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 })
-      @objective_proposals = []
-      @objective_proposals_mutex = Mutex.new
       # A message for the running turn cutting its generation.
       @steer_cut = SteerCut.new(clock: -> { monotonic_now }, controller: -> { active_cancel_controller },
                                 cut_after: -> { steer_cut_after })
@@ -223,12 +228,11 @@ module Samagotchi
       @chat_backend_mutex = Mutex.new
       @side_judgments = SideJudgments.new
       @judgments = build_judgments
-      # On mode's cards an answer brought while a turn ran: shown once it
-      # has ended (#show_context_cards_after_turn).
-      @context_cards_after_turn = []
-      @context_cards_mutex = Mutex.new
-      @toolkit_warmup_thread = nil
       @host_registry = host_registry || HostRegistry.new
+      # The turn stages over the objectives (its audit, view and proposals)
+      # and the Verify/Revise anchors (TurnStages).
+      @objectives_stage = build_objectives_stage
+      @verify_anchors = build_verify_anchors
       # A model given here (a worker's session model) is the one it runs,
       # so its host is checked; the config default is only checked once it
       # is used (the one-shot checks the model it starts on, #switch_model!).
@@ -302,6 +306,8 @@ module Samagotchi
       # The kernel (built here, or a spec's) and what it reads of the Engine;
       # then the native backend over it.
       wire_kernel(kernel, muted_memories)
+      # The turn-end warm-up's stage, over that kernel.
+      @turn_warmup = build_turn_warmup
       Log.debug(:model, "backend", provider: backend.provider) if Log.level?(:debug)
       @resume_session = session_id ? Session.load(session_id) : nil
       @prompt_builder = build_system_prompt(memories, appended_prompt_files)
@@ -379,6 +385,11 @@ module Samagotchi
       # The session's toolkit: the kits (the plugins' too, chi.toolkit),
       # what its next turn declares, the turn-start apply.
       @toolkit_binding = build_toolkit_binding
+      # The turn stages over it and the side asks (TurnStages): System 1's
+      # toolkit suggestion and the attached-context candidate judge, which a
+      # plugin may reach as it loads.
+      @toolkit_suggestion = build_toolkit_suggestion
+      @context_judge = build_context_judge
       # The tools plugins publish without declaring (chi.tool_source), and
       # the search and call tools that reach them (Tools::ToolIndex).
       @tool_index = Tools::ToolIndex.new
@@ -396,6 +407,8 @@ module Samagotchi
       # with no plugins too: a toolkit's left-out tools are reachable
       # either way (declared per toolkit, Tools::Registry).
       @tool_index.declare(@tools, failures: @plugin_failures)
+      # What readers off the turn thread see until the first turn's start.
+      publish_tools!
     end
     private :build_tools_and_plugins
 
@@ -424,45 +437,39 @@ module Samagotchi
     end
     private :subscribe_session_observers
 
-    # The kernel and what it holds of the Engine (stores, hooks, tools, the
-    # mutes, the question flow, the gate, peers, warm-up, the hook runtime),
-    # and the native backend over it. After the plugins load.
+    # The kernel and what it holds of the Engine for its life, one
+    # KernelLoop::Services (stores, hooks, tools, the mutes, the question
+    # flow, peers, the gate, warm-up, the generation guard), and the native
+    # backend over it. After the plugins load. Nothing per turn: a turn's
+    # TurnContext goes down the backend's complete (#generate).
     def wire_kernel(kernel, muted_memories)
-      # 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: @model_binding.given_profile, model_name: effective_model_name,
-                                         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.
+      # The mutes never change during a session: 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
-      # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
-      @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.
+      # Where the approvals live; also where list_sessions and send_note
+      # look for other sessions (a worker moves it, Worker).
       self.guardrail_state_dir = Session.default_state_dir
-      # list_sessions and send_note speak for whichever session runs now.
-      @kernel.peers = PeerView.new(self)
-      # A plugin tool's row refs resolve against the session's folder, as
-      # answer refs do (AnswerRefs), not the process's.
-      @kernel.session_cwd = -> { @session&.working_directory }
-      # forget_outputs refuses what the user pinned in the working set.
-      @kernel.working_set_pins = -> { @session&.working_set_pins || [] }
-      # A cut tool output is saved whole in the session's folder.
-      @kernel.session_dir = -> { @session&.id && Session.session_dir(@session.id, state_dir: session_state_dir) }
-      @kernel.guardrail_gate = @guardrail_wiring.gate
-      @kernel.participant_turn = -> { Steer.participant_author?(turn_author) }
-      @kernel.participant_mode = -> { @guardrail_wiring.turn_mode }
-      # A pair turn stops once its participant passed their cap.
-      @kernel.generation_guard = -> { guard_participant_spend }
       # The turn-end warm-up; the kernel asks it for a slot pin per request.
       @prompt_warmup = PromptWarmup.new
-      @kernel.warmup = @prompt_warmup
+      services = KernelLoop::Services.new(
+        hooks: @hooks, tools: @tools, reminder_store: @reminder_store, muted_memory_names: @muted_memory_names,
+        # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
+        question_handler: proc { |payload| request_question(payload) },
+        # list_sessions and send_note speak for whichever session runs now.
+        peers: PeerView.new(self),
+        # Every tool call asks this gate first. The kernel is never rebuilt,
+        # so it holds across model switches.
+        gate: @guardrail_wiring.gate(hooks: @hooks, tools: @tools),
+        warmup: @prompt_warmup,
+        # A pair turn stops once its participant passed their cap.
+        generation_guard: ->(context) { guard_participant_spend(context) }
+      )
+      # A given kernel (specs) gets the same services as the one built here.
+      @kernel = kernel || KernelLoop.new(client: @client, profile: @model_binding.given_profile,
+                                         model_name: effective_model_name, services: services)
+      @kernel.attach(services) if kernel
+      sync_kernel_client!
+      sync_model_key!
       # 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
@@ -476,11 +483,9 @@ module Samagotchi
     def build_guardrail_wiring
       GuardrailWiring.new(
         scratch: @scratch,
-        hooks: -> { @hooks },
+        # Built before the tools (the hooks load into its failures).
         tools: -> { @tools },
         session: -> { @session },
-        model_key: -> { @model_binding.model_key },
-        model_name: -> { guardrail_model_name },
         cancelled: -> { !!active_cancel_controller&.cancelled? },
         # An approval of the model's call: :question_asked first (QuestionAsked).
         ask: ->(fields) { open_question(question_asked(QuestionAsked::KIND_APPROVAL, fields)) },
@@ -495,7 +500,7 @@ module Samagotchi
         system_one_runs: -> { system_one_runs },
         cancel_controller: -> { active_cancel_controller },
         # A participant's turn: their name on the owner's card, their
-        # grant's mode for the turn's (GuardrailWiring#turn_mode).
+        # grant's mode for the turn's (GuardrailWiring#begin_turn).
         participant: ->(author) { @participants.entry_for(author, session: @session) }
       )
     end
@@ -511,7 +516,8 @@ module Samagotchi
         thinking_notices: -> { @thinking_notices },
         metrics: -> { @metrics },
         hooks: -> { @hooks },
-        kernel: -> { @kernel },
+        turn_context: -> { turn_context },
+        last_turn_context: -> { last_turn_context },
         model_settings: -> { @model_settings },
         session: -> { @session },
         live_conversation: -> { live_conversation },
@@ -683,7 +689,7 @@ module Samagotchi
       end
       @side_judgments.join(SIDE_JUDGMENTS_JOIN_SECONDS)
       # The warm-up's answer is dropped anyway.
-      stop_toolkit_warmup
+      @toolkit_suggestion.stop_warmup
       left = threads.count(&:alive?)
       Log.warn(:plugins, "anytime_commands_left", count: left) if left.positive?
       @plugin_tasks.kill_leftovers
@@ -715,13 +721,13 @@ module Samagotchi
         kept, event = yield(seconds)
         event[:turn_id] = turn.id
         event[:verify] = true if turn.verify
-        revises = stamp_opening(kept, turn, outcome)
+        revises = @verify_anchors.stamp_opening(kept, turn, outcome)
         replace_session_messages(turn.session, kept) if kept
-        verdict = record_verdict(turn, outcome)
+        verdict = @verify_anchors.record_verdict(turn, outcome)
         event[:verdict] = verdict if verdict
         event[:revises] = revises.to_h if revises
         emit_working_set(turn.on_event, turn.session, turn.session.messages)
-        announce_objectives(turn.session)
+        @objectives_stage.announce(turn.session)
         turn.session.status = Session::STATUS_IDLE
         record_last_turn(turn.session, outcome, seconds, turn.origin, event, limit: exhausted ? turn.limit : nil)
         emit_event(turn.on_event, turn.tag(event))
@@ -778,14 +784,15 @@ module Samagotchi
     end
     private :build_recap
 
-    # 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.
+    # One turn's lifecycle state, for #run_turn and its endings. Per turn
+    # and single-threaded: the cross-thread turn state (the published
+    # TurnContext, the cancel slot, the sink, steers) stays in TurnState.
+    # +context+: the turn's TurnContext, the one source of truth for its
+    # id, session, origin and controller (read through #id, #session,
+    # #origin, #controller); #generate replaces it with the settings in.
     # +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.
-    # +id+: names the turn on :turn_started (its metrics record's id) and on
-    # its saved prompt, so a UI pairs the two whatever left the conversation.
+    # +prepared_settings+: the LLM::TurnSettings #prepare_turn makes (before
+    # the hooks); #generate completes them into the context's.
     # +limit+: the iteration limit #generate ran it with.
     # +resumed+: a step-limit Continue (run_turn's resumed:).
     # +resume_from+: where its reasoning starts, the run it resumes
@@ -794,8 +801,15 @@ module Samagotchi
     # +wall+: the wall time it started (MessageTime.now, once): the
     # :turn_started event's at and its user message's (and reminders') stamp.
     # +verify+, +revises+: a Verify turn's claim, a Revise turn's draft.
-    Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id, :limit, :resumed, :resume_from, :wall, :verify, :revises, :outcome) do
+    Turn = Struct.new(:context, :prompt, :continue, :on_event, :started_at, :messages, :ended, :prepared_settings,
+                      :limit, :resumed, :resume_from, :wall, :verify, :revises, :outcome) do
+      # The turn's id (:turn_started's turn_id, its metrics record's id and
+      # its saved prompt's), session, origin and controller: its context's.
+      def id = context.id
+      def session = context.session
+      def origin = context.origin
+      def controller = context.controller
+
       def resumed? = resumed ? true : false
 
       # The turn ended as a completed one (not canceled, not failed): the
@@ -866,7 +880,7 @@ module Samagotchi
     #   wake's note) names it with this id
     # @param verify [VerifyAnchor, nil] a Verify turn's claim (its verdict)
     # @param revises [ReviseAnchor, nil] a Revise turn's draft: stamped on
-    #   the prompt at the turn's end, metadata only (#stamp_opening)
+    #   the prompt at the turn's end, metadata only (TurnStages::VerifyAnchors#stamp_opening)
     #
     # An Interrupt (SIGINT) cancels the turn: what it got to is kept in the
     # session as after a Stop (the prompt, the loop's finished tool
@@ -897,7 +911,7 @@ module Samagotchi
                                 pending_input: pending_input)
         publish_used_memories(session, on_event)
         complete_turn(turn, result)
-        warm_up_next_turn(turn, result)
+        @turn_warmup.after(turn, result)
         result
       rescue Interrupt => e
         # After the end event (in the after_turn/session_end hooks) the
@@ -924,24 +938,23 @@ module Samagotchi
         raise
       ensure
         release_turn(probe_cancel_before)
-        show_context_cards_after_turn
-        # Only a completed turn shows its proposal cards: a canceled, failed
-        # or rolled-back turn keeps none, and its proposals are dropped here
-        # so the next turn does not show them either.
-        turn.completed? ? show_objective_proposals : discard_objective_proposals(turn)
+        @context_judge.show_cards_after_turn
+        # Only a completed turn shows its proposal cards; any other's are
+        # dropped, so the next turn does not show them either.
+        @objectives_stage.finally(turn)
       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.
+    # its TurnContext, 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:, id: nil, verify: nil, revises: nil,
                    input_waiting: nil)
       origin = TurnOrigin.of(origin)
       # A participant's Verify fresh child: every turn is theirs (their
       # author, boundary and cap), whoever started it.
       origin = session.verify_fresh.origin_for(origin) if session.respond_to?(:verify_fresh) && session.verify_fresh
-      verify = verified_anchor(session, VerifyAnchor.from(verify))
+      verify = @verify_anchors.verified(session, VerifyAnchor.from(verify))
       # Track the active session for recap and status snapshot.
       @session = session
       # status is turn state: running now, idle again before the turn's end
@@ -950,25 +963,62 @@ module Samagotchi
       @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 (a one-shot prints only its sink; a
-      # worker's observers carry it to the bridge).
-      @turn_state.begin!(controller: effective_controller, sink: on_event, input_waiting: input_waiting)
+      # The turn's context, whole before the turn is published: who queued
+      # it, a participant's mode (participants.json), git asked afresh.
+      context = new_turn_context(session, origin, effective_controller, id || SecureRandom.uuid)
+      # The turn runs, with its context, controller and sink, in one step:
+      # a Stop, a plugin's card or its ctx.turn_author from another thread
+      # never sees a running turn without them (or with the last turn's).
+      # 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 (a one-shot prints only its sink; a worker's
+      # observers carry it to the bridge).
+      @turn_state.begin!(context: context, controller: effective_controller, sink: on_event, input_waiting: input_waiting)
       # 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),
-               id: id || SecureRandom.uuid, wall: MessageTime.now, verify: VerifyAnchor.from(verify),
-               revises: ReviseAnchor.from(revises))
+      Turn.new(context: context, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
+               started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC), wall: MessageTime.now,
+               verify: VerifyAnchor.from(verify), revises: ReviseAnchor.from(revises))
     end
     private :begin_turn
 
+    # A new turn's TurnContext (#begin_turn): the gate's turn facts
+    # (GuardrailWiring#begin_turn), the session's folders. Its settings and
+    # model come in #generate.
+    def new_turn_context(session, origin, controller, id)
+      start = @guardrail_wiring.begin_turn(origin, session: session)
+      TurnContext.new(id: id, session: session, origin: origin, author: origin.participant_author,
+                      participant_mode: start.mode, participant: start.participant, controller: controller,
+                      cwd: (session.working_directory if session.respond_to?(:working_directory)), session_dir: turn_session_dir(session),
+                      state_dir: session_state_dir, git: start.git, settings: nil, model_key: nil,
+                      fallback_model_key: nil, model_name: nil, surface: nil)
+    end
+    private :new_turn_context
+
+    # The session's folder, nil when it can't be named (an id that isn't
+    # one, a lookup that raised): a cut tool output then says it wasn't saved.
+    def turn_session_dir(session)
+      Session.session_dir(session.id, state_dir: session_state_dir)
+    rescue StandardError => e
+      Log.warn(:turn, "tool_output_save_failed", error: e.class.name)
+      nil
+    end
+    private :turn_session_dir
+
+    # The running turn's TurnContext as other threads see it (TurnState),
+    # nil between turns; its settings are nil until #generate.
+    # @return [TurnContext, nil]
+    def turn_context = @turn_state.context
+    private :turn_context
+
+    # The last finished turn's TurnContext (TurnState#last_context), nil
+    # before any: its author (the recap's), its settings (the working set's
+    # between turns).
+    # @return [TurnContext, nil]
+    def last_turn_context = @turn_state.last_context
+    private :last_turn_context
+
     # 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
@@ -987,14 +1037,14 @@ module Samagotchi
       # A participant's turn names them (author, author_name) for the UIs'
       # badge; the owner's turn_started stays as it was.
       turn_started.merge!(author_fields(turn.origin.author, session: session),
-                          participant_mode_fields(turn.origin.author))
+                          participant_mode_fields(turn.context))
       emit_event(turn.on_event, turn.tag(turn_started))
       raise image_error if image_error
 
       # On mode's ask starts here too; the turn joins it before
       # apply_toolkit! below, so its latency hides behind the probes and
       # the init wait.
-      toolkit_suggestion = start_toolkit_suggestion(turn)
+      @toolkit_suggestion.start(turn)
 
       # The window and the profile probes run after run_turn's probe-cancel
       # swap, so a Stop cuts them; a failure ends the turn as turn_failed.
@@ -1006,12 +1056,12 @@ module Samagotchi
       refresh_profile!
 
       # 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?
+      turn.prepared_settings = turn_settings(session)
+      refuse_images!(turn.prepared_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.
       if turn.controller.cancelled?
-        toolkit_suggestion&.abandon(:canceled)
+        @toolkit_suggestion.abandon(turn, :canceled)
         return false
       end
 
@@ -1028,11 +1078,11 @@ module Samagotchi
       apply_staged_tools!
       # On mode: the suggested kit, before anything is declared (a Stop
       # during the wait is caught by the check below).
-      settle_toolkit_suggestion(turn, toolkit_suggestion)
+      @toolkit_suggestion.settle(turn)
       # The candidate judge: its asks run beside the turn; on mode's
       # attaches reach the model at the next between-turn delivery.
-      start_context_judge(turn)
-      audit_objectives_incoming(turn)
+      @context_judge.start(turn)
+      @objectives_stage.incoming(turn)
       apply_toolkit!(session, turn.on_event)
       refresh_participants!(session)
       # A Stop during the waits above: the turn ends here,
@@ -1055,7 +1105,8 @@ module Samagotchi
     ensure
       # A turn that ended (a failure, an Interrupt) before it settled the
       # ask: its line says so. Nothing once it was settled.
-      toolkit_suggestion&.abandon(:failed)
+      @toolkit_suggestion.abandon(turn, :failed)
+      @toolkit_suggestion.finish(turn)
     end
     private :prepare_turn
 
@@ -1087,7 +1138,7 @@ module Samagotchi
 
       unless turn.continue
         user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author),
-                         **participant_mode_fields(turn.origin.author), MessageTime::KEY => turn.at }
+                         **participant_mode_fields(turn.context), MessageTime::KEY => turn.at }
         user_message[:verify] = turn.verify.to_h if turn.verify
         user_message[:images] = image_refs unless image_refs.empty?
         turn.messages << user_message
@@ -1106,17 +1157,28 @@ module Samagotchi
       # Route model name as bare (without host prefix) to the server;
       # host selection already done via active client.
       bare_for_backend = bare_model_name(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.
+      # The turn's settings, set once here into its context (with the model
+      # key and name the gate and memory_read use: frozen now, after the
+      # hooks that may switch the model), which goes down the backend's
+      # complete to every tool call, and is published (TurnState).
       explained = model.llm_context_explained(@model_settings.llm_context_session_args)
       model_backend = backend(model)
       # A host that loads tools runs a direct call of one the session
       # reaches but doesn't declare (ToolRunner, KernelLoop#dispatch).
       loads_tools = model_backend.respond_to?(:loads_tools?) && model_backend.loads_tools?(bare_for_backend)
-      @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: model.window_setting,
-                                                 llm_context: explained&.resolved, price: model.price,
-                                                 loads_tools: loads_tools)
+      settings = turn.prepared_settings.with(model_name: bare_for_backend, window_setting: model.window_setting,
+                                             llm_context: explained&.resolved, price: model.price,
+                                             loads_tools: loads_tools)
+      # The turn's tools (Tools::ToolSurface), built once from the Registry
+      # under those settings' layers and loads_tools: what the loops declare,
+      # defer and dispatch until the turn ends; a change meanwhile (a
+      # /toolkit change, a staged chi.replace_tools) is the next turn's.
+      surface = Tools::ToolSurface.for(@tools, layers: settings.llm_context&.active_layers || [],
+                                               loads_tools: loads_tools)
+      turn.context = turn.context.with(settings: settings, model_key: @model_binding.model_key,
+                                       fallback_model_key: @model_binding.fallback_model_key,
+                                       model_name: guardrail_model_name, surface: surface)
+      @turn_state.replace_context(turn.context)
       log_llm_context(explained)
 
       turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
@@ -1133,7 +1195,8 @@ module Samagotchi
         model_name: bare_for_backend,
         max_tool_output_chars: max_tool_output_chars,
         pending_input: turn_drain(pending_input),
-        reasoning_since: reasoning_since
+        reasoning_since: reasoning_since,
+        context: turn.context
       )
       result.run_start = run_start
       result

data/lib/samagotchi/engine_peers.rb

@@ -4,7 +4,7 @@ require_relative "objectives"
 
 module Samagotchi
   # The views of an Engine its peers get: the kernel's tools
-  # (Engine#initialize sets @kernel.peers) and a delegate's approval relay
+  # (KernelLoop::Services#peers, Engine#wire_kernel) and a delegate's approval relay
   # (Engine#relay_peer).
   class Engine
     # The kernel's Tools::Peers, following the current session. cancelled?