samagotchi 0.9.0 → 0.10.1

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

data/lib/samagotchi/kernel_loop.rb

@@ -141,8 +141,8 @@ module Samagotchi
     # Run the conversation loop and return the final model response plus
     # resumable conversation state when execution stops at max_iterations.
     #
-    # @param messages       [Array<Hash>, Result] conversation so far ({role:, content:})
-    #                                           or a previous Result to resume
+    # @param messages       [Array<Hash>]        conversation so far ({role:, content:});
+    #   a stopped run resumes from its Result#conversation
     # @param max_iterations [Integer]            safety cap on tool-call rounds
     # @param on_stream_event [Proc, nil]         optional callback for generation events
     # @param cancel_controller [CancellationController, nil] optional cancellation source
@@ -170,7 +170,6 @@ module Samagotchi
       empty_retries = 0
       empty_retry_limit = EmptyAnswerRetry.limit
       @retry_generation = false
-      stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
       # Qwen with thinking off: an empty thought after the cue, so the model
       # answers at once. Kept in the turn's model messages, so each tool-loop
       # prompt starts with what the server already has cached.
@@ -192,6 +191,9 @@ module Samagotchi
           conversation << line
           prompt, images = Prompt.format_with_images(conversation, profile: @profile, vision: @vision, prefill: prefill)
         end
+        # Each generation splits its own stream: one that ended inside a
+        # thought or a tool call doesn't leave the next one "inside" it.
+        stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
         emit_stream_event(
           on_stream_event,
           type: :generation_started,
@@ -235,6 +237,7 @@ module Samagotchi
                   type: :generation_chunk,
                   iteration: iteration_index + 1,
                   content: chunk[:content],
+                  text: split[:text],
                   thinking: split[:thinking],
                   payload: chunk[:payload]
                 )
@@ -263,9 +266,8 @@ module Samagotchi
           ""
         end
         if cut
-          # The cut stream may have stopped mid-block, and its visible text
-          # goes with it: a fresh splitter, the buffer as it was before.
-          stream_splitter = ThoughtStreamSplitter.for_profile(@profile)
+          # The cut stream's visible text goes with it: the buffer as it was
+          # before (the next generation gets a fresh splitter).
           partial_assistant_buffer.slice!(buffer_mark..)
           emit_stream_event(on_stream_event, type: :generation_completed, iteration: iteration_index + 1,
                                              content_length: 0, thinking_chars: streamed_thinking,
@@ -660,8 +662,8 @@ module Samagotchi
     private
 
     # The generation's thinking: what the stream split into the thinking
-    # lane (Qwen), else what the profile's thought blocks hold (Gemma's
-    # stream isn't split).
+    # lane, else what the profile's thought blocks hold (an empty thought, a
+    # bare Gemma <|think|> cue, a response that wasn't streamed).
     def thinking_chars(response, streamed)
       return streamed if streamed.positive?
 
@@ -687,14 +689,8 @@ module Samagotchi
       end
     end
 
-    def prepare_conversation(messages)
-      if messages.is_a?(Result)
-        duplicate_conversation(messages.conversation)
-      else
-        # Standard multi-turn compliance: never pass prior raw thought blocks.
-        sanitize_history(messages)
-      end
-    end
+    # Standard multi-turn compliance: never pass prior raw thought blocks.
+    def prepare_conversation(messages) = sanitize_history(messages)
 
     def duplicate_conversation(messages)
       messages.map(&:dup)

data/lib/samagotchi/live_versions.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "socket"
 require_relative "session"
 require_relative "version"
 require_relative "worker_sidecar"
@@ -12,7 +11,6 @@ module Samagotchi
   # older one names none) and a `chi web` on its port (/api/info). Read-only:
   # a dead worker's sidecar is left for the next client to clean up.
   module LiveVersions
-    PROBE_TIMEOUT = 0.2
     WEB_TIMEOUT = 0.5
 
     # version is nil for a sidecar written before sidecars carried one.
@@ -24,8 +22,8 @@ module Samagotchi
     def workers(state_dir: Session.default_state_dir)
       Dir[File.join(state_dir, "*", WorkerSidecar::FILE)].sort.filter_map do |path|
         session_dir = File.dirname(path)
-        sidecar = WorkerSidecar.read(session_dir)
-        next unless sidecar && listening?(sidecar.port)
+        sidecar = WorkerSidecar.live(session_dir, unlink: false)
+        next unless sidecar
 
         Worker.new(session_id: File.basename(session_dir), version: sidecar.version)
       end
@@ -48,14 +46,5 @@ module Samagotchi
       info = Web::InfoProbe.call(host, port, timeout: timeout)
       info.is_a?(Hash) ? info : nil
     end
-
-    def listening?(port, host: "127.0.0.1")
-      return false unless port.positive?
-
-      Socket.tcp(host, port, connect_timeout: PROBE_TIMEOUT).close
-      true
-    rescue StandardError
-      false
-    end
   end
 end

data/lib/samagotchi/llm/native_tool_normalizer.rb

@@ -1,217 +1,19 @@
 # frozen_string_literal: true
 
 require "json"
-require_relative "../tools/execute"
-require_relative "../tools/read"
-require_relative "../tools/write"
-require_relative "../tools/memory"
-require_relative "../tools/edit"
-require_relative "../tools/task_create"
-require_relative "../tools/task_get"
-require_relative "../tools/task_list"
-require_relative "../tools/task_stop"
-require_relative "../tools/task_wait"
-require_relative "../tools/web_fetch"
-require_relative "../tools/register_reminder"
-require_relative "../tools/cancel_reminder"
-require_relative "../tools/list_reminders"
-require_relative "../tools/list_sessions"
-require_relative "../tools/send_note"
-require_relative "../tools/delegate"
-require_relative "../tools/delegate_result"
-require_relative "../tools/ask_user_question"
+require_relative "../tools/builtin_calls"
 
 module Samagotchi
   module LLM
     # Bridges a native tool call (an LLM::ToolCall from the chat adapter; any
-    # object with #name and #arguments) into samagotchi's internal tool-call shape that
-    # `KernelLoop#dispatch` consumes:
+    # object with #name and #arguments) into samagotchi's internal tool-call
+    # shape: its arguments read as a Hash, then Tools::BuiltinCalls builds
+    # the call, as it does for the Gemma and Qwen parsers.
     #
-    #   { name:, content:, path:, scope:, start_line:, end_line:, cwd:, env:, description: }
-    #
-    # The adapter hands you a *structured* `arguments` Hash (`.arguments` is a parsed
-    # Hash), while the internal `content` is a per-tool serialized text blob
-    # (e.g. `Edit` wants "<old>…</old><new>…</new>"; `Read` wants a `path`;
-    # `Execute` wants the command). Rather than re-architect every tool to accept
-    # structured args (huge blast radius), we rebuild the exact blob per tool so
-    # `dispatch` and every tool stay unchanged.
-    #
-    # Unknown tool names pass through untouched so `dispatch` renders its standard
-    # "unknown tool … available: …" error — the loop feeds that back like any tool
-    # result.
-    #
-    # This is the Phase-3 crux from Spike #4: the native→internal mapping is
-    # independent of how tools were driven in the request body.
+    # Unknown tool names pass through with their arguments on args:, so
+    # `dispatch` renders its standard "unknown tool … available: …" error —
+    # the loop feeds that back like any tool result.
     class NativeToolNormalizer
-      # Map each known tool NAME to a proc(args => internal-call-hash).
-      # Each proc receives the tool call's arguments (`.arguments` is a Hash of string→value)
-      # and returns the internal dispatch shape with every expected key present
-      # (missing values are nil).
-      #
-      # Args come back as strings from the wire (e.g. "start_line" => "1"); tools
-      # that read them do `.to_s.strip`, so we leave them as-is here and let the
-      # dispatch site coerce.
-      MAP = {
-        Tools::Execute::NAME => lambda { |args|
-          {
-            name: Tools::Execute::NAME,
-            content: args["command"].to_s,
-            path: nil, scope: nil,
-            start_line: nil, end_line: nil,
-            cwd: args["cwd"], env: args["env"]
-          }
-        },
-        Tools::Read::NAME => lambda { |args|
-          {
-            name: Tools::Read::NAME,
-            content: args["path"].to_s,
-            path: nil, scope: nil,
-            start_line: args["start_line"], end_line: args["end_line"],
-            cwd: nil, env: nil, description: nil,
-            args: args.is_a?(Hash) ? args : {}
-          }
-        },
-        Tools::Write::NAME => lambda { |args|
-          {
-            name: Tools::Write::NAME,
-            content: args["content"] || args["text"],
-            path: args["path"], scope: nil,
-            start_line: nil, end_line: nil,
-            cwd: nil, env: nil, description: nil
-          }
-        },
-        Tools::MemoryRead::NAME => lambda { |args|
-          {
-            name: Tools::MemoryRead::NAME,
-            content: args["name"].to_s,
-            path: nil, scope: args["scope"],
-            start_line: nil, end_line: nil,
-            cwd: nil, env: nil, description: nil
-          }
-        },
-        Tools::MemoryWrite::NAME => lambda { |args|
-          {
-            name: Tools::MemoryWrite::NAME,
-            content: args["content"] || args["text"] || args["body"],
-            path: args["name"], scope: args["scope"],
-            description: args["description"],
-            current_model_only: args["current_model_only"],
-            start_line: nil, end_line: nil,
-            cwd: nil, env: nil
-          }
-        },
-        Tools::Edit::NAME => lambda { |args|
-          old_text = args["old_text"] || args["old"]
-          new_text = args["new_text"] || args["new"]
-          {
-            name: Tools::Edit::NAME,
-            content: "<old>#{old_text}</old><new>#{new_text}</new>",
-            path: args["path"],
-            start_line: args["start_line"], end_line: args["end_line"],
-            scope: nil, cwd: nil, env: nil, description: nil
-          }
-        },
-        Tools::TaskCreate::NAME => lambda { |args|
-          {
-            name: Tools::TaskCreate::NAME,
-            content: args["command"].to_s,
-            path: nil, scope: nil,
-            start_line: nil, end_line: nil,
-            cwd: args["cwd"], env: args["env"], description: nil
-          }
-        },
-        Tools::TaskGet::NAME => lambda { |args|
-          {
-            name: Tools::TaskGet::NAME,
-            content: (args["id"] || args["task_id"]).to_s,
-            path: nil, scope: nil,
-            start_line: nil, end_line: nil,
-            cwd: nil, env: nil, description: nil
-          }
-        },
-        Tools::TaskStop::NAME => lambda { |args|
-          {
-            name: Tools::TaskStop::NAME,
-            content: (args["id"] || args["task_id"]).to_s,
-            path: nil, scope: nil,
-            start_line: nil, end_line: nil,
-            cwd: nil, env: nil, description: nil
-          }
-        },
-        Tools::TaskWait::NAME => lambda { |args|
-          {
-            name: Tools::TaskWait::NAME,
-            content: (args["id"] || args["task_id"]).to_s,
-            path: nil, scope: nil,
-            start_line: nil, end_line: nil,
-            cwd: nil, env: nil,
-            timeout: args["timeout"], tail_lines: args["tail_lines"], done_pattern: args["done_pattern"],
-            description: nil
-          }
-        },
-        Tools::TaskList::NAME => lambda { |_args|
-          {
-            name: Tools::TaskList::NAME,
-            content: "", path: nil, scope: nil,
-            start_line: nil, end_line: nil,
-            cwd: nil, env: nil, description: nil
-          }
-        },
-        Tools::WebFetch::NAME => lambda { |args|
-          {
-            name: Tools::WebFetch::NAME,
-            content: args["url"].to_s,
-            path: nil, scope: nil,
-            start_line: nil, end_line: nil,
-            cwd: nil, env: nil, description: nil
-          }
-        },
-        Tools::RegisterReminder::NAME => lambda { |args|
-          {
-            name: Tools::RegisterReminder::NAME,
-            content: args["name"].to_s,
-            path: nil, scope: nil,
-            description: args["description"],
-            interval_minutes: args["interval_minutes"]
-          }
-        },
-        Tools::CancelReminder::NAME => lambda { |args|
-          { name: Tools::CancelReminder::NAME, content: args["name"].to_s, path: nil, scope: nil }
-        },
-        Tools::ListReminders::NAME => lambda { |_args|
-          { name: Tools::ListReminders::NAME, content: "", path: nil, scope: nil }
-        },
-        Tools::ListSessions::NAME => lambda { |args|
-          { name: Tools::ListSessions::NAME, content: "", path: nil, scope: nil, cwd: args["cwd"] }
-        },
-        Tools::SendNote::NAME => lambda { |args|
-          { name: Tools::SendNote::NAME, content: args["text"].to_s, path: nil, scope: nil, session: args["session"].to_s }
-        },
-        Tools::Delegate::NAME => lambda { |args|
-          { name: Tools::Delegate::NAME, content: args["task"].to_s, path: nil, scope: nil,
-            model: args["model"], session: args["session"], wait: args["wait"], timeout: args["timeout"] }
-        },
-        Tools::DelegateResult::NAME => lambda { |args|
-          { name: Tools::DelegateResult::NAME, content: "", path: nil, scope: nil,
-            session: args["session"], timeout: args["timeout"] }
-        },
-        Tools::AskUserQuestion::NAME => lambda { |args|
-          raw_opts = args["options"]
-          norm_opts = Samagotchi::Tools::AskUserQuestion.normalize_options_lenient(raw_opts)
-          norm_opts = raw_opts if norm_opts.empty? && raw_opts.is_a?(Array)
-          {
-            name: Tools::AskUserQuestion::NAME,
-            content: args["question"].to_s,
-            path: nil, scope: nil,
-            question: args["question"].to_s,
-            options: norm_opts.empty? ? raw_opts : norm_opts,
-            header: args["header"],
-            multi_select: args["multi_select"],
-            allow_freeform: args["allow_freeform"]
-          }
-        }
-      }.freeze
-
       class << self
         # Map a single native tool call (LLM::ToolCall) to the internal call hash.
         #
@@ -221,12 +23,7 @@ module Samagotchi
         def normalize(call)
           return nil if call.nil?
 
-          name = call.name.to_s
-          args = args_for(call)
-          proc = MAP[name]
-          return passthrough(name, args) unless proc
-
-          proc.call(args).merge(name: name)
+          Tools::BuiltinCalls.build(call.name.to_s, args_for(call))
         end
 
         # Map an Array of tool calls to internal call hashes (nils dropped).
@@ -252,25 +49,11 @@ module Samagotchi
         end
 
         def safe_json_parse(str)
-          JSON.parse(str)
+          parsed = JSON.parse(str)
+          parsed.is_a?(Hash) ? parsed : { "__raw__" => str }
         rescue JSON::ParserError
           { "__raw__" => str }
         end
-
-        # A registry (plugin) tool, or an unknown one: the arguments as args:
-        # (typed by the schema at dispatch), plus enough for `dispatch` to
-        # render the standard "unknown tool" error. `content` is the joined
-        # argument values (harmless; the unknown-tool branch ignores it).
-        def passthrough(name, args)
-          {
-            name: name,
-            content: args.is_a?(Hash) ? args.values.join(" ") : name,
-            path: nil, scope: nil,
-            start_line: nil, end_line: nil,
-            cwd: nil, env: nil, description: nil,
-            args: args.is_a?(Hash) ? args : {}
-          }
-        end
       end
     end
   end

data/lib/samagotchi/memory_bundle/builder.rb

@@ -14,8 +14,6 @@ module Samagotchi
     # Inverse of Installer: reads from the resolved scope directory,
     # computes SHA256 checksums, writes manifest.yml via Manifest.write,
     # and optionally zips/tars the staging directory.
-    #
-    # Reuses Installer.system_dir / project_dir_base overrides for test isolation.
     class Builder
       class BuildError < StandardError; end
 
@@ -291,18 +289,7 @@ module Samagotchi
       end
 
       def resolve_target_dir(scope)
-        case scope
-        when "system"
-          Samagotchi::MemoryBundle::Installer.system_dir
-        when "project"
-          if Samagotchi::MemoryBundle::Installer.project_dir_base_override
-            Samagotchi::MemoryBundle::Installer.project_dir_base
-          else
-            File.join(Samagotchi::MemoryBundle::Installer.project_dir_base, MemoryPaths.project_key)
-          end
-        else
-          raise BuildError, "invalid scope: #{scope}"
-        end
+        MemoryPaths.scope_dir(scope) or raise BuildError, "invalid scope: #{scope}"
       end
 
       def resolve_out_path(out_arg, default_name)

data/lib/samagotchi/memory_bundle/index_updater.rb

@@ -7,22 +7,9 @@ module Samagotchi
   module MemoryBundle
     # Updates the scoped index.md for a single entry, locked and atomically.
     # Used by Installer (P3) to keep index.md in sync.
-    # Delegates to MemoryRead.memories_dir for test-isolated paths.
     module IndexUpdater
       MEMORY_INDEX = "index"
       LOCK_FILE = ".index.lock"
-      def self.system_dir_override
-        @system_dir_override
-      end
-      def self.system_dir_override=(val)
-        @system_dir_override = val
-      end
-      def self.project_dir_base_override
-        @project_dir_base_override
-      end
-      def self.project_dir_base_override=(val)
-        @project_dir_base_override = val
-      end
       def self.update_index(scope, entry_name, byte_count, description = nil)
         index_path = index_path_for(scope)
         return true unless index_path
@@ -93,21 +80,8 @@ module Samagotchi
         Date.today.iso8601
       end
       def self.index_path_for(scope)
-        normalized = scope.to_s.strip
-        normalized = "system" if normalized.empty?
-        base_dir = case normalized
-                   when "system"
-                     system_dir_override || MemoryPaths.system_dir
-                   when "project"
-                     if project_dir_base_override
-                       File.join(project_dir_base_override, MemoryPaths.project_key)
-                     else
-                       MemoryPaths.project_dir
-                     end
-                   else
-                     return nil
-                   end
-        File.join(base_dir, "#{MEMORY_INDEX}.md")
+        base_dir = MemoryPaths.scope_dir(scope.to_s.strip)
+        base_dir && File.join(base_dir, "#{MEMORY_INDEX}.md")
       end
     end
   end

data/lib/samagotchi/memory_bundle/installer.rb

@@ -29,18 +29,6 @@ module Samagotchi
 
       attr_reader :results, :warnings, :placeholder_warnings, :conflicts
 
-      class << self
-        attr_accessor :system_dir_override, :project_dir_base_override
-
-        def system_dir
-          system_dir_override || MemoryPaths.system_dir
-        end
-
-        def project_dir_base
-          project_dir_base_override || MemoryPaths.projects_dir
-        end
-      end
-
       def initialize(source:, name:, scope: nil, force: false, strict: true, upgrade: false, dry_run: false)
         @source = source
         @name = name
@@ -53,9 +41,6 @@ module Samagotchi
         @warnings = []
         @placeholder_warnings = []
         @conflicts = {}
-        # Propagate scope overrides so IndexUpdater resolves the correct directories.
-        IndexUpdater.system_dir_override = self.class.system_dir_override
-        IndexUpdater.project_dir_base_override = self.class.project_dir_base_override
       end
 
       def run
@@ -531,18 +516,7 @@ module Samagotchi
       end
 
       def resolve_target_dir(scope)
-        case scope
-        when "system", ""
-          self.class.system_dir
-        when "project"
-          if self.class.project_dir_base_override
-            self.class.project_dir_base
-          else
-            File.join(self.class.project_dir_base, MemoryPaths.project_key)
-          end
-        else
-          raise InstallError, "invalid scope: #{scope}"
-        end
+        MemoryPaths.scope_dir(scope) or raise InstallError, "invalid scope: #{scope}"
       end
     end
   end

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -14,12 +14,8 @@ module Samagotchi
     #   manifest.json — metadata about the install (merged on reinstall)
     #   bases/        — snapshots of every file as installed (for 3-way merge later)
     class Provenance
-      class << self
-        attr_accessor :bundles_dir_override
-
-        def bundles_dir
-          bundles_dir_override || MemoryPaths.bundles_dir
-        end
+      def self.bundles_dir
+        MemoryPaths.bundles_dir
       end
 
       attr_reader :name, :bundle_dir