samagotchi 0.154.0 → 0.155.0

data/lib/samagotchi/llm/backend.rb

@@ -19,9 +19,11 @@ module Samagotchi
     # in +messages+ (Engine#run_turn resume_from:); the replies from there on
     # keep the model's reasoning (thought blocks), as within one run. nil:
     # the run starts here, as every other turn's does.
+    # +context+: the run's turn (TurnContext, Engine#generate's), handed down
+    # the tool path explicitly; nil: the backend's own (a bare kernel's).
     class ModelBackend
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
-                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
+                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil, context: nil)
         raise NotImplementedError, "#{self.class}#complete must be implemented"
       end
     end

data/lib/samagotchi/llm/chat_loop.rb

@@ -24,7 +24,7 @@ require_relative "../tool_runner"
 require_relative "../tool_response"
 require_relative "../tool_ids"
 require_relative "../tool_declarations"
-require_relative "../tools/deferred_tools"
+require_relative "../tools/tool_surface"
 require_relative "../tool_loads"
 require_relative "../vision_context"
 require_relative "../log"
@@ -79,8 +79,11 @@ module Samagotchi
       #   prompt's part every session shares (SystemPrompt#stable_length), or nil
       # @param sleeper [#call, nil] waits the given seconds before a dropped
       #   stream's step is asked again (specs pass one that doesn't sleep)
-      def initialize(kernel:, adapter: nil, stable_length: nil, sleeper: nil)
+      # @param context [TurnContext, nil] the turn its helpers read before any
+      #   #complete (a bench building wire messages); a run's replaces it
+      def initialize(kernel:, adapter: nil, stable_length: nil, sleeper: nil, context: nil)
         @kernel = kernel
+        @turn_context = context
         @adapter = adapter
         @stable_length = stable_length
         @sleeper = sleeper || ->(seconds) { sleep(seconds) }
@@ -93,10 +96,14 @@ module Samagotchi
 
       # +reasoning_since+ (ModelBackend#complete): the resumed run's start,
       # the Run's own start then (Run#initialize, #reasoning_boundary).
+      # +context+: the run's turn (TurnContext, Engine#generate's): its
+      # settings are what the requests send, its tool calls run in it; a
+      # bare loop's (#turn_context) when none is given.
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
-                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
+                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil, context: nil)
         raise ArgumentError, "ChatLoop has no adapter" unless @adapter
 
+        @turn_context = context if context
         conversation = Array(messages).map(&:dup)
         Run.new(self, conversation, on_stream_event, cancel_controller, model_name, pending_input, start: reasoning_since)
            .call(max_iterations: max_iterations || 1, cap: KernelLoop.resolve_output_char_cap(max_tool_output_chars))
@@ -108,14 +115,14 @@ module Samagotchi
       end
 
       # Tool definitions for the request: the schemas the native prompts are
-      # rendered from (the kernel's registry, the tools the turn's LLM
-      # context layers offer), with the chat-only enums and closed
-      # parameters. On an adapter that loads tools for +model+
-      # (#loads_tools?), every tool the session reaches but doesn't declare
-      # follows, deferred (Tools::DeferredTools: +conversation+, the
+      # rendered from (the turn's ToolSurface: what it declares), with the
+      # chat-only enums and closed parameters. On an adapter that loads
+      # tools for +model+ (#loads_tools?, asked per request: a refusal turns
+      # it off mid-turn), every tool the session reaches but doesn't declare
+      # follows, deferred (ToolSurface#deferred_for: +conversation+, the
       # request's, names the ones it loaded); never without a declared one.
       def tool_definitions(conversation = nil, model: nil)
-        declared = ToolDeclarations.chat_schemas(tools.schemas(layers: llm_context_layers)).map do |schema|
+        declared = ToolDeclarations.chat_schemas(surface.schemas).map do |schema|
           { type: "function", function: schema.slice(:name, :description, :parameters) }
         end
         return declared if declared.empty? || !loads_tools?(model)
@@ -127,10 +134,13 @@ module Samagotchi
       end
 
       # The tools a request on a host that loads tools declares deferred
-      # (Tools::DeferredTools).
-      def deferred_tools(conversation)
-        Tools::DeferredTools.list(tools, conversation, layers: llm_context_layers)
-      end
+      # (ToolSurface#deferred_for).
+      def deferred_tools(conversation) = surface.deferred_for(conversation)
+
+      # The turn's ToolSurface (#turn_context's), else one computed now from
+      # the kernel's tools (a bare loop).
+      # @return [Tools::ToolSurface]
+      def surface = Tools::ToolSurface.of(turn_context, tools)
 
       # Whether the adapter takes tools it doesn't declare up front for
       # +model+ (AnthropicMessages#loads_tools?); OpenAIChat doesn't.
@@ -147,22 +157,33 @@ module Samagotchi
       # The kernel's tools.
       def tools = @kernel.tools
 
-      # The turn's LLM context layers (KernelLoop#llm_context_layers).
-      def llm_context_layers = @kernel.llm_context_layers
+      # The TurnContext of the run in progress, else of the last run
+      # (#complete's context:); before any, the one it was built with, else a
+      # context of the kernel's own settings (a bare loop). Read on the turn's thread only.
+      # @return [TurnContext]
+      def turn_context = @turn_context || TurnContext.none(settings: @kernel.turn_settings)
+
+      # The turn's LLM::TurnSettings (#turn_context's).
+      def settings = turn_context.settings
+
+      # The turn's LLM context layers (TurnContext#llm_context_layers).
+      def llm_context_layers = turn_context.llm_context_layers
 
       # The turn's LLM context strategy (LLMContextStrategy::Resolved), nil
       # when none was resolved.
-      def llm_context = @kernel.turn_settings&.llm_context
+      def llm_context = settings&.llm_context
 
       # KernelLoop#reprefilled_tokens, the kernel's request history.
       def reprefilled_tokens(model, **) = @kernel.reprefilled_tokens(model, **)
 
-      # The kernel's LLMContextView, the turn's strategy.
-      def llm_context_view = @kernel.llm_context_view
+      # The kernel's LLMContextView under the turn's strategy.
+      def llm_context_view = @kernel.llm_context_view(llm_context)
 
       # The strategy's own edits before a request and at turn end
-      # (KernelLoop#apply_llm_context!).
-      def apply_llm_context!(conversation, **) = @kernel.apply_llm_context!(conversation, **)
+      # (KernelLoop#apply_llm_context!), under the turn's strategy.
+      def apply_llm_context!(conversation, **)
+        @kernel.apply_llm_context!(conversation, llm_context, model: settings&.model_name, **)
+      end
 
       # The running turn, for forget_outputs (KernelLoop#llm_context_turn).
       def llm_context_turn=(turn)
@@ -267,7 +288,7 @@ module Samagotchi
       TOOL_IMAGES_TEXT = "[images from tool results]"
 
       # Whether this turn's requests carry tool changes (the turn's model).
-      def tool_change_wire? = tool_changes?(@kernel.turn_settings&.model_name)
+      def tool_change_wire? = tool_changes?(settings&.model_name)
 
       # The first index whose model entries carry their reasoning (nil:
       # none do) under +level+. Under turn: +since+ when given, where a
@@ -298,14 +319,14 @@ module Samagotchi
         conversation.drop(boundary).sum { |entry| entry[:role].to_s == "model" && thought?(entry) ? entry[:thinking].length : 0 }
       end
 
-      # The turn's ReasoningHistory level (the kernel's turn_settings); drop
+      # The turn's ReasoningHistory level (the turn's settings); drop
       # without settings, and for a +model+ whose host refused it
       # (#reasoning_history_refused!). An adapter that sends its blocks back
       # (#replays_content?) is floored at turn: the running run's thinking
       # blocks always go back (a tool loop with thinking needs the last
       # assistant turn's), whatever the level says.
       def reasoning_history(model = nil)
-        level = model && @refusals.refused?(:reasoning_history, model) ? :drop : @kernel.turn_settings&.reasoning_history
+        level = model && @refusals.refused?(:reasoning_history, model) ? :drop : settings&.reasoning_history
         level ||= :drop
         level == :drop && replays_content? ? :turn : level
       end
@@ -320,18 +341,17 @@ module Samagotchi
         @refusals.remember(:reasoning_history, model)
       end
 
-      # The turn's VisionContext (the Engine sets the kernel's
-      # turn_settings), or nil.
-      def vision = @kernel.turn_settings.vision
+      # The turn's VisionContext (its settings'), or nil.
+      def vision = settings.vision
 
-      # The turn's configured price (the kernel's turn_settings), or nil.
-      def price = (@kernel.turn_settings&.price if @kernel.respond_to?(:turn_settings))
+      # The turn's configured price (its settings'), or nil.
+      def price = settings&.price
 
-      # The turn's request parameters (the kernel's turn_settings).
-      def sampling = @kernel.turn_settings.sampling || {}
+      # The turn's request parameters (its settings').
+      def sampling = settings.sampling || {}
 
-      # The turn's thinking level (the kernel's turn_settings).
-      def thinking = @kernel.turn_settings.thinking || Thinking::DEFAULT
+      # The turn's thinking level (its settings').
+      def thinking = settings.thinking || Thinking::DEFAULT
 
       # The request fields the thinking level adds, as the adapter's wire
       # takes them (OpenAIChat#thinking_fields: Thinking.chat_fields); none
@@ -375,24 +395,24 @@ module Samagotchi
       def strip_model_thought(text) = @kernel.strip_model_thought(text)
 
       def tool_runner
-        @tool_runner ||= ToolRunner.new(@kernel, window: -> { context_window(@kernel.turn_settings&.model_name) })
+        @tool_runner ||= ToolRunner.new(@kernel, window: ->(run_settings) { context_window(run_settings&.model_name, run_settings) })
       end
 
       # The window for +model+: the kernel's client probes the server it
       # points at (Engine keeps it on the effective model's host; a local
       # llama.cpp answers /props), then the host's model list, the model's
       # or host's window_tokens, config, env and the default. A remote
-      # provider has no /props to probe.
-      def context_window(model)
+      # provider has no /props to probe. +run_settings+: the LLM::TurnSettings
+      # whose window_setting counts (the turn's by default).
+      def context_window(model, run_settings = settings)
         client = @adapter.remote? ? nil : @kernel.client
-        ContextWindow.resolve(client: client, model: model, adapter: @adapter,
-                              setting: (@kernel.turn_settings&.window_setting if @kernel.respond_to?(:turn_settings)))
+        ContextWindow.resolve(client: client, model: model, adapter: @adapter, setting: run_settings&.window_setting)
       rescue StandardError
         nil
       end
 
-      # The kernel's generation guard (KernelLoop#guard_generation).
-      def guard_generation = @kernel.respond_to?(:guard_generation) ? @kernel.guard_generation : nil
+      # The kernel's generation guard for the turn (KernelLoop#guard_generation).
+      def guard_generation = @kernel.respond_to?(:guard_generation) ? @kernel.guard_generation(turn_context) : nil
 
       # A hook failing must not break the turn (as in ToolRunner).
       def fire_hook(name, event)
@@ -432,7 +452,8 @@ module Samagotchi
       # Array), plus a model turn's tool_calls and thinking (the host's
       # reasoning, sent back as #wire_messages says), a result's tool_call_id, the image
       # refs of a user message or a tool result, a prompt's turn_id and its
-      # Verify/Revise anchors (Engine, never sent) and a wake turn's report's turn_start (Steer, never sent), and a plugin tool result's tool_params and tool_labels
+      # Verify/Revise anchors (Engine, never sent), an opening's opening_id
+      # (TurnFlow#abort_continue!'s reason line, never sent) and a wake turn's report's turn_start (Steer, never sent), and a plugin tool result's tool_params and tool_labels
       # (the live row's params line and label, never sent back), an
       # edit/write result's tool_diffs (never sent), an empty-answer
       # note's marker (TurnNote.empty, never sent), and an answer's display
@@ -448,6 +469,7 @@ module Samagotchi
           message[:tool_call_id] = entry[:tool_call_id] if entry[:tool_call_id]
           message[:images] = entry[:images] if entry[:images].is_a?(Array) && !entry[:images].empty?
           message[:turn_id] = entry[:turn_id] if entry[:turn_id]
+          message[:opening_id] = entry[:opening_id] if entry[:opening_id].is_a?(String)
           message[:turn_start] = true if entry[:turn_start] == true
           message[:verify] = entry[:verify] if entry[:verify].is_a?(Hash)
           message[:revises] = entry[:revises] if entry[:revises].is_a?(Hash)
@@ -607,8 +629,10 @@ module Samagotchi
           @deferred = []
           @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context,
                                        counted_chars_per_token: loop.counted_chars_per_token)
+          # The run's turn: its tool calls run in it.
+          @turn_context = loop.turn_context
           loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context,
-                                                             emit: method(:emit))
+                                                             emit: method(:emit), turn_id: @turn_context.id)
         end
 
         def call(max_iterations:, cap:)
@@ -1092,7 +1116,7 @@ module Samagotchi
         def dispatch(tool_calls, iteration, cap)
           log_direct_deferred(tool_calls)
           calls = tool_calls.map { |tool_call| NativeToolNormalizer.normalize(tool_call) }
-          runs = ToolResponse.run_batch(@loop.tool_runner, calls, iteration: iteration, emit: method(:emit),
+          runs = ToolResponse.run_batch(@loop.tool_runner, calls, context: @turn_context, iteration: iteration, emit: method(:emit),
                                                                   on_stream_event: @on_stream_event, cap: cap) do |run, index|
             @conversation << ToolResponse.single(run, tool_call_id: tool_calls[index].id,
                                                       ids: ToolIds.next_ids(@conversation, 1))

data/lib/samagotchi/llm/native_backend.rb

@@ -17,7 +17,7 @@ module Samagotchi
       def provider = :native
 
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
-                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
+                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil, context: nil)
         @kernel.run(
           messages,
           max_iterations: max_iterations,
@@ -26,7 +26,8 @@ module Samagotchi
           model_name: model_name,
           max_tool_output_chars: max_tool_output_chars,
           pending_input: pending_input,
-          reasoning_since: reasoning_since
+          reasoning_since: reasoning_since,
+          context: context || @kernel.context
         )
       end
     end

data/lib/samagotchi/llm_context_forget.rb

@@ -52,9 +52,11 @@ module Samagotchi
     # The turn a forget_outputs call runs in: its conversation (the
     # entries the edits are saved on), its ContextStatus (nil: none) and
     # its stream (+emit+, nil: none), which gets an applied batch's ✂ row
-    # (LLMContextNotice).
-    Turn = Data.define(:conversation, :context, :emit) do
-      def initialize(emit: nil, **fields) = super
+    # (LLMContextNotice); +turn_id+: the Engine turn the run is for
+    # (TurnContext#id; nil: none), so a reader tells the running turn's
+    # conversation from the last one's (Engine#live_conversation).
+    Turn = Data.define(:conversation, :context, :emit, :turn_id) do
+      def initialize(emit: nil, turn_id: nil, **fields) = super
     end
 
     # One output a call may name: its entry, its ToolIds ref, its tool,

data/lib/samagotchi/model_binding.rb

@@ -8,7 +8,7 @@ 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!).
+  # (#sync_model_key!), which each turn's TurnContext takes.
   #
   # 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
@@ -126,13 +126,13 @@ module Samagotchi
     # 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!).
+    # target's overlay is missing. A turn takes both in its TurnContext
+    # (Engine#generate): memory_read and the gate read them there.
     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/plugin/prompt_sections.rb

@@ -63,6 +63,13 @@ module Samagotchi
         @mutex.synchronize { @sections.any? { |section| section.bundle == bundle.to_s && section.name == name.to_s } }
       end
 
+      # The names +bundle+ registered, in prompt order (what it registered, for
+      # Testing::Install and chi bundle check).
+      # @return [Array<String>]
+      def names(bundle)
+        @mutex.synchronize { @sections.select { |section| section.bundle == bundle.to_s }.map(&:name) }
+      end
+
       # Run every block for +session_id+ and keep what they gave.
       # @param session_id [String, nil] whose last good text a failure keeps
       # @return [Array<Built>] in prompt order, the sections with text

data/lib/samagotchi/question_desk.rb

@@ -118,7 +118,7 @@ module Samagotchi
     end
 
     # Ask the model's question (ask_user_question): the kernel's
-    # question_handler, called on the turn thread with the payload
+    # Services#question_handler, called on the turn thread with the payload
     # Tools::AskUserQuestion.validate made. Opens it (#open_question) and
     # returns the answer as JSON for the tool result.
     # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:},

data/lib/samagotchi/revise_anchor.rb

@@ -5,7 +5,7 @@ require_relative "verify_anchor"
 module Samagotchi
   # The earlier turn a Revise turn rewrites the answer of, carried only by
   # a Revise turn (TurnAnchors). Its stamp on the turn's opening message
-  # is display metadata, never in the prompt (Engine#revision_target).
+  # is display metadata, never in the prompt (TurnStages::VerifyAnchors#revision_target).
   ReviseAnchor = Data.define(:turn_id) do
     def self.from(value)
       return value if value.is_a?(self)

data/lib/samagotchi/session_manager.rb

@@ -33,6 +33,7 @@ require_relative "worker_idle_exit"
 require_relative "worker_signals"
 require_relative "chi_invocation"
 require_relative "log"
+require_relative "degrade"
 require_relative "log_path"
 require_relative "paths"
 require_relative "project_env"
@@ -282,7 +283,7 @@ module Samagotchi
       child_env[ModelProfile::MODEL_FROM_CLI_ENV] = "1" if child_env.key?(ModelProfile::MODEL_ENV)
       # And the spawner's debug log, absolute: a relative log.file would
       # otherwise land in the worker's (the session's) directory.
-      log_path = begin LogPath.resolve rescue nil end
+      log_path = begin LogPath.resolve rescue nil end # degrade-ok: no log to say it in; the worker's is off (below)
       if log_path
         child_env["SAMAGOTCHI_LOG_FILE"] = log_path
       else
@@ -936,9 +937,7 @@ module Samagotchi
     # session.keep_empty off: sessions left with nothing in them are deleted
     # (the worker as it exits, the retention sweep).
     def self.discard_empty?
-      Samagotchi::Config.get("session.keep_empty") != true
-    rescue StandardError
-      false
+      Degrade.call(:config, "keep_empty_unreadable", fallback: false) { Samagotchi::Config.get("session.keep_empty") != true }
     end
 
     # Whether a session being left (or found left) is deleted: session.keep_empty
@@ -977,9 +976,9 @@ module Samagotchi
       return true if one.to_s == other.to_s
       return false if one.nil? || other.nil?
 
-      ConfigFile.model_ref(one).ref == ConfigFile.model_ref(other).ref
-    rescue StandardError
-      false
+      Degrade.call(:config, "model_ref_unresolved", fallback: false) do
+        ConfigFile.model_ref(one).ref == ConfigFile.model_ref(other).ref
+      end
     end
 
     # Only the system prompt (an Engine seeds one, a saved session keeps
@@ -1281,9 +1280,7 @@ module Samagotchi
     end
 
     def self.config_idle_exit_minutes
-      Samagotchi::Config.get("session.idle_exit_minutes")
-    rescue StandardError
-      nil
+      Degrade.call(:config, "idle_exit_minutes_unreadable") { Samagotchi::Config.get("session.idle_exit_minutes") }
     end
 
     private_class_method def self.setup_session_directory(session_dir, session, state_dir:)
@@ -1640,9 +1637,7 @@ module Samagotchi
     end
 
     private_class_method def self.delivery_owner(manager, session_id, state_dir)
-      manager.session_owner(session_id, state_dir: state_dir)
-    rescue StandardError
-      nil
+      Degrade.call(:worker, "owner_unreadable", sid: session_id) { manager.session_owner(session_id, state_dir: state_dir) }
     end
 
     def self.stopped_on_disk?(session_id, state_dir:)

data/lib/samagotchi/session_retention.rb

@@ -18,7 +18,7 @@ module Samagotchi
   # (session.retention_days), count (session.max_count, counting only the
   # sessions that stay), statuses kept (session.keep_status), sessions left
   # empty (SessionManager.discardable?, an hour on), leftover scratch
-  # sessions and skeleton-only directories; a session with a live owner
+  # sessions (once past SCRATCH_START_GRACE) and skeleton-only directories; a session with a live owner
   # always stays.
   module SessionRetention
     # The session.retention_days / max_count / keep_status defaults.
@@ -93,6 +93,16 @@ module Samagotchi
       end
     end
 
+    # How long after its save an unowned scratch session may still be
+    # waiting for the worker just spawned for it to take its owner lock.
+    SCRATCH_START_GRACE = SessionManager::WORKER_START_GRACE
+
+    private_class_method def self.scratch_starting?(path, now)
+      now - File.mtime(path) < SCRATCH_START_GRACE
+    rescue SystemCallError
+      false
+    end
+
     # Lazy sweep guard: runs prune at most once per SWEEP_INTERVAL_HOURS
     # (session.sweep_interval_hours).
     MARKER = ".last_retention"
@@ -162,7 +172,9 @@ module Samagotchi
     # count (`chi sessions clean` with no --days: test runs are throwaway).
     #
     # A scratch session nobody owns (its terminal and worker were killed) goes whatever its
-    # age, its status and the count; +test_only+ takes it too.
+    # age, its status and the count; +test_only+ takes it too. One saved
+    # within SCRATCH_START_GRACE (its file's mtime, against +now+) stays: its
+    # worker may not have taken the owner lock yet.
     #
     # +max_count+ counts the sessions that stay: one deleted whatever its
     # place (scratch, left empty, expired, +any_age+) takes no slot.
@@ -173,7 +185,7 @@ module Samagotchi
     # @return [Hash] { deleted: [ids], kept: [ids], skipped: [ids] }
     def self.apply(state_dir: Session.default_state_dir, days: DEFAULT_RETENTION_DAYS, max_count: DEFAULT_MAX_COUNT,
                    keep_status: DEFAULT_KEEP_STATUS, dry_run: false, test_only: false, alive_check: nil,
-                   empty_check: nil, any_age: false)
+                   empty_check: nil, any_age: false, now: Time.now)
       keep_status = Array(keep_status).map(&:to_s)
       # Fetch all sessions sorted newest-first for count logic
       all = Session.list(state_dir: state_dir, sort: "updated_at", order: "desc")
@@ -182,7 +194,6 @@ module Samagotchi
         all = all.select { |session| session.test_run || session.scratch }
       end
 
-      now = Time.now
       cutoff = days.to_i.positive? ? now - (days.to_i * 86_400) : nil
       max = max_count.to_i
 
@@ -217,6 +228,15 @@ module Samagotchi
           end
         end
 
+        # A scratch session saved within SCRATCH_START_GRACE: `chi scratch`
+        # saves it, then spawns the worker that takes its owner lock, so no
+        # owner yet doesn't mean a leftover. Kept, it takes no count slot.
+        if session.scratch && scratch_starting?(path, now)
+          kept << session.id
+          passed_over += 1
+          next
+        end
+
         left_empty = begin
           empty_check&.call(session.id)
         rescue StandardError

data/lib/samagotchi/steer.rb

@@ -28,6 +28,12 @@ module Samagotchi
   module Steer
     KIND = "steer"
     INPUT_KIND = "input"
+    # KernelLoop's line asking a Qwen model to finish the tool call it left
+    # open: a user line inside the running turn, the model's alone. No turn
+    # opens with it (#turn_prompt?), and the page draws nothing for it, as it
+    # showed nothing live. Its kind adds no header (#header): its bytes go
+    # out as before it had one.
+    RECOVERY_KIND = "recovery"
 
     # A drain item for an input line with its sender (source nil = the user).
     # A plain String is still a valid item: the user's line. +mark+: fields
@@ -317,6 +323,11 @@ module Samagotchi
       message.is_a?(Hash) && (message[:role] || message["role"]).to_s == "user" && !steer?(message)
     end
 
+    # KernelLoop's recovery line (RECOVERY_KIND).
+    def recovery?(message)
+      message.is_a?(Hash) && (message[:kind] || message["kind"]).to_s == RECOVERY_KIND
+    end
+
     # The user's lines merged into a running turn (Merge#messages).
     def input?(message)
       message.is_a?(Hash) && (message[:kind] || message["kind"]).to_s == INPUT_KIND
@@ -333,7 +344,7 @@ module Samagotchi
       start = (message[:turn_start] || message["turn_start"]) == true
       return start if (message[:role] || message["role"]).to_s == "system"
 
-      prompt?(message) && (!input?(message) || start)
+      prompt?(message) && !recovery?(message) && (!input?(message) || start)
     end
 
     # A stored `!shell` line: "!(cmd)\n<output>", no turn id. A user message,

data/lib/samagotchi/stream_event.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "degrade"
+
+module Samagotchi
+  # The one rule for handing a loop event to its on_stream_event callback
+  # (KernelLoop#emit_stream_event, ToolRunner#emit): no callback is fine, and
+  # a failing one (a UI gone) must not break the turn or the tool call. Its
+  # failure is a Degrade record under :turn, named by the caller (+failure+,
+  # so a log still says which side lost the event), with the event's type.
+  module StreamEvent
+    module_function
+
+    # @param callback [#call, nil] the loop's on_stream_event
+    # @param event [Hash] the event
+    # @param failure [String] the Degrade event slug when +callback+ raises
+    # @return the callback's value, nil when it raised or there is none
+    def emit(callback, event, failure:)
+      Degrade.call(:turn, failure, type: (event[:type] if event.is_a?(Hash))) { callback&.call(event) }
+    end
+  end
+end