samagotchi 0.9.0 → 0.10.0

data/lib/samagotchi/desktop_command.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "cli/command"
+require_relative "cli/flags"
 require_relative "desktop"
 
 module Samagotchi
   # `chi desktop install|upgrade|uninstall|status`: the native helper that
   # sends selected text to live sessions as a context note (macOS for now).
   class DesktopCommand
+    include CLI::Command
+
     USAGE = <<~TEXT
       Usage: chi desktop <install|upgrade|uninstall|status>
         install [--force] [--login]
@@ -21,6 +25,15 @@ module Samagotchi
 
     SUBCOMMANDS = %w[install upgrade uninstall status].freeze
 
+    # --no-register (hidden) on each; --help is an unknown option after the
+    # subcommand.
+    FLAGS = CLI::Flags.new(args: false) { |f| f.switch "--no-register" }
+    INSTALL_FLAGS = CLI::Flags.new(args: false) do |f|
+      f.switch "--no-register"
+      f.switch "--force"
+      f.switch "--login"
+    end
+
     # @param platform [#call] register: → a Desktop::MacOS-like object
     def initialize(argv, stdout: $stdout, stderr: $stderr, platform: nil, supported: Desktop.supported?)
       @argv = argv.dup
@@ -33,7 +46,7 @@ module Samagotchi
     # @return [Integer] 0 ok, 1 failed, 2 usage
     def run
       sub = @argv.shift
-      if sub.nil? || %w[-h --help help].include?(sub)
+      if sub.nil? || HELP_WORDS.include?(sub)
         @stdout.puts(USAGE)
         return 0
       end
@@ -44,7 +57,9 @@ module Samagotchi
         return 1
       end
 
-      options = parse(sub) or return 2
+      options = parse(sub)
+      return options if options.is_a?(Integer)
+
       # --no-register (hidden): no pbs/lsregister/open/pkill, for installs
       # into temp dirs (HOME=…) that must not touch the real Services.
       helper = @platform.call(register: !options[:no_register])
@@ -56,17 +71,14 @@ module Samagotchi
 
     private
 
-    # @return [Hash, nil] nil after a usage error
+    def command_name = "chi desktop"
+
+    # @return [Hash, Integer] the options, or the usage error's exit status
     def parse(sub)
-      flags = { "--no-register" => :no_register }
-      flags.merge!("--force" => :force, "--login" => :login) if sub == "install"
-      @argv.each_with_object({}) do |arg, options|
-        unless flags.key?(arg)
-          usage_error("unknown option #{arg}")
-          return nil
-        end
-        options[flags[arg]] = true
-      end
+      parsed = (sub == "install" ? INSTALL_FLAGS : FLAGS).parse(@argv)
+      return usage_error(parsed.error.message) if parsed.error
+
+      parsed.options
     end
 
     # The warnings come after a done install: a refused or failed one
@@ -136,11 +148,5 @@ module Samagotchi
     def print_warnings(helper)
       helper.warnings.each { |warning| @stderr.puts("warning: #{warning}") }
     end
-
-    def usage_error(message)
-      @stderr.puts("chi desktop: #{message}")
-      @stderr.puts(USAGE)
-      2
-    end
   end
 end

data/lib/samagotchi/edit_preview.rb

@@ -33,8 +33,8 @@ module Samagotchi
       return before if before.is_a?(Hash)
 
       if call[:name].to_s == "edit"
-        result = Tools::Edit.apply(call[:content], path: path, start_line: call[:start_line],
-                                                   end_line: call[:end_line], read: ->(_) { before })
+        result = Tools::Edit.apply(path: path, old_text: call[:old_text], new_text: call[:new_text],
+                                   start_line: call[:start_line], end_line: call[:end_line], read: ->(_) { before })
         return { error: result.delete_prefix("Error: ") } if result.is_a?(String)
 
         after = result.first

data/lib/samagotchi/engine.rb

@@ -11,7 +11,6 @@ require_relative "context_note"
 require_relative "steer"
 require_relative "turn_note"
 require_relative "model_profile"
-require_relative "thought_stream_splitter"
 require_relative "cancellation_controller"
 require_relative "context_window"
 require_relative "kernel_loop"
@@ -107,7 +106,7 @@ module Samagotchi
       # #profile_resolution decides on first need (see there), so building an
       # Engine makes no network call.
       @given_profile = profile ? ModelProfile.normalize(profile) : nil
-      @model_lookup_names = [@default_model_name]
+      @typed_model_name = @default_model_name
       @profile_resolution = nil
       # Ensure the built-in system bundle is installed (lazy, warn-only).
       # This is the single seam for both TUI and non-TUI (web/worker) paths.
@@ -769,7 +768,7 @@ module Samagotchi
       resolved = ModelProfile.check_host!(ModelProfile.required_model_name(aliased), hosts: @host_registry.entries)
       @effective_model_name = resolved
       bare = bare_model_name(resolved)
-      @model_lookup_names = [model_name, aliased, resolved]
+      @typed_model_name = model_name
       # A profile given to .new was for the starting model.
       @given_profile = nil
       @profile_resolution = nil
@@ -844,7 +843,7 @@ module Samagotchi
       # head system prompt invalidates the cache for the entire conversation
       # (prompt re-evaluated every interval). A tail append keeps the prefix
       # intact — only the new reminder suffix is evaluated. Mirrors the
-      # context-status injection at lib/samagotchi/kernel_loop.rb:447.
+      # context guidance line KernelLoop#run appends (ContextStatus#take_guidance).
       messages << { role: "system", content: reminder_text }
       # Atomically mark all due as fired under one lock and clear the
       # IdleReminders latch so the next interval can be detected.
@@ -1107,29 +1106,15 @@ module Samagotchi
       @guardrail_wiring.state_dir = state_dir
     end
 
-    # The gate's core checks, in order (GuardrailWiring#checks).
-    def guardrail_checks
-      @guardrail_wiring.checks
-    end
-
     # The YAML rules, read again when a file changed (GuardrailWiring#rules).
     # @return [Guardrails::Rules]
     def guardrail_rules
       @guardrail_wiring.rules
     end
 
-    # Installed bundles' guardrails/*.yml (GuardrailWiring#bundle_rules).
-    def bundle_guardrail_rules
-      @guardrail_wiring.bundle_rules
-    end
-
     # @return [Guardrails::LoadFailures]
     attr_reader :guardrail_failures
 
-    def guardrail_protected_paths
-      @guardrail_wiring.protected_paths
-    end
-
     # @return [Guardrails::Approvals]
     def guardrail_approvals
       @guardrail_wiring.approvals
@@ -1165,12 +1150,6 @@ module Samagotchi
       @plugin_failures.message if @guardrail_failures_announced
     end
 
-    # The context the gate sees for a tool call now.
-    # @return [Guardrails::Context]
-    def guardrail_context
-      @guardrail_wiring.context
-    end
-
     # Ask the user to approve a call the gate voted `ask` on
     # (GuardrailWiring#request_approval).
     # @param verdict [Guardrails::Verdict]
@@ -2065,7 +2044,7 @@ module Samagotchi
           (task = current_init_task) ? task.cancelled? : @activity_mutex && active_cancel_controller&.cancelled?
         },
         card: ->(**card) { show_card(**card) },
-        steer: ->(text, source) { steer(text, source: source) },
+        steer: ->(text, label) { steer(text, source: hook_source(label)) },
         stop_turn: ->(reason, label) { hook_stop_turn(reason, label) },
         stop_generation: ->(reason, label) { hook_stop_generation(reason, label) },
         ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
@@ -2108,31 +2087,13 @@ module Samagotchi
     end
     private :ask_side_model
 
-    # config.yml `bundles:`: each bundle's settings by name, for its hooks.
-    # @return [Hash{String => Hash}] {} when absent; a section that isn't a
-    #   mapping warns once and counts as absent
+    # config.yml `bundles:` (ConfigFile.bundle_settings), read once: the
+    # bundle hooks and the plugins both want it.
     def bundle_settings
-      # Read once: the bundle hooks and the plugins both want it.
-      @bundle_settings ||= read_bundle_settings
+      @bundle_settings ||= Samagotchi::ConfigFile.bundle_settings
     end
     private :bundle_settings
 
-    def read_bundle_settings
-      data = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
-      section = data.is_a?(Hash) ? data["bundles"] : nil
-      return {} if section.nil?
-      unless section.is_a?(Hash)
-        Log.warn(:hooks, "bundles_section_invalid", echo: "[samagotchi:hooks] config.yml bundles: must be a mapping of bundle name to settings; ignored")
-        return {}
-      end
-
-      section.each_with_object({}) do |(name, value), acc|
-        acc[name.to_s] = value.is_a?(Hash) ? value : {}
-      end
-    rescue StandardError
-      {}
-    end
-    private :read_bundle_settings
 
     # The session's current model as a recap target: its host's OpenAI API
     # (native llama.cpp hosts serve /v1/chat/completions too), key variable
@@ -2168,44 +2129,29 @@ module Samagotchi
     # only notifying the observer.
     # Wrap a raw kernel stream event and fan it out to the turn sink + observers.
     #
-    # Phase 2 (web-stream-rendering): each :generation_chunk is enriched with two
-    # ADDITIVE fields derived from the raw `content` (which is left untouched —
-    # the TUI thinking spinner, analytics, and Bridge replay all rely on raw):
+    # 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
-    # The splitter is profile-aware and resets on each :generation_started so a
-    # turn's multiple generations each start clean.
-    #
-    # Enrichment is profile-scoped:
-    #   * Splitting profiles (explicit think close, e.g. Qwen) ALWAYS emit
-    #     `text`/`thinking` on every :generation_chunk — even when empty — so the
-    #     web client can rely on them and never fall back to raw `content`.
-    #   * Non-splitting profiles (nil think close, e.g. Gemma) leave the event
-    #     unchanged; the web client then falls back to raw `content`, preserving
-    #     today's behavior (no regression).
+    # 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.
     def build_stream_event_handler(on_event, cancel_controller: nil)
-      splitter = ThoughtStreamSplitter.for_profile(profile)
-      enrich = profile.thought_close ? :always : :never
       watch = stream_watch(cancel_controller)
       proc do |event|
         progress = nil
         case event[:type]
         when :generation_started
-          splitter = ThoughtStreamSplitter.for_profile(profile)
           watch&.started(event[:iteration])
         when :generation_chunk
-          # The chat loop already splits its stream (reasoning arrives apart
-          # from the answer); only raw native chunks are split here.
-          if event.key?(:text)
-            progress = { thinking: event[:thinking], text: event[:text] }
-          else
-            delta = splitter.feed(event[:content])
-            progress = { thinking: delta[:thinking], text: delta[:text] }
-            event = event.merge(text: delta[:text], thinking: delta[:thinking]) if enrich == :always
-          end
+          # A chunk without the lanes (no loop of ours sends one) counts as text.
+          text = event.key?(:text) ? event[:text] : event[:content]
+          progress = { thinking: event[:thinking].to_s, text: text.to_s }
         end
         # The chat loop asked again without the thinking fields: a notice,
         # not an event of its own.
@@ -2300,11 +2246,10 @@ module Samagotchi
       ModelProfile.resolve(names: model_lookup_names(target), entry: target.entry, client: target.client, bare_model: target.bare_model)
     end
 
-    # The names a models: entry may be under: as typed (maybe an alias), the
-    # part after a host prefix, alias-resolved, bare.
+    # The names a models: entry may be under (HostRegistry#lookup_names):
+    # the model as typed at start or at the last /model, and what it became.
     def model_lookup_names(target)
-      typed = @model_lookup_names.first
-      (@model_lookup_names + [@host_registry.parse_qualified_model(typed).last, target.bare_model]).compact
+      @host_registry.lookup_names(@typed_model_name, resolved: @effective_model_name, target: target)
     end
 
     # Everything that holds a profile follows the resolution: the kernel's

data/lib/samagotchi/events.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The sets of event types more than one place reads (the Worker, the
+  # Bridge's observers, the TUI, the web), kept here once. The web's own
+  # copies (app.js's stream handlers, turn_events.js's snapshotEvents) are
+  # checked against these by spec/events_drift_spec.rb.
+  module Events
+    # A turn is over: it completed, was canceled, or failed.
+    TURN_END = %i[turn_completed turn_canceled turn_failed].freeze
+    # Turn ends that leave the turn in the conversation: a failed turn's
+    # prompt goes back to the composer instead.
+    TURN_KEPT = %i[turn_completed turn_canceled].freeze
+    # The kinds of a running turn's parts (Bridge::TurnAccumulator), which a
+    # joining UI replays as live events.
+    PART_KINDS = %w[thinking text tool input steer reminder notice].freeze
+    # Types no Engine emits that a UI handles: the Bridge's stream frames
+    # and the web's one synthetic replay event (a prompt merged into the
+    # turn, turn_events.js snapshotEvents).
+    STREAM_FRAMES = %i[snapshot reset stream_closed].freeze
+    SYNTHETIC = %i[merged_input].freeze
+  end
+end

data/lib/samagotchi/guardrail_wiring.rb

@@ -156,13 +156,11 @@ module Samagotchi
     def protected_paths
       @protected ||= begin
         require_relative "memory_bundle/provenance"
-        config = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
-        hooks_dir = config.is_a?(Hash) && config["hooks"].is_a?(Hash) ? config["hooks"]["hooks_dir"] : nil
         Guardrails::ProtectedPaths.new(
           store_dir: File.dirname(@approvals.path),
           bundles_dir: MemoryBundle::Provenance.bundles_dir,
           config_path: Samagotchi::ConfigFile.global_path,
-          hooks_dir: Hooks::Loader.expand_path(hooks_dir || Hooks::Loader.default_hooks_dir)
+          hooks_dir: Hooks::Loader.hooks_dir
         )
       end
     end
@@ -209,8 +207,7 @@ module Samagotchi
     end
 
     def load_rules
-      section = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
-      section = section["guardrails"] if section.is_a?(Hash)
+      section = Samagotchi::ConfigFile.section("guardrails")
       rules = []
       disable = []
       begin

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -30,9 +30,9 @@ module Samagotchi
     # Any hook whose sha256 differs is not loaded (reinstall the bundle
     # after editing a hook by hand).
     #
-    # The +on_error+ policy is applied per hook at fire time:
-    #   - "fail_closed" (on :before_tool_call): a raising guardrail sets
-    #     event[:blocked] = true — the tool call is prevented (fail-closed).
+    # The +on_error+ policy is applied per hook at fire time (Hooks.wrap):
+    #   - "fail_closed" (on :before_tool_call): a raising guardrail denies
+    #     the tool call (fail-closed).
     #   - "log": warn to stderr and continue.
     #   - "skip" (default): silently continue.
     module BundleLoader
@@ -80,16 +80,14 @@ module Samagotchi
 
             begin
               plugin = instantiate(bundle_name, basename, file, settings: settings)
-              log_failure = Hooks.failure_log_gate(event_sym)
-
-              registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: priority) do |event|
-                begin
-                  plugin.call(event)
-                rescue Exception => e
-                  # A veto always applies; only the log line is throttled.
-                  handle_error(bundle_name, basename, on_error, fail_closed, event, e) if fail_closed || log_failure.call
-                end
-              end
+              policy = if fail_closed then :deny
+                       elsif on_error == "log" then :log
+                       else :skip
+                       end
+              label = "#{fail_closed ? "guardrail " : ""}#{basename} (bundle #{bundle_name})"
+              handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
+                                   fields: { bundle: bundle_name }) { |event| plugin.call(event) }
+              registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: priority, &handler)
               loaded += 1
             rescue Exception => e
               Log.error(:hooks, "bundle_hook_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' failed to load: #{e.class}: #{e.message}", bundle: bundle_name, hook: basename.to_s, error: e.class.name)
@@ -119,10 +117,9 @@ module Samagotchi
           ns = namespace_for(bundle_name)
           content = File.read(file)
           ns.module_eval(content, file, 1)
-          class_name = File.basename(basename, ".rb").split("_").map(&:capitalize).join
-          klass = ns.const_get(class_name, false)
+          klass = Hooks.class_for(basename, ns)
           instance = Hooks.build_plugin(klass, settings)
-          raise ArgumentError, "plugin #{class_name} does not respond to #call" unless instance.respond_to?(:call)
+          raise ArgumentError, "plugin #{klass.name.split("::").last} does not respond to #call" unless instance.respond_to?(:call)
           instance
         end
 
@@ -141,20 +138,6 @@ module Samagotchi
             Samagotchi::Bundles.const_set(ns_name.to_sym, Module.new)
           end
         end
-
-        # Apply the per-hook on_error policy when a plugin raises.
-        def handle_error(bundle_name, basename, on_error, fail_closed, event, error)
-          if fail_closed && event.is_a?(Hash)
-            event[:blocked] = true
-            reason = "guardrail #{basename} (bundle #{bundle_name}) failed: #{error.class}: #{error.message}"
-            event[:guardrail]&.deny!(reason, rule: "guardrail-load", source: "core", decided_by: "core")
-            existing = event[:block_reason].to_s
-            event[:block_reason] = existing.empty? ? reason : "#{existing}; #{reason}"
-          elsif on_error == "log"
-            Log.warn(:hooks, "bundle_hook_failed", echo: "[samagotchi:hooks] #{basename} (bundle #{bundle_name}) failed: #{error.class}: #{error.message}", bundle: bundle_name, hook: basename.to_s, error: error.class.name)
-          end
-          # "skip" (and fail_closed on non-veto events) is silent.
-        end
       end
     end
   end

data/lib/samagotchi/hooks/loader.rb

@@ -41,6 +41,15 @@ module Samagotchi
           File.join(ConfigFile.config_dir(env: env), "hooks", "")
         end
 
+        # The hooks folder: config.yml's hooks.hooks_dir, or the default,
+        # "~" expanded.
+        # @param data [Hash, nil] the parsed config.yml (read when not given)
+        def hooks_dir(env = ENV, data: ConfigFile.read_yaml(path: ConfigFile.global_path(env: env)))
+          section = data.is_a?(Hash) ? data["hooks"] : nil
+          configured = section.is_a?(Hash) ? section["hooks_dir"] : nil
+          expand_path(configured || default_hooks_dir(env), env)
+        end
+
         # Load hooks from a config hash and return a Registry with registered plugins.
         #
         # @param config_hash [Hash, nil] the hooks section from config.yml
@@ -52,7 +61,7 @@ module Samagotchi
           return Hooks::Registry.new unless config_hash&.key?("hooks")
 
           hooks_config = config_hash["hooks"]
-          hooks_dir = expand_path(hooks_config["hooks_dir"] || default_hooks_dir(env), env)
+          hooks_dir = hooks_dir(env, data: config_hash)
 
           registry = Hooks::Registry.new
           definitions = parse_definitions(hooks_config)
@@ -60,20 +69,10 @@ module Samagotchi
           definitions.each do |defn|
             begin
               plugin = load_plugin(hooks_dir, defn[:path], settings: defn[:settings])
-              log_failure = Hooks.failure_log_gate(defn[:event_type])
               # Persistent: config hooks must fire on every turn, not be wiped
               # by Engine#run_turn's per-turn clear_hooks after turn 1.
-              registry.register_persistent(defn[:event_type].to_sym, label: "#{defn[:path]} (config)") do |event|
-                begin
-                  plugin.call(event)
-                rescue StandardError => e
-                  if defn[:required] && defn[:event_type] == "before_tool_call"
-                    deny_for_raise(event, defn[:path], e)
-                  else
-                    handle_error(defn[:on_error] || "skip", defn[:path], e) if log_failure.call
-                  end
-                end
-              end
+              registry.register_persistent(defn[:event_type].to_sym, label: "#{defn[:path]} (config)",
+                                           &wrapped(plugin, defn))
             rescue ScriptError, StandardError => e
               # ScriptError: a SyntaxError (or LoadError) from `require`.
               Log.error(:hooks, "hook_load_failed", echo: "[samagotchi:hooks] hook #{defn[:path]} failed to load: #{e.class}: #{e.message}", hook: defn[:path].to_s, error: e.class.name)
@@ -130,33 +129,24 @@ module Samagotchi
 
         @plugin_cache[[full_path, settings]] ||= begin
           require full_path
-          class_name = File.basename(path, ".rb").split("_").map(&:capitalize).join
-          klass = Object.const_get(class_name)
+          klass = Hooks.class_for(path)
           instance = Hooks.build_plugin(klass, settings)
           # Validate that the instance responds to #call
-          raise ArgumentError, "Plugin #{class_name} does not respond to #call" unless instance.respond_to?(:call)
+          raise ArgumentError, "Plugin #{klass.name} does not respond to #call" unless instance.respond_to?(:call)
           instance
         end
       end
 
-      # A required before_tool_call hook that raises denies the call.
-      def self.deny_for_raise(event, hook_path, error)
-        return unless event.is_a?(Hash)
-
-        reason = "required hook #{hook_path} raised #{error.class}: #{error.message}"
-        event[:guardrail]&.deny!(reason, rule: "guardrail-load", source: "core", decided_by: "core")
-        event[:blocked] = true
-        event[:block_reason] ||= reason
-      end
-
-      # Handle a hook error based on the on_error config.
-      def self.handle_error(on_error, hook_path, error = nil)
-        case on_error
-        when "log"
-          Log.warn(:hooks, "hook_failed", echo: "[samagotchi:hook] #{error ? "#{error.class}: #{error.message}" : "hook failed"} (#{hook_path})", hook: hook_path.to_s, error: error&.class&.name)
-        when "skip"
-          # Silent — just skip
+      # The plugin's #call under the entry's error policy: a required
+      # before_tool_call hook that raises denies the call; otherwise
+      # on_error: log warns and skip is silent.
+      def self.wrapped(plugin, defn)
+        if defn[:required] && defn[:event_type] == "before_tool_call"
+          policy, label = :deny, "required hook #{defn[:path]}"
+        else
+          policy, label = (defn[:on_error] == "log" ? :log : :skip), "#{defn[:path]} (config)"
         end
+        Hooks.wrap(label: label, event: defn[:event_type].to_sym, policy: policy) { |event| plugin.call(event) }
       end
     end
   end

data/lib/samagotchi/hooks/registry.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "monitor"
+require_relative "../log"
 
 module Samagotchi
   module Hooks
@@ -36,6 +37,46 @@ module Samagotchi
       end
     end
 
+    # A hook file's class: the PascalCase of its basename (my_hook.rb →
+    # MyHook), looked up in +namespace+ (a bundle's module; Object for a
+    # config hook).
+    # @return [Class]
+    def self.class_for(file, namespace = Object)
+      namespace.const_get(File.basename(file.to_s, ".rb").split("_").map(&:capitalize).join, false)
+    end
+
+    # A hook's block wrapped in its error policy: what a loader registers.
+    # When the block raises,
+    #   :deny  denies the call (event[:guardrail], the Gate's Verdict),
+    #          whatever was raised: a fail-closed before_tool_call guardrail.
+    #          The Gate folds the verdict into event[:blocked] and
+    #          event[:block_reason] for the hooks after it.
+    #   :log   warns (a stream hook at most once a minute, failure_log_gate)
+    #   :skip  is silent
+    # :log and :skip rescue StandardError and ScriptError.
+    # @param label [String] the hook, for the deny reason and the warning
+    # @param event [Symbol] the hook's event
+    # @param log [Array(Symbol, String)] the warning's tag and record name
+    # @param echo [Boolean] the warning also goes to stderr
+    # @param fields [Hash] more fields for the warning's record
+    def self.wrap(label:, event:, policy:, log: [:hooks, "hook_failed"], echo: true, fields: {}, &block)
+      log_failure = failure_log_gate(event)
+      lambda do |payload|
+        block.call(payload)
+      rescue Exception => e # rubocop:disable Lint/RescueException -- :deny fails closed on anything
+        raise unless policy == :deny || e.is_a?(StandardError) || e.is_a?(ScriptError)
+
+        failed = "#{e.class}: #{e.message}"
+        if policy == :deny
+          payload[:guardrail]&.deny!("#{label} raised #{failed}", rule: "guardrail-load", source: "core", decided_by: "core") if payload.is_a?(Hash)
+        elsif policy == :log && log_failure.call
+          text = "#{label} failed: #{failed}"
+          Log.warn(log[0], log[1], echo: echo ? "[samagotchi:hooks] #{text}" : nil, hook: label, event: event.to_s,
+                                   error: e.class.name, msg: text, **fields)
+        end
+      end
+    end
+
     # What a hook can do beyond reading its event: the Engine's
     # callables, each given the hook's label. +notify+ takes
     # (text:, level:, hook:) and shows one line to the user; +ask_user+

data/lib/samagotchi/hooks.rb

@@ -26,8 +26,5 @@ module Samagotchi
   #                         event also has context: and targets: (docs/guardrails.md)
   #   :after_tool_call    — after tool execution, before result injection
   module Hooks
-    REGISTRY_CLASS = Registry
-    LOADER_CLASS = Loader
-    BUNDLE_LOADER_CLASS = BundleLoader
   end
 end

data/lib/samagotchi/host_registry.rb

@@ -77,6 +77,7 @@ module Samagotchi
     # @param clock [#call, nil] monotonic seconds (specs)
     def initialize(hosts_config: nil, env: ENV, client_override: nil, clock: nil)
       @client_override = client_override
+      @env = env
       @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
       @adapters = {}
       @host_lists = {}
@@ -133,6 +134,20 @@ module Samagotchi
       ConfigFile.parse_host_qualified_model(raw, hosts: @entries)
     end
 
+    # The names a models: entry may be under, in the order they are looked
+    # up: +typed+ as given (maybe an alias), its alias's target, +resolved+
+    # (what the model became, e.g. the default for a blank one), the part
+    # after a host prefix, and the bare model the host is asked for.
+    # Thinking, SamplingSettings, VisionSupport and ModelProfile all take these.
+    # @param target [ModelTarget, nil] the resolved model's target (resolved when not given)
+    # @return [Array<String>]
+    def lookup_names(typed, resolved: nil, target: nil)
+      aliased = ConfigFile.resolve_model_alias(typed, env: @env)
+      target ||= resolve(resolved || aliased)
+      [typed, aliased, resolved, parse_qualified_model(typed).last, target.bare_model]
+        .map { |name| name.to_s.strip }.reject(&:empty?).uniq
+    end
+
     # Resolve model string (already alias-resolved, may be qualified) to a HostEntry.
     # If qualified explicitly, return that host. If unqualified, try cached model index,
     # else fallback to default host.

data/lib/samagotchi/idle_reminders.rb

@@ -36,13 +36,6 @@ module Samagotchi
       @due_reminder_name = nil
     end
 
-    # Get the currently pending due reminder name (for Engine to read).
-    # Kept for backward compatibility.
-    # Called by Engine#collect_due_reminders. Thread-safe.
-    def due_reminder_name
-      @mutex.synchronize { @due_reminder_name }
-    end
-
     # Get all due reminders (from ReminderStore). Called by Engine#collect_due_reminders.
     # Thread-safe. Returns all due reminders, not just one.
     # @return [Array<Hash>] [{name:, description:, interval_minutes:}, ...]

data/lib/samagotchi/image_store.rb

@@ -197,6 +197,8 @@ module Samagotchi
     REF_RE = %r{\Aimages/[0-9a-f]{16}\.(png|jpe?g|gif|webp)\z}
     MIME = { png: "image/png", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp" }.freeze
     EXT = { png: "png", jpeg: "jpg", gif: "gif", webp: "webp" }.freeze
+    # The most images one turn may carry (a client's refs, check_refs).
+    MAX_TURN_REFS = 20
     # Nothing larger is even read.
     MAX_SOURCE_BYTES = 50 * 1024 * 1024
 
@@ -251,6 +253,26 @@ module Samagotchi
       File.file?(path) && !File.symlink?(path)
     end
 
+    # A turn's images from a client (the web, a Bridge request) as
+    # [{file:, name:}], or a String saying what's wrong. Only refs to files
+    # already in the session's images/ pass (an upload): never a path, so no
+    # client can make the worker read a file.
+    def self.check_refs(session_dir, raw)
+      return [] if raw.nil?
+      return "images must be a list" unless raw.is_a?(Array)
+      return "at most #{MAX_TURN_REFS} images" if raw.size > MAX_TURN_REFS
+
+      raw.map do |image|
+        return "each image must be {file:, name:}" unless image.is_a?(Hash)
+
+        ref = symbolize(image)
+        return "images are refs to uploaded files, not paths" if ref.key?(:path)
+        return "unknown image #{ref[:file].to_s[0, 80]}" unless valid_ref?(session_dir, ref)
+
+        { file: ref[:file].to_s, name: File.basename(ref[:name].to_s)[0, 120] }
+      end
+    end
+
     # Messages seeded into another session (a plugin's ctx.sessions.fork):
     # each image ref's file is copied from +from+ into +to+ (both session
     # dirs; no +from+ copies none). A ref whose file isn't there is dropped, and its message says