samagotchi 0.2.0 → 0.4.0

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -94,14 +94,23 @@ module Samagotchi
         end
       end
 
+      # Yields [name, data] for each installed bundle with hooks, by name.
+      # A manifest that doesn't parse is yielded as {error:} when its
+      # bundle has a hooks/ dir, and skipped otherwise; the rest still load.
       def self.each_installed_holding_hooks
         return enum_for(:each_installed_holding_hooks) unless block_given?
         dir = self.bundles_dir
         return unless Dir.exist?(dir)
         Dir[File.join(dir, "*", "manifest.json")].sort.each do |mjson|
-          data = JSON.parse(File.read(mjson), symbolize_names: true)
-          next unless data && data[:hooks].is_a?(Hash) && !data[:hooks].empty?
-          yield File.basename(File.dirname(mjson)), data
+          name = File.basename(File.dirname(mjson))
+          begin
+            data = JSON.parse(File.read(mjson), symbolize_names: true)
+          rescue JSON::ParserError, SystemCallError => e
+            yield name, { error: "manifest.json is unreadable: #{e.message}" } if Dir.exist?(File.join(File.dirname(mjson), "hooks"))
+            next
+          end
+          next unless data.is_a?(Hash) && data[:hooks].is_a?(Hash) && !data[:hooks].empty?
+          yield name, data
         end
       end
 
@@ -116,8 +125,10 @@ module Samagotchi
       #   snapshot
       # @param requires_chi [String, nil] the manifest's requirement
       # @param needs [Array<Hash>] the manifest's needs ({command:, why:, hint:})
+      # @param conflicts [Array<String>] files an upgrade kept with local
+      #   edits that conflict with it; their entries get conflict: true
       def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
-                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil)
+                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [])
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -134,6 +145,7 @@ module Samagotchi
           # Save base snapshot — use file_key as-is (it already includes .md).
           File.write(File.join(bases_dir, file_key), content)
           merged_entries[file_key] = { checksum: checksum }
+          merged_entries[file_key][:conflict] = true if conflicts.include?(file_key.to_s)
         end
 
         # Prune stale base snapshots for files no longer in the bundle.
@@ -226,14 +238,29 @@ module Samagotchi
         manifest_data["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
         manifest_data["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } if needs.is_a?(Array) && !needs.empty?
 
-        # Write aside and rename, so a reader in another process (a parallel
-        # chi start) never parses a truncated manifest.json.
-        manifest_path = File.join(@bundle_dir, "manifest.json")
-        tmp_path = "#{manifest_path}.#{Process.pid}.tmp"
-        File.write(tmp_path, JSON.pretty_generate(manifest_data))
-        File.rename(tmp_path, manifest_path)
-      ensure
-        FileUtils.rm_f(tmp_path) if tmp_path
+        write_manifest(manifest_data)
+      end
+
+      # After a conflict was resolved by hand: each file's base becomes the
+      # bundle's version (the incoming file, else what's on disk now) and
+      # its conflict mark goes. The rest of the manifest stays as is.
+      # @param conflicts [Hash{String => Hash}] Installer#conflicts
+      def resolve_conflicts(conflicts)
+        return unless installed?
+
+        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        raw["files"] ||= {}
+        conflicts.each do |file_key, info|
+          key = file_key.to_s
+          next unless raw["files"].key?(key)
+          src = [info[:incoming], info[:current]].find { |p| p && File.exist?(p) }
+          next unless src
+
+          content = File.read(src)
+          File.write(base_path(key), content)
+          raw["files"][key] = { "checksum" => Digest::SHA256.hexdigest(content) }
+        end
+        write_manifest(raw)
       end
 
       # Reads provenance data (returns nil if not installed).
@@ -243,6 +270,18 @@ module Samagotchi
         JSON.parse(File.read(manifest_path), symbolize_names: true)
       end
 
+      # Write aside and rename, so a reader in another process (a parallel
+      # chi start) never parses a truncated manifest.json.
+      def write_manifest(manifest_data)
+        manifest_path = File.join(@bundle_dir, "manifest.json")
+        tmp_path = "#{manifest_path}.#{Process.pid}.tmp"
+        File.write(tmp_path, JSON.pretty_generate(manifest_data))
+        File.rename(tmp_path, manifest_path)
+      ensure
+        FileUtils.rm_f(tmp_path) if tmp_path
+      end
+      private :write_manifest
+
       # Returns the path to a base snapshot for a given file key.
       def base_path(file_key)
         File.join(@bundle_dir, "bases", file_key)

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require_relative "installer"
+require_relative "listing"
+require_relative "manifest"
+require_relative "merger"
+require_relative "provenance"
+require_relative "source"
+require_relative "status"
+require_relative "system_bundle"
+require_relative "../version"
+
+module Samagotchi
+  module MemoryBundle
+    # What `chi update` does to the installed bundles that chi ships: one
+    # Row per installed bundle (the system bundle aside: SystemBundle.sync
+    # has it). A bundle is updated when it was installed from a shipped dir
+    # (its source is …/lib/samagotchi/bundles/<dir>, in a gem or a
+    # checkout), chi ships it under the same name, the shipped version is
+    # newer and this chi meets its requires_chi. It never installs a
+    # bundle that isn't installed and never downgrades.
+    #
+    # .md files take the Installer's 3-way merge: a conflict keeps the
+    # user's file (kept). Hooks, rules and the plugin are replaced; an
+    # edited one (which didn't load: its sha no longer matched) is listed
+    # in replaced.
+    module ShippedUpdate
+      # status: :would_update (plan), :updated, :up_to_date, :skipped,
+      # :failed. note says why for skipped/failed. kept and replaced are
+      # file names; under plan they are what apply would keep or replace.
+      Row = Struct.new(:name, :from, :to, :status, :note, :kept, :replaced, :source_dir, :scope, keyword_init: true)
+
+      SHIPPED_SOURCE = %r{/lib/samagotchi/bundles/[^/]+/?\z}
+
+      module_function
+
+      # Read-only.
+      # @return [Array<Row>] by name
+      def plan(shipped_dir: SourceNormalizer::SHIPPED_DIR, chi_version: Samagotchi::VERSION)
+        shipped = Listing.shipped(dir: shipped_dir).to_h { |s| [s.name, s] }
+        installed_names.map do |name|
+          plan_row(name, shipped[name], shipped_dir, chi_version)
+        end
+      end
+
+      # The shipped bundles not installed (what the footer lists).
+      # @return [Array<Listing::Shipped>]
+      def not_installed(shipped_dir: SourceNormalizer::SHIPPED_DIR)
+        names = installed_names
+        Listing.shipped(dir: shipped_dir).reject { |s| names.include?(s.name) }
+      end
+
+      # Runs the Installer for each :would_update row; the others pass
+      # through. A failing bundle doesn't stop the rest.
+      # @return [Array<Row>]
+      def apply(rows)
+        rows.map do |row|
+          next row unless row.status == :would_update
+
+          installer = Installer.new(source: row.source_dir, name: row.name, scope: row.scope, strict: true, upgrade: true)
+          installer.run
+          row.dup.tap do |r|
+            r.status = :updated
+            r.kept = installer.conflicts.keys
+          end
+        rescue StandardError => e
+          row.dup.tap do |r|
+            r.status = :failed
+            r.note = e.message.lines.first.to_s.strip
+          end
+        end
+      end
+
+      def installed_names
+        dir = Provenance.bundles_dir
+        return [] unless File.directory?(dir)
+
+        Dir.children(dir).reject { |e| e.start_with?(".") || e == SystemBundle::BUNDLE_NAME }
+           .select { |e| File.file?(File.join(dir, e, "manifest.json")) }.sort
+      end
+
+      def plan_row(name, ship, shipped_dir, chi_version)
+        row = Row.new(name: name, kept: [], replaced: [])
+        data = begin
+          Provenance.new(name: name).read
+        rescue JSON::ParserError, SystemCallError
+          nil
+        end
+        return skip(row, "manifest.json unreadable") unless data.is_a?(Hash)
+
+        row.from = data[:version].to_s
+        row.scope = data[:scope].to_s.empty? ? "system" : data[:scope].to_s
+        return skip(row, "not from chi") unless ship && data[:source].to_s.match?(SHIPPED_SOURCE)
+
+        row.to = ship.version.to_s
+        return skip(row, "newer than shipped: left") if Listing.newer?(row.from, row.to)
+        return row.tap { |r| r.status = :up_to_date; r.to = nil } unless Listing.newer?(row.to, row.from)
+
+        row.source_dir = File.join(shipped_dir, ship.source)
+        manifest = Manifest.read(dir: row.source_dir)
+        if Manifest.requires_chi_failure(manifest.requires_chi, chi_version)
+          return skip(row, "needs chi #{manifest.requires_chi}", keep_to: true)
+        end
+        return skip(row, "project scope: chi bundle upgrade #{ship.source} in the project") if row.scope == "project"
+
+        row.kept = conflicts(row, data)
+        row.replaced = edited_executables(name, data)
+        row.status = :would_update
+        row
+      end
+
+      def skip(row, note, keep_to: false)
+        row.to = nil unless keep_to
+        row.status = :skipped
+        row.note = note
+        row
+      end
+
+      # The .md files whose local edits conflict with the shipped version.
+      def conflicts(row, data)
+        provenance = Provenance.new(name: row.name)
+        target_dir = Status.resolve_target_dir(row.scope)
+        return [] unless data[:files]
+
+        Dir.glob(File.join(row.source_dir, "*.md")).map { |f| File.basename(f) }.sort.select do |key|
+          Merger.classify(base_path: provenance.base_path(key), current_path: File.join(target_dir, key),
+                          incoming_path: File.join(row.source_dir, key)) == :conflict
+        end
+      end
+
+      # Installed hooks, rules and the plugin whose sha differs from the
+      # recorded one (they didn't load), as hooks/F, guardrails/F, plugin/F.
+      def edited_executables(name, data)
+        provenance = Provenance.new(name: name)
+        edited = []
+        (data[:hooks] || {}).each do |file, meta|
+          edited << "hooks/#{file}" if edited?(File.join(provenance.hooks_dir, file.to_s), meta)
+        end
+        (data[:guardrails] || {}).each do |file, meta|
+          edited << "guardrails/#{file}" if edited?(File.join(provenance.guardrails_dir, file.to_s), meta)
+        end
+        plugin = provenance.plugin_path(data)
+        edited << "plugin/#{File.basename(plugin)}" if plugin && edited?(plugin, data[:plugin])
+        edited
+      end
+
+      def edited?(path, meta)
+        recorded = meta.is_a?(Hash) ? meta[:sha256].to_s.delete_prefix("sha256:") : ""
+        return false if recorded.empty? || !File.file?(path)
+
+        Digest::SHA256.hexdigest(File.binread(path)) != recorded
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/status.rb

@@ -31,6 +31,7 @@ module Samagotchi
           missing = !File.exist?(target_path)
           index_present = index_has_entry?(scope, file_key_str)
           details[file_key_str] = {
+            conflict: meta.is_a?(Hash) && meta[:conflict] == true,
             stored_checksum: stored_checksum,
             current_checksum: current_checksum,
             base_checksum: base_checksum,
@@ -96,11 +97,13 @@ module Samagotchi
         end
       end
 
+      # Index lines name the entry without ".md" (Installer#update_target_index,
+      # memory_write); a legacy "name.md" line counts too.
       def self.index_has_entry?(scope, file_key)
         path = IndexUpdater.index_path_for(scope)
         return false unless path && File.exist?(path)
         content = File.read(path)
-        content.match?(IndexUpdater.managed_pattern(file_key))
+        [file_key.delete_suffix(".md"), file_key].uniq.any? { |name| content.match?(IndexUpdater.managed_pattern(name)) }
       end
     end
   end

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require_relative "installer"
 require_relative "provenance"
 require_relative "manifest"
+require_relative "merger"
 require_relative "../log"
 
 module Samagotchi
@@ -27,40 +28,72 @@ module Samagotchi
 
       module_function
 
+      # What sync did (or, with dry_run, would do). status is :installed,
+      # :updated, :restored (missing files put back), :up_to_date,
+      # :newer_installed (left as is), :skipped (SKIP_ENV or no shipped
+      # bundle) or :failed (error: says why); kept lists the files whose
+      # local edits conflicted with the update and were kept.
+      Result = Struct.new(:from, :to, :status, :kept, :warnings, :error, keyword_init: true) do
+        def changed? = %i[installed updated restored].include?(status)
+      end
+
       # Ensure the system bundle is installed and up-to-date.
       # Idempotent and warn-only: never raises to callers.
       # Safe for TUI and non-TUI (web/worker) paths — Engine calls this.
       def ensure!
-        return false if skip?
-        return false unless File.directory?(GEM_BUNDLE_DIR)
+        result = sync
+        case result.status
+        when :failed
+          Log.error(:memory, "system_bundle_failed", echo: "[samagotchi-system] #{result.error}")
+        when :newer_installed
+          with_lock { note_newer_installed(result.from, result.to) }
+        end
+        result.kept.each do |file_key|
+          Log.info(:memory, "system_local_edit_kept", echo: "[samagotchi-system] kept local edit in #{file_key} (bundle v#{result.to} has update — run: chi bundle status #{BUNDLE_NAME} / chi bundle diff #{BUNDLE_NAME} #{file_key})", file: file_key.to_s)
+        end
+        result.warnings.each { |w| Log.warn(:memory, "system_bundle_warning", echo: "[samagotchi-system] #{w}") }
+        result.changed?
+      end
+
+      # Install, upgrade or repair the installed system bundle to match the
+      # shipped one, under the lock. Never raises; logs nothing (ensure!
+      # and chi update report the Result).
+      # @param dry_run [Boolean] classify only, write nothing
+      # @return [Result]
+      def sync(dry_run: false)
+        return result(:skipped, error: "#{SKIP_ENV} is set") if skip?
+        return result(:skipped, error: "no shipped system bundle") unless File.directory?(GEM_BUNDLE_DIR)
 
         begin
           gem_manifest = Manifest.read(dir: GEM_BUNDLE_DIR)
         rescue Manifest::ValidationError => e
-          Log.error(:memory, "system_manifest_invalid", echo: "[samagotchi-system] invalid gem manifest: #{e.message}")
-          return false
+          return result(:failed, error: "invalid gem manifest: #{e.message}")
         end
+        to = gem_manifest.version.to_s
 
         with_lock do
           data = Provenance.new(name: BUNDLE_NAME).read
+          from = data && data[:version].to_s
 
           if data.nil?
-            install_fresh(gem_manifest)
-          elsif installed_newer?(data[:version], gem_manifest.version)
+            dry_run ? result(:installed, to: to) : install_fresh(to)
+          elsif installed_newer?(from, to)
             # Running an older checkout/gem: never downgrade the user's system memories
             # (not even to restore a missing file). `chi self` shows installed vs shipped.
-            note_newer_installed(data[:version], gem_manifest.version)
-            false
-          elsif data[:version].to_s != gem_manifest.version.to_s
-            upgrade_existing(gem_manifest, data)
+            result(:newer_installed, from: from, to: to)
+          elsif from != to
+            dry_run ? result(:updated, from: from, to: to, kept: conflicting(gem_manifest)) : upgrade_existing(from, to)
           else
             # Already at desired version — still verify files present (e.g. user deleted one)
-            verify_files_present(gem_manifest, data)
+            verify_files_present(gem_manifest, from, dry_run)
           end
         end
       rescue StandardError => e
-        Log.error(:memory, "system_bundle_failed", echo: "[samagotchi-system] ensure failed: #{e.class}: #{e.message}", error: e.class.name)
-        false
+        result(:failed, error: "ensure failed: #{e.class}: #{e.message}")
+      end
+
+      def result(status, from: nil, to: nil, kept: [], warnings: [], error: nil)
+        Result.new(from: from, to: to, status: status, kept: kept, warnings: warnings, error: error)
       end
 
       # Parallel chi starts on one config dir take turns: the second one reads
@@ -101,7 +134,7 @@ module Samagotchi
         File.write(path, "#{pair}\n", mode: "a")
       end
 
-      def install_fresh(gem_manifest)
+      def install_fresh(to)
         installer = Installer.new(
           source: GEM_BUNDLE_DIR,
           name: BUNDLE_NAME,
@@ -109,53 +142,48 @@ module Samagotchi
           force: false,
           strict: true
         )
-        _nd, _manifest = installer.run
-        unless installer.warnings.empty?
-          installer.warnings.each { |w| Log.warn(:memory, "system_bundle_warning", echo: "[samagotchi-system] #{w}") }
-        end
-        true
+        installer.run
+        result(:installed, to: to, warnings: installer.warnings)
       end
 
-      def upgrade_existing(gem_manifest, _existing_data)
-        installer = Installer.new(
-          source: GEM_BUNDLE_DIR,
-          name: BUNDLE_NAME,
-          scope: SCOPE,
-          force: false,
-          strict: true,
-          upgrade: true
-        )
-        _nd, _manifest = installer.run
-        # Installer already handled fast_forward/keep/noop. Conflicts are kept with warning.
-        if installer.conflicts.any?
-          installer.conflicts.each do |file_key, _info|
-            Log.info(:memory, "system_local_edit_kept", echo: "[samagotchi-system] kept local edit in #{file_key} (bundle v#{gem_manifest.version} has update — run: chi bundle status #{BUNDLE_NAME} / chi bundle diff #{BUNDLE_NAME} #{file_key})", file: file_key.to_s)
-          end
-        end
-        installer.warnings.each { |w| Log.warn(:memory, "system_bundle_warning", echo: "[samagotchi-system] #{w}") } unless installer.warnings.empty?
-        true
+      # Installer handles fast_forward/keep/noop; a conflict keeps the local
+      # file, and its own "Conflict in" warning is left out (kept says it).
+      def upgrade_existing(from, to)
+        installer = upgrade_installer
+        installer.run
+        kept = installer.conflicts.keys
+        warnings = installer.warnings.reject { |w| kept.any? { |k| w.start_with?("Conflict in #{k}:") } }
+        result(:updated, from: from, to: to, kept: kept, warnings: warnings)
       end
 
-      def verify_files_present(gem_manifest, data)
-        # If any file from the bundle is missing on disk but provenance says it should exist,
-        # reinstall that file via Installer (which will classify as :install). This handles
-        # accidental user deletion without forcing a full reinstall.
+      # A file from the bundle missing on disk (the user deleted it) is put
+      # back via the Installer (which classifies it as :install), without a
+      # full reinstall.
+      def verify_files_present(gem_manifest, version, dry_run)
         target_dir = Installer.system_dir
         missing = gem_manifest.files.keys.any? { |k| !File.exist?(File.join(target_dir, k)) }
-        return false unless missing
+        return result(:up_to_date, from: version, to: version) unless missing
+        return result(:restored, from: version, to: version) if dry_run
 
-        installer = Installer.new(
-          source: GEM_BUNDLE_DIR,
-          name: BUNDLE_NAME,
-          scope: SCOPE,
-          force: false,
-          strict: true,
-          upgrade: true
-        )
-        _nd, _manifest = installer.run
-        true
+        upgrade_installer.run
+        result(:restored, from: version, to: version)
+      end
+
+      # The files an upgrade would keep: edited here and changed in the
+      # shipped bundle (a dry run's kept).
+      def conflicting(gem_manifest)
+        provenance = Provenance.new(name: BUNDLE_NAME)
+        gem_manifest.files.keys.map(&:to_s).sort.select do |key|
+          Merger.classify(base_path: provenance.base_path(key), current_path: File.join(Installer.system_dir, key),
+                          incoming_path: File.join(GEM_BUNDLE_DIR, key)) == :conflict
+        end
+      end
+
+      def upgrade_installer
+        Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true)
       end
-      private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present
+      private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present,
+                           :upgrade_installer, :result, :conflicting
     end
   end
 end

data/lib/samagotchi/model_profile.rb

@@ -14,6 +14,9 @@ module Samagotchi
     # No model anywhere (--model, default.model in config.yml, the env): a
     # first run before any config. An ArgumentError, as before.
     MissingModel = Class.new(ArgumentError)
+    # A host-qualified model whose host isn't configured (a MissingModel,
+    # so every surface that reports a missing model reports it the same way).
+    UnknownHost = Class.new(MissingModel)
 
     attr_reader :name, :turn_start, :turn_end,
                 :tool_call_open, :tool_call_close,
@@ -130,6 +133,26 @@ module Samagotchi
       value
     end
 
+    # Raises UnknownHost when +model_name+ (or the alias it names) is
+    # qualified with a host that isn't configured, instead of sending the
+    # whole ref to the default host as a model id. Where a model comes in
+    # (an Engine starting or switching, a spawned session) calls it.
+    # @param hosts [Hash, nil] the hosts a prefix may name (a HostRegistry's
+    #   entries); config.yml's by default
+    # @return [String] +model_name+
+    def self.check_host!(model_name, env: ENV, hosts: nil)
+      require_relative "config"
+      hosts ||= Samagotchi::ConfigFile.hosts_config(env: env)
+      ref = Samagotchi::ConfigFile.resolve_model_alias(model_name, env: env, hosts: hosts)
+      host = Samagotchi::ConfigFile.unknown_host_prefix(ref, hosts: hosts)
+      return model_name unless host
+
+      names = hosts.keys.map { |k| k.to_s.downcase }.sort
+      near = Samagotchi::Config.near_names(host, names).first(3)
+      hint = near.empty? ? "" : " (did you mean #{near.map { |n| "'#{n}'" }.join(' or ')}?)"
+      raise UnknownHost, "unknown host '#{host}' in model '#{ref}'#{hint}; the configured hosts are #{names.join(', ')}"
+    end
+
     # One line for the user: where to set the model.
     def self.missing_model_message
       path = begin
@@ -139,7 +162,7 @@ module Samagotchi
         "~/.config/samagotchi/config.yml"
       end
       "no model configured: set default.model in #{path} to the model id your server serves " \
-        "(or #{MODEL_ENV}, or pass --model ID); see docs/configuration.md"
+        "(or #{MODEL_ENV}, or pass --model ID); see docs/configuration.md; or run: chi bootstrap HOST[:PORT]"
     end
 
     def self.from_model_name(model_name)

data/lib/samagotchi/plugin/context.rb

@@ -18,8 +18,10 @@ module Samagotchi
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +model_name+ and +state_dir+ are what ctx.sessions forks with.
+    # +steer+ takes (text, source) and +stop_turn+ (reason, label), each
+    # true when it acted on a running turn.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
-                      :ask_model, :model_name, :state_dir, keyword_init: true)
+                      :ask_model, :model_name, :state_dir, :scratch, :steer, :stop_turn, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -178,6 +180,25 @@ module Samagotchi
       # Whether the running turn was cancelled (a long tool should stop).
       def cancelled? = !!@host.cancelled.call
 
+      # Put +text+ into the running turn, as a user's steering does: at the
+      # loop's next boundary (after the tool calls in flight) it joins the
+      # conversation as its own user message, shown in every UI as a nudge
+      # from this bundle. It never starts a turn. True means queued: if the
+      # model answers first, or the turn ends, it is dropped (logged).
+      # Callable from a hook, a command (an anytime one runs beside the
+      # turn) or your own thread.
+      # @return [Boolean] whether a turn was running and the text queued
+      def steer(text)
+        !!@host.steer&.call(text.to_s, @bundle)
+      end
+
+      # Stop the running turn, after a notice with +reason+, as a hook's
+      # event[:stop_turn] does (for commands and threads).
+      # @return [Boolean] whether a running turn was stopped now
+      def stop_turn(reason)
+        !!@host.stop_turn&.call(reason.to_s, @label)
+      end
+
       private
 
       def deep_freeze(value)

data/lib/samagotchi/plugin/sessions.rb

@@ -33,9 +33,11 @@ module Samagotchi
       #   the first user message, by default)
       # @param prompt [String, nil] the child's first turn
       # @return [String] the child's id
-      # @raise [Error] no session yet, or too many children running
+      # @raise [Error] no session yet, a scratch session (the child would
+      #   outlive it), or too many children running
       def fork(messages:, title: nil, prompt: nil)
         parent_id = @host.session_id.call or raise Error, "this session has no id yet"
+        raise Error, "a scratch session starts no other sessions: they would outlive it" if @host.scratch&.call
         state_dir = self.state_dir
         prompt = prompt.to_s.strip.empty? ? nil : prompt.to_s
         check_children(parent_id, state_dir) if prompt

data/lib/samagotchi/prompt.rb

@@ -39,8 +39,10 @@ module Samagotchi
     # what it was before images existed.
     #
     # @param vision [VisionContext, nil] the turn's images context
+    # @param prefill [String] text after the generation cue, the start of
+    #   the model's answer (Thinking.native: Qwen's empty thought)
     # @return [Array(String, Array<String>)]
-    def self.format_with_images(messages, profile: ModelProfile.default, vision: nil)
+    def self.format_with_images(messages, profile: ModelProfile.default, vision: nil, prefill: "")
       plan = ImagePlan.new(messages, vision, data: :base64)
       images = []
       suffixes = messages.each_with_index.map { |m, index| image_lines(plan.items(m, index), profile, images) }
@@ -49,7 +51,7 @@ module Samagotchi
              else
                format_with_turn_markers(messages, profile, suffixes)
              end
-      [text, images]
+      [text + prefill.to_s, images]
     end
 
     private

data/lib/samagotchi/reminder_store.rb

@@ -90,7 +90,7 @@ module Samagotchi
 
     # Get all due reminders whose interval has elapsed.
     # Returns an Array of {name:, description:, interval_minutes:} hashes.
-    # Called by Engine#maybe_inject_reminders (synchronously, at run_turn start).
+    # Called by Engine#collect_due_reminders (synchronously, at run_turn start).
     # Thread-safe. Returns a frozen copy so the caller can't mutate internal state.
     # @return [Array<Hash>] array of due reminder hashes (may be empty)
     def due_reminders
@@ -103,14 +103,6 @@ module Samagotchi
       end
     end
 
-    # Get the name of the next due reminder (if any) whose interval has elapsed.
-    # Kept for backward compatibility with IdleReminders thread.
-    # @return [String, nil] the reminder name, or nil if none are due
-    def next_due_name
-      due = due_reminders
-      due.first&.fetch(:name)
-    end
-
     # Mark a reminder as fired — resets its next_fire_at to now + interval.
     # Called by Engine after a due reminder has been delivered.
     # @param name [String] the reminder name