samagotchi 0.110.0 → 0.111.0

data/lib/samagotchi/engine_snapshots.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative "session_setting"
+require_relative "token_usage"
+
+module Samagotchi
+  # The read model an Engine gives its UIs: #session_state_snapshot (cheap,
+  # never probes and never raises: the Bridge's /state and reset frames call
+  # it under the event lock) and #stats_snapshot (/stats, which may make one
+  # short /props GET), with their helpers.
+  #
+  # What it needs from the Engine comes through lookups, read at call time;
+  # the Engine forwards each method here. It takes no lock of its own: under
+  # the Bridge's event lock a snapshot takes the question desk's monitor and
+  # the metrics mutex, as before.
+  class EngineSnapshots
+    # State lookups, each [#call] → the Engine's object:
+    # @param session, metrics, observer, question_desk, used_memories, muted,
+    #   prompt_builder, participants, participants_watch, recap,
+    #   last_context_status, model_settings
+    # Engine calls (the Engine keeps these; specs stub some on it):
+    # @param effective_model, effective_model_name, effective_model_ref,
+    #   bare_model_name (ref), served_model (probe:), prompt_notes, preloaded,
+    #   saved_context_status (context, **opts), context_window (model),
+    #   profile_resolution, toolkit_summary, toolkit_explained
+    def initialize(session:, metrics:, observer:, question_desk:, used_memories:, muted:, prompt_builder:,
+                   participants:, participants_watch:, recap:, last_context_status:, model_settings:,
+                   effective_model:, effective_model_name:, effective_model_ref:, bare_model_name:, served_model:,
+                   prompt_notes:, preloaded:, saved_context_status:, context_window:, profile_resolution:,
+                   toolkit_summary:, toolkit_explained:)
+      @session = session
+      @metrics = metrics
+      @observer = observer
+      @question_desk = question_desk
+      @used_memories = used_memories
+      @muted = muted
+      @prompt_builder = prompt_builder
+      @participants = participants
+      @participants_watch = participants_watch
+      @recap = recap
+      @last_context_status = last_context_status
+      @model_settings = model_settings
+      @effective_model = effective_model
+      @effective_model_name = effective_model_name
+      @effective_model_ref = effective_model_ref
+      @bare_model_name = bare_model_name
+      @served_model = served_model
+      @prompt_notes = prompt_notes
+      @preloaded = preloaded
+      @saved_context_status = saved_context_status
+      @context_window = context_window
+      @profile_resolution = profile_resolution
+      @toolkit_summary = toolkit_summary
+      @toolkit_explained = toolkit_explained
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # The metrics for /stats. Before the first generation reports them, the
+    # context window, the served model and (on a native host) the prompt
+    # profile come from the effective model's server, so this may make one
+    # short /props GET; the cheap #session_state_snapshot never does.
+    # price_host: the effective model's host, whose hosts.<name>.models
+    # prices the cost estimate names. kit_prompt: the next turn's kit
+    # prompt text ({kit:, tokens:}), only when its toolkit has one.
+    # settings: the session's own settings ({"recap.enabled" => false}),
+    # only when it has some.
+    # @return [Hash] @metrics.snapshot, filled in
+    def stats_snapshot
+      snapshot = metrics.snapshot
+      # One resolve for the whole snapshot (its readers' rescues stay theirs);
+      # a model that doesn't resolve raises here, as it always has.
+      model = effective_model
+      served, served_for = served_model_for(snapshot, model: model)
+      snapshot = snapshot.merge(served_model: served, served_model_for: served_for,
+                                served_expected_by: model.served_expected_by(served),
+                                **setting_chips(SessionSetting::STATS, model),
+                                prompt_notes: prompt_notes.map(&:to_h), prompt_files: prompt_builder.prompt_files,
+                                price_host: model.host_name)
+      kit_prompt = kit_prompt_stats
+      snapshot = snapshot.merge(kit_prompt: kit_prompt) if kit_prompt
+      # Each participant's spend under their name (participants.json's).
+      if (spend = snapshot[:spend_by_author])
+        named = spend.to_h { |author, row| [author, row.merge(name: participants.name_for(author, session: session))] }
+        snapshot = snapshot.merge(spend_by_author: named)
+      end
+      # The session's own settings (chi --set), as --set names them.
+      settings = session&.settings&.flat || {}
+      snapshot = snapshot.merge(settings: settings) unless settings.empty?
+      unless snapshot.dig(:context, :window_tokens)
+        window = current_context_window(model)
+        if window
+          snapshot = snapshot.merge(context: snapshot[:context].merge(window_tokens: window.tokens,
+                                                                      window_source: window.source.to_s))
+        end
+      end
+      # The chat loop uses no prompt profile: drop one a native turn reported.
+      return snapshot.except(:profile, :profile_source) if model.chat?
+
+      unless snapshot[:profile]
+        resolution = profile_resolution
+        snapshot = snapshot.merge(profile: resolution.profile.name, profile_source: resolution.label)
+      end
+      snapshot
+    end
+
+    # Read-only snapshot of the engine's view of the current session plus the
+    # live event sequence. Cheap primitive used by the bridge's reconnect-too-
+    # old reset marker and the GET /session/:id/state read surface. Orthogonal
+    # to the transport — safe to call before the first turn (nil session).
+    #
+    # @return [Hash] with keys:
+    #   :status        [String, nil] current session status
+    #   :message_count [Integer]   number of messages in the session
+    #   :last_prompt   [String, nil] the last user prompt (empty string if none)
+    #   :event_seq     [Integer]   @session_observer.event_count
+    #   :metrics       [Hash]      @metrics.snapshot (per-session analytics)
+    #   :pending_question [Hash, nil] the pending question (PendingQuestion#to_h)
+    #   :used_memory_names [Array<String>] deduped memory names active this session
+    #   :prompt_notes  [Array<Hash>] the model notes the prompt carried
+    #     ({name:, scope:, chars:, digest:}; #prompt_notes)
+    #   :parent_id     [String, nil] the session that delegated this one
+    #   :model_name    [String]    the model turns run on now (after /model)
+    #   :served_model, :served_model_for [String, nil] what a generation of
+    #     that model reported serving, and the name asked (#served_model
+    #     without the probe)
+    #   :served_expected_by [String, nil] the host whose models: entry names
+    #     that served model under served: (#served_expected_by)
+    #   :recap_enabled [Boolean]   whether an idle recap is configured, with
+    #     :recap_min_user_turns and :recap_inactivity_seconds (nil when not)
+    #   :participants  [Array<Hash>] who is in the review now ({id:, name:,
+    #     kind:}; ParticipantsWatch#active), [] for nobody
+    def session_state_snapshot
+      served_pair = served_model(probe: false)
+      metrics = self.metrics.snapshot
+      # One resolve for the model's fields; nil when it doesn't resolve (the
+      # Bridge's /state and reset frames rely on this never raising): those
+      # fields are nil then, as their own rescues always gave.
+      model = model_settings.model_setting(nil) { |resolved| resolved }
+      {
+        status: session&.status,
+        message_count: (session&.messages || []).size,
+        last_prompt: session&.last_prompt,
+        event_seq: observer&.event_count,
+        metrics: metrics,
+        pending_question: question_desk.pending&.to_h,
+        used_memory_names: used_memories.names,
+        preloaded_memory_names: preloaded_memory_names,
+        muted_memory_names: muted.dup,
+        prompt_notes: prompt_notes.map(&:to_h),
+        parent_id: session&.parent_id,
+        title: session&.title,
+        model_name: effective_model_ref,
+        served_model: served_pair[0],
+        served_model_for: served_pair[1],
+        served_expected_by: model&.served_expected_by(served_pair[0]),
+        context_status: last_context_status&.dup || saved_context_status(metrics[:context], model: model),
+        **setting_chips(SessionSetting::ALL, model),
+        recap_enabled: !recap.nil?,
+        recap_min_user_turns: recap&.min_user_turns,
+        recap_inactivity_seconds: recap&.inactivity&.to_i,
+        participants: participants_watch.active
+      }
+    end
+
+    # See Engine#served_model. A report for another name (before a /model switch)
+    # doesn't count. Without a model (EffectiveModel), no probe. A remote
+    # chat host has no /props: nil until a turn. The name asked is never
+    # resolved (HostRegistry#bare_name), so it holds on a broken resolve.
+    def served_model_for(snapshot, model: nil)
+      asked = bare_model_name(model ? model.name : effective_model_name)
+      return [snapshot[:served_model], asked] if snapshot[:served_model] && snapshot[:served_model_for] == asked
+      return [nil, nil] unless model
+
+      model.served_from_props(asked)
+    # Only bare_model_name and the snapshot lookup are left to fail here:
+    # the probe's failure is EffectiveModel#served_from_props's.
+    rescue StandardError
+      [nil, nil]
+    end
+
+    # The next turn's kit prompt text for /stats: its kit and its estimated
+    # tokens (chars / 4), nil when its toolkit has none.
+    def kit_prompt_stats
+      resolved = toolkit_explained.resolved
+      return nil unless resolved.prompt
+
+      { kit: resolved.name, tokens: (resolved.prompt.length / TokenUsage::CHARS_PER_TOKEN).ceil }
+    end
+
+    # +settings+' chips (SessionSetting), the model's from +model+ (nil
+    # when it doesn't resolve): /stats, the session state, a :command_ran.
+    def setting_chips(settings, model)
+      settings.to_h { |setting| [setting.key, setting.model? ? setting.chip_for(model, session) : toolkit_summary] }
+    end
+
+    private
+
+    def session = @session.call
+    def metrics = @metrics.call
+    def observer = @observer.call
+    def question_desk = @question_desk.call
+    def used_memories = @used_memories.call
+    def muted = @muted.call
+    def prompt_builder = @prompt_builder.call
+    def participants = @participants.call
+    def participants_watch = @participants_watch.call
+    def recap = @recap.call
+    def last_context_status = @last_context_status.call
+    def model_settings = @model_settings.call
+    def effective_model = @effective_model.call
+    def effective_model_name = @effective_model_name.call
+    def effective_model_ref = @effective_model_ref.call
+    def bare_model_name(ref) = @bare_model_name.call(ref)
+    def served_model(probe:) = @served_model.call(probe: probe)
+    def prompt_notes = @prompt_notes.call
+    def preloaded_memory_names = @preloaded.call
+    def saved_context_status(context, **) = @saved_context_status.call(context, **)
+    def current_context_window(model) = @context_window.call(model)
+    def profile_resolution = @profile_resolution.call
+    def toolkit_summary = @toolkit_summary.call
+    def toolkit_explained = @toolkit_explained.call
+  end
+end

data/lib/samagotchi/event_fanout.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative "hooks"
+require_relative "log"
+require_relative "steer_cut"
+require_relative "working_set"
+
+module Samagotchi
+  # How one of an Engine's events reaches the turn's sink and the persistent
+  # observers (#emit_event: the used-memories capture, the isolated sink
+  # call, the observer notify, the follow-up :used_memories_updated), the
+  # stream handler that wraps each raw loop event (#build_stream_event_handler:
+  # SteerCut, ThinkingNotices, the StreamWatch, the generation report, the
+  # working set at each request), and the working set's dedupe
+  # (#emit_working_set).
+  #
+  # What it needs from the Engine comes through lookups, read at call time;
+  # the Engine forwards each method here. It takes no lock: the observers'
+  # notify takes the event lock, as before. #announce_or_hold stays the
+  # Engine's: its thread-local is keyed on the Engine.
+  class EventFanout
+    # @param observer          [#call] → SessionObserver
+    # @param used_memories     [#call] → UsedMemories
+    # @param muted             [#call] → Array<String>, the muted memory names
+    # @param steer_cut         [#call] → SteerCut
+    # @param thinking_notices  [#call] → ThinkingNotices
+    # @param metrics           [#call] → SessionMetrics
+    # @param hooks             [#call] → Hooks::Registry
+    # @param kernel            [#call] → KernelLoop
+    # @param model_settings    [#call] → SessionModelSettings
+    # @param session           [#call] → Session, nil
+    # @param live_conversation [#call] → Array<Hash>, the running turn's conversation
+    # @param used_memory_names [#call] → Array<String>
+    # @param served_expected_by [#call] (served) → the host expecting the served model
+    # @param working_set_strategy [#call] → the strategy the working set is built under
+    # @param turn_running      [#call] → Boolean
+    # @param announce_or_hold  [#call] (event) → announces the event, or holds it
+    def initialize(observer:, used_memories:, muted:, steer_cut:, thinking_notices:, metrics:, hooks:, kernel:,
+                   model_settings:, session:, live_conversation:, used_memory_names:, served_expected_by:,
+                   working_set_strategy:, turn_running:, announce_or_hold:)
+      @observer = observer
+      @used_memories = used_memories
+      @muted = muted
+      @steer_cut = steer_cut
+      @thinking_notices = thinking_notices
+      @metrics = metrics
+      @hooks = hooks
+      @kernel = kernel
+      @model_settings = model_settings
+      @session = session
+      @live_conversation = live_conversation
+      @used_memory_names = used_memory_names
+      @served_expected_by = served_expected_by
+      @working_set_strategy = working_set_strategy
+      @turn_running = turn_running
+      @announce_or_hold = announce_or_hold
+      @working_set_emitted = nil
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Always return a handler so raw kernel loop events reach the persistent
+    # SessionObserver (and thus the analytics collector) even when there is no
+    # turn-scoped +on_event+ sink (e.g. the -p/--resume paths and
+    # SessionManager background workers). emit_event tolerates a nil on_event by
+    # only notifying the observer.
+    # Wrap a raw kernel stream event and fan it out to the turn sink + observers.
+    #
+    # Each :generation_chunk comes split already, by the loop that streamed it:
+    # besides the raw `content` (left untouched — the TUI thinking spinner,
+    # analytics, and Bridge replay rely on it) it carries
+    #   * :text     — visible prose (thinking AND tool_call blocks removed)
+    #   * :thinking — thinking-only content
+    # KernelLoop splits a native stream with a ThoughtStreamSplitter per
+    # generation (every profile, Gemma's thought channel included); the chat
+    # loop gets reasoning apart from the answer. The web routes on those
+    # fields (chunk_router.js).
+    #
+    # With a :generation_progress hook registered, a Hooks::StreamWatch gets
+    # each chunk's thinking and text after the UIs had it.
+    #
+    # +model_ref+: the turn's model (#generation_model_ref), added to each
+    # :generation_started as `model_ref:` (both loops send through here).
+    def build_stream_event_handler(on_event, cancel_controller: nil, model_ref: nil)
+      watch = stream_watch(cancel_controller)
+      proc do |event|
+        progress = SteerCut.lanes(event) if event[:type] == :generation_chunk
+        steer_cut.observe(event, progress)
+        case event[:type]
+        when :generation_started
+          event = event.merge(model_ref: model_ref) if model_ref
+          thinking_notices.generation_started
+          watch&.started(event[:iteration])
+        when :generation_retrying
+          # A dropped stream's step asked again: it streams from the start.
+          if event[:restarted]
+            thinking_notices.generation_started
+            watch&.started(event[:iteration], restarted: true)
+          end
+        when :generation_chunk then thinking_notices.note_thought(progress[:thinking])
+        end
+        # The chat loop asked again without the thinking fields or the
+        # reasoning sent back: a notice, not an event of its own.
+        next thinking_notices.thinking_refused(event) if event[:type] == :thinking_refused
+        next thinking_notices.reasoning_history_refused(event) if event[:type] == :reasoning_history_refused
+        next thinking_notices.sampling_refused(event) if event[:type] == :sampling_refused
+
+        event = with_generation_report(event) if event[:type] == :generation_completed
+        emit_event(on_event, event)
+        # What this request sends: both loops start a generation after
+        # their apply_llm_context!.
+        emit_working_set(on_event, session, live_conversation) if event[:type] == :generation_started
+        watch.feed(**progress) if watch && progress
+        thinking_notices.generation_completed(event) if event[:type] == :generation_completed
+      end
+    end
+
+    # The working set (WorkingSet) as the model has it, as a
+    # :working_set_updated event ({items:, at:}, adds: while the user's
+    # adds are pending): at each request (the
+    # stream handler's :generation_started, from the running turn's
+    # conversation) and at turn end (#end_turn, from the session's kept
+    # messages). Only when it differs from the last one emitted for this
+    # session, and never while it is empty — except one empty event,
+    # remembered, when the last one for this session had items (a
+    # rollback removed the tool calls), so a tool-free turn emits none
+    # and the next empty request sends nothing more. The web overlays it
+    # on the rows' set; other UIs ignore it.
+    #
+    # Between turns (#announce_working_set: no +on_event+) it is
+    # announced, under the next turn's strategy.
+    def emit_working_set(on_event, session, conversation)
+      return unless session && conversation
+
+      snapshot = WorkingSet.build(conversation, cwd: session.working_directory, strategy: working_set_strategy,
+                                  pins: session.working_set_pins)
+
+      shown = snapshot.to_h.except(:at)
+      last = @working_set_emitted
+      if snapshot.empty?
+        return unless last && last[0] == session.id && last[1] != { items: [] }
+      elsif last == [session.id, shown]
+        return
+      end
+
+      @working_set_emitted = [session.id, shown]
+      event = { type: :working_set_updated, **shown, at: snapshot.at }
+      on_event ? emit_event(on_event, event) : announce_or_hold(event)
+    rescue StandardError => e
+      Log.warn(:turn, "working_set_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+    end
+
+    # The strategy the set is built under: the running turn's
+    # (TurnSettings#llm_context: what its requests send); between turns
+    # the next turn's (as #warm_up_next_turn: the turn's settings keep the
+    # last turn's, stale after a /llm-context or /model change), the last
+    # turn's when it can't be resolved.
+    def working_set_llm_context
+      turn = kernel.respond_to?(:turn_settings) ? kernel.turn_settings&.llm_context : nil
+      return turn if turn_running?
+
+      model_settings.turn_llm_context || turn
+    end
+
+    # A :generation_completed with the generation's decode speed (`speed:`
+    # {decode_tps:, source:}, nil without one), the session's running
+    # token totals (`tokens:`, the snapshot's block) and its per-model rows
+    # (`model_segments:`, the snapshot's) and whether its served
+    # model is an expected one (`served_expected_by:`, its host): the web's info bar
+    # reads them from the stream. SessionMetrics closes the generation here,
+    # so the event it gets next finds it closed.
+    def with_generation_report(event)
+      report = metrics.finish_generation
+      event.merge(speed: report.speed&.to_h, tokens: report.tokens, model_segments: report.model_segments,
+                  served_expected_by: served_expected_by(event[:served_model]))
+    rescue StandardError => e
+      Log.warn(:turn, "generation_report_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+      event
+    end
+
+    # The turn's StreamWatch, or nil when no hook listens.
+    def stream_watch(cancel_controller)
+      return nil unless cancel_controller && hooks.any?(Hooks::StreamWatch::EVENT)
+
+      Hooks::StreamWatch.new(hooks: hooks, cancel_controller: cancel_controller)
+    end
+
+    def emit_event(on_event, event)
+      # Capture used memories synchronously in the turn thread.
+      read_names = begin
+        used_memories.capture(event, muted: muted)
+      rescue StandardError => e
+        Log.warn(:memory, "used_memories_capture_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        nil
+      end
+      # Turn-scoped sink: receives the event hash as the stream handler
+      # passed it (no event_seq; a :generation_completed has its report). Sink errors are isolated and never break the
+      # kernel loop (same as KernelLoop's own handling).
+      if on_event
+        begin
+          on_event.call(event)
+        rescue StandardError => e
+          # Sink errors must not break the kernel loop (same as KernelLoop's own handling)
+          Log.warn(:turn, "sink_failed", event_type: event[:type].to_s, error: e.class.name, msg: e.message.to_s[0, 200])
+        end
+      end
+
+      # Persistent subscribers: receive a copy with a locally-monotonic
+      # `event_seq`, fan out with per-subscriber error isolation.
+      observer.notify(event)
+      # Every memory read, after its tool_call_started: the whole list for
+      # the UIs' memory line, and the names this call read (read_names).
+      return unless read_names
+
+      emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names, read_names: read_names })
+    end
+
+    private
+
+    def observer = @observer.call
+    def used_memories = @used_memories.call
+    def muted = @muted.call
+    def steer_cut = @steer_cut.call
+    def thinking_notices = @thinking_notices.call
+    def metrics = @metrics.call
+    def hooks = @hooks.call
+    def kernel = @kernel.call
+    def model_settings = @model_settings.call
+    def session = @session.call
+    def live_conversation = @live_conversation.call
+    def used_memory_names = @used_memory_names.call
+    def served_expected_by(served) = @served_expected_by.call(served)
+    def working_set_strategy = @working_set_strategy.call
+    def turn_running? = @turn_running.call
+    def announce_or_hold(event) = @announce_or_hold.call(event)
+  end
+end

data/lib/samagotchi/model_binding.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "effective_model"
+require_relative "model_overlay"
+require_relative "model_profile"
+
+module Samagotchi
+  # An Engine's model choice (ModelChoice: the model as given and as typed)
+  # and the prompt profile resolved for it, under one mutex; the counterpart
+  # of ToolkitBinding. The memory overlay keys follow the choice
+  # (#sync_model_key!).
+  #
+  # The choice changes in one assignment under the mutex (#switch!), so a
+  # reader on another thread sees the old pair or the new one. A resolution
+  # is kept and applied only for the choice it was resolved for, by
+  # identity (#store_profile: a /stats on a Bridge thread probing while
+  # /model runs keeps nothing). Nothing else takes the mutex.
+  #
+  # What it needs from the Engine comes through lookups, called at use; the
+  # Engine forwards each method here.
+  class ModelBinding
+    # @param choice         [ModelChoice] the starting model
+    # @param given_profile  [ModelProfile, nil] a caller's profile (until a switch)
+    # @param registry       [HostRegistry]
+    # @param kernel         [#call] → KernelLoop
+    # @param prompt_builder [#call] → SystemPrompt, nil while the Engine is built
+    # @param bare_name      [#call] (ref) → the model id sent for +ref+
+    def initialize(choice:, given_profile:, registry:, kernel:, prompt_builder:, bare_name:)
+      @choice = choice
+      @given_profile = given_profile
+      @registry = registry
+      @kernel = kernel
+      @prompt_builder = prompt_builder
+      @bare_name = bare_name
+      # Guards the model choice and the profile cached for it (#store_profile).
+      @mutex = Mutex.new
+      # [choice, resolution]: the resolution kept, with the choice it is for.
+      @resolution = nil
+      @model_key = nil
+      @fallback_model_key = nil
+    end
+
+    # @return [ModelChoice] the model turns run on now
+    attr_reader :choice
+
+    # @return [ModelProfile, nil] the profile given to the Engine, nil after a switch
+    attr_reader :given_profile
+
+    # The effective model's key (ModelOverlay.key_for its bare name), and
+    # the typed name's when that differs (#sync_model_key!).
+    # @return [String, nil]
+    attr_reader :model_key, :fallback_model_key
+
+    # Moves to +choice+ (Engine#switch_model!): the given profile and the
+    # kept resolution go with the old one.
+    def switch!(choice)
+      @mutex.synchronize do
+        # One assignment: a reader on another thread sees the old pair or the new one.
+        @choice = choice
+        # A profile given to .new was for the starting model.
+        @given_profile = nil
+        @resolution = nil
+      end
+    end
+
+    # Which profile the effective model gets and where that came from
+    # (ModelProfile.resolve: --profile/env, models:, hosts.<name>.profile,
+    # the server's chat template, the name, qwen36). Resolved on first need
+    # and kept, so the system prompt and the server's KV prefix stay stable;
+    # #switch! starts over, and a failed server probe is retried before
+    # the next turn (#refresh_profile!). The kernel follows each resolution.
+    # Kept with the model choice it was resolved for: one that finishes
+    # after a switch is neither kept nor applied (#store_profile).
+    # @return [ModelProfile::Resolution]
+    def profile_resolution
+      choice = @choice
+      cached = @resolution
+      return cached.last if cached&.first.equal?(choice)
+
+      store_profile(choice, resolve_profile(choice))
+    end
+
+    # +choice+'s profile (ModelProfile.resolve; may probe /props), or the
+    # one given to .new.
+    def resolve_profile(choice)
+      given = @given_profile
+      return ModelProfile::Resolution.new(profile: given, source: :given, detail: nil, retry: false) if given
+
+      EffectiveModel.of(@registry, choice).profile_resolution
+    end
+
+    # Keeps +resolution+ as +choice+'s and applies it, unless the model
+    # switched while it was resolved (a /stats on a Bridge thread probing
+    # as a /model ran): then it is only returned, and the new model's is
+    # resolved on its first need.
+    # @return [ModelProfile::Resolution]
+    def store_profile(choice, resolution)
+      @mutex.synchronize do
+        return resolution unless @choice.equal?(choice)
+
+        apply_profile(resolution)
+        @resolution = [choice, resolution]
+      end
+      resolution
+    end
+
+    # Everything that holds a profile follows the resolution: the kernel's
+    # prompt format and parser, and the system prompts built for the old one.
+    def apply_profile(resolution)
+      kept = @resolution&.last
+      @prompt_builder.call&.reset! if kept && kept.profile.name != resolution.profile.name
+      @kernel.call.use_profile!(resolution)
+      resolution
+    end
+
+    # Before a turn: resolve now if nothing has yet, or again if the last
+    # server probe failed (unreachable, or 503 while loading a model). A
+    # profile that changes here drops the cached system prompts.
+    def refresh_profile!
+      choice, kept = @resolution
+      return profile_resolution unless choice.equal?(@choice) && kept.retry?
+
+      store_profile(choice, resolve_profile(choice))
+    end
+
+    # The memory overlay key follows the model sent (ModelOverlay.key_for
+    # its id). A model typed as an alias used to key overlays by the alias
+    # (before aliases were applied there): that key is read when the
+    # target's overlay is missing (KernelLoop#sync_model_key!).
+    def sync_model_key!
+      choice = @choice
+      @model_key = ModelOverlay.key_for(@bare_name.call(choice.name))
+      typed_key = ModelOverlay.key_for(@registry.parse_qualified_model(choice.typed).last)
+      @fallback_model_key = typed_key == @model_key ? nil : typed_key
+      @kernel.call.sync_model_key!(@model_key, fallback: @fallback_model_key)
+    end
+  end
+end

data/lib/samagotchi/send_command/wait_target.rb

@@ -19,11 +19,18 @@ module Samagotchi
       # settle end the wait (TurnCheckpoint.settled_turn). A message merged
       # into a turn starting then falls back to that turn's reply
       # (ReplyWait's turn: without queued:); no id (an older worker), the
-      # next reply.
+      # next reply. A prompt the session was created with has no delivery:
+      # its turn is the id the create gave it (+direct_turn+,
+      # Session#first_turn_id), and nothing can merge into it, so the wait
+      # is for that turn alone (ReplyWait's queued:).
       # @param delivered [SessionManager::DeliverResult, nil] nil when the
       #   message started the session itself (no delivery)
-      def self.first_message(delivered)
-        return new unless delivered
+      # @param direct_turn [String, nil] that first turn's id, for a direct
+      #   start
+      def self.first_message(delivered, direct_turn: nil)
+        return new unless delivered || !direct_turn.to_s.strip.empty?
+
+        return new(turn: direct_turn, report_turn_id: direct_turn, queued: true) if delivered.nil?
 
         new(turn: delivered.enqueued_id, report_turn_id: delivered.enqueued_id)
       end

data/lib/samagotchi/send_command.rb

@@ -521,7 +521,8 @@ module Samagotchi
 
       start = @access.prepare_wait(session.id, session: session, created: true)
       wait_for_reply(session.id, cursor: start.cursor, baseline: start.baseline,
-                                 timeout: options[:timeout], **WaitTarget.first_message(@delivered).to_h)
+                                 timeout: options[:timeout],
+                                 **WaitTarget.first_message(@delivered, direct_turn: session.first_turn_id).to_h)
     end
 
     # What chi send --new asks to create: through the worker (images, a

data/lib/samagotchi/session.rb

@@ -54,6 +54,13 @@ module Samagotchi
     attr_accessor :id, :metadata_version, :mode, :model_name, :working_directory, :messages,
                   :created_at, :updated_at, :status, :last_prompt, :first_preview, :test_run,
                   :used_memory_names
+    # The id the prompt a session is created with gets (SessionManager
+    # .spawn_session), so its first turn is a turn with an id like one sent
+    # later: the worker's first turn takes it as its origin, its reply file
+    # and last_turn carry it, and a wait for it (`chi send --new --wait`,
+    # chi web's create) can name it (`--wait --turn T ID`). nil for a
+    # session created idle, and for one saved before the field existed.
+    attr_accessor :first_turn_id
     # Memories the session was started with (--memory) and memories hidden
     # from it (--mute): the worker rebuilds the same prompt on a respawn.
     # Names as given; the engine normalizes them.
@@ -310,7 +317,7 @@ module Samagotchi
 
     def initialize(id:, mode:, model_name:, working_directory:, messages:, created_at:, updated_at:,
                    metadata_version: METADATA_VERSION, status: STATUS_IDLE, last_prompt: "",
-                   first_preview: "", test_run: false, pending_question: nil,
+                   first_preview: "", first_turn_id: nil, test_run: false, pending_question: nil,
                    used_memory_names: [], project_root: nil,
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
@@ -329,6 +336,7 @@ module Samagotchi
       @status = status
       @last_prompt = last_prompt
       @first_preview = first_preview
+      @first_turn_id = first_turn_id
       @title = title
       @test_run = !!test_run
       self.pending_question = pending_question
@@ -525,12 +533,13 @@ module Samagotchi
       "interrupted_turn" => nil,
       "parent_answers" => nil,
       "working_set_pins" => [],
-      "review" => nil
+      "review" => nil,
+      "first_turn_id" => nil
     }.freeze
 
     # FIELDS a session file has only when set: a session without them saves
     # as it did before they existed.
-    OPTIONAL_FIELDS = %w[review].freeze
+    OPTIONAL_FIELDS = %w[review first_turn_id].freeze
 
     # A session from a parsed session file. +messages+ false leaves the
     # conversation out (the lists' lightweight summaries).