samagotchi 0.18.1 → 0.20.0

data/lib/samagotchi/host_registry.rb

@@ -2,6 +2,7 @@
 
 require "ipaddr"
 require_relative "config"
+require_relative "log"
 require_relative "model_ref"
 require_relative "client"
 require_relative "llm/openai_chat"
@@ -125,9 +126,17 @@ module Samagotchi
     LOCAL_NETS = %w[127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 100.64.0.0/10
                     ::1/128 fc00::/7 fe80::/10].map { |net| IPAddr.new(net) }.freeze
 
-    # Whether an address is remote: https, or an http IP address outside
-    # the local nets (LOCAL_NETS). An http host named by a name (localhost,
-    # box, mac.local, gpu.lan) counts as local: chi doesn't look names up.
+    # Name suffixes that stay on a home or office network: mDNS, the
+    # special-use and customary private names, router defaults (fritz.box)
+    # and Tailscale's MagicDNS. Compared on whole labels.
+    LOCAL_NAME_SUFFIXES = %w[localhost local lan home home.arpa internal intranet localdomain private corp test
+                             box ts.net].freeze
+
+    # Whether an address is remote: https, an http IP address outside the
+    # local nets (LOCAL_NETS), or an http name with a dot whose suffix isn't
+    # a local one (LOCAL_NAME_SUFFIXES): `gpu.example.com` is remote, while
+    # `box`, `mac.local`, `gpu.lan` and `pc.tail1234.ts.net` are local. chi
+    # doesn't look names up; hosts.<name>.remote overrides either way.
     def self.remote_address?(scheme, host)
       return true if scheme.to_s == "https"
 
@@ -135,9 +144,17 @@ module Samagotchi
       address = address.native if address.ipv4_mapped?
       LOCAL_NETS.none? { |net| net.family == address.family && net.include?(address) }
     rescue IPAddr::Error
-      false
+      remote_name?(host)
     end
 
+    def self.remote_name?(host)
+      name = host.to_s.downcase.delete_suffix(".")
+      return false unless name.include?(".")
+
+      LOCAL_NAME_SUFFIXES.none? { |suffix| name == suffix || name.end_with?(".#{suffix}") }
+    end
+    private_class_method :remote_name?
+
     # server.first_token_timeout, or nil when unset or unreadable.
     def self.configured_first_token_timeout
       Config.get("server.first_token_timeout")
@@ -273,6 +290,7 @@ module Samagotchi
             data = { host: entry.host, port: entry.port, transport: entry.transport, models: models, error: nil }
             @mutex.synchronize { @host_lists[name] = { data: data, at: @clock.call } }
           rescue StandardError => e
+            Log.warn(:model, "list_failed", host: name, error: e.class.name, msg: e.message.to_s[0, 500])
             data = { host: entry.host, port: entry.port, transport: entry.transport, models: [], error: e.message }
           end
           results_mutex.synchronize { results[name] = data }

data/lib/samagotchi/idle_recap.rb

@@ -52,6 +52,8 @@ module Samagotchi
       # separator, while the chat loop writes one message per call.
       TOOL_OUTPUT_SEPARATOR = "\n\n---\n\n"
       TOOL_OUTPUT_HEADER_RE = /\A\[([\w.:-]+)\]/
+      # The text the web sends for a turn of images alone (images.js turnText).
+      IMAGE_ONLY_RE = /\A\s*(?:\[image: [^\]\n]*\]\s*)+\z/
 
       module_function
 
@@ -64,8 +66,11 @@ module Samagotchi
             # A plugin's steer is a prod to the model, not what the user said.
             next nil if Steer.steer?(message)
 
-            # An image is a line naming it (refs only, never its bytes).
-            [message["content"].to_s, *image_lines(message["images"])].reject(&:empty?).join("\n")
+            # An image is a line naming it (refs only, never its bytes), unless
+            # the text is only the web's placeholder naming it already.
+            content = message["content"].to_s
+            images = IMAGE_ONLY_RE.match?(content) ? [] : image_lines(message["images"])
+            [content, *images].reject(&:empty?).join("\n")
           when "model", "assistant"
             strip_thought(message["content"].to_s.gsub(TOOL_CALL_RE, ""))
           else

data/lib/samagotchi/idle_scheduler.rb

@@ -56,7 +56,7 @@ module Samagotchi
       @jobs.each do |job|
         job.tick
       rescue StandardError => e
-        Log.warn(:idle, "tick_failed", echo: "[IdleScheduler] #{job.class} tick failed: #{e.class}: #{e.message}", job: job.class.name, error: e.class.name)
+        Log.exception(:idle, "tick_failed", e, echo: "[IdleScheduler] #{job.class} tick failed: #{e.class}: #{e.message}", job: job.class.name)
       end
     end
 

data/lib/samagotchi/installed_versions.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "installed_gem"
+require_relative "version"
+
+module Samagotchi
+  # The newest chi on this machine, which a long-lived process (chi web, an
+  # attaching TUI) compares with its own VERSION to say "chi X is installed;
+  # restart". Run from an installed gem: the highest samagotchi-<v>.gemspec
+  # in RubyGems' specification dirs, matching the `>= 0.a` a new worker
+  # activates (prereleases count). Run from a source checkout: the VERSION
+  # in lib/samagotchi/version.rb on disk now (a `git pull` moves it).
+  #
+  # Cheap enough to poll: each dir is listed again only when its mtime
+  # changed, version.rb is re-read only when its mtime did, and nothing
+  # calls Gem::Specification.reset (that would disturb the running process).
+  #
+  # SAMAGOTCHI_INSTALLED_VERSION=<v> (hidden, for smokes and e2e) answers
+  # <v> instead.
+  class InstalledVersions
+    ENV_KEY = "SAMAGOTCHI_INSTALLED_VERSION"
+    GEMSPEC = /\Asamagotchi-(#{Gem::Version::VERSION_PATTERN})\.gemspec\z/
+    VERSION_LINE = /^\s*VERSION\s*=\s*["']([^"']+)["']/
+    REQUIREMENT = Gem::Requirement.new(">= 0.a")
+
+    # @param gem_spec [Gem::Specification, nil] the installed gem this code
+    #   runs from (nil: a source checkout)
+    # @param dirs [#call] → the specification dirs to list
+    # @param version_file [String] a checkout's version.rb
+    def initialize(env: ENV, gem_spec: InstalledGem.spec, dirs: -> { Gem::Specification.dirs },
+                   version_file: File.join(InstalledGem::ROOT, "lib", "samagotchi", "version.rb"))
+      @env = env
+      @gem_spec = gem_spec
+      @dirs = dirs
+      @version_file = version_file
+      @dir_cache = {}
+      @file_cache = nil
+      @mutex = Mutex.new
+    end
+
+    # @return [String, nil] the newest installed version, or nil when none
+    #   could be found out
+    def newest
+      seam = @env[ENV_KEY].to_s
+      return seam unless seam.empty?
+
+      @mutex.synchronize { @gem_spec ? newest_gem : checkout_version }
+    end
+
+    # Whether +installed+ is a newer version than +running+.
+    def self.newer?(installed, running = VERSION)
+      return false if installed.to_s.empty? || !Gem::Version.correct?(installed) || !Gem::Version.correct?(running)
+
+      Gem::Version.new(installed) > Gem::Version.new(running)
+    end
+
+    private
+
+    def newest_gem
+      @dirs.call.filter_map { |dir| dir_newest(dir) }.max&.to_s
+    end
+
+    def dir_newest(dir)
+      mtime = File.mtime(dir)
+      cached = @dir_cache[dir]
+      return cached[1] if cached && cached[0] == mtime
+
+      best = Dir.children(dir).filter_map { |name| GEMSPEC.match(name)&.[](1) }
+                .select { |v| Gem::Version.correct?(v) }
+                .map { |v| Gem::Version.new(v) }
+                .select { |v| REQUIREMENT.satisfied_by?(v) }.max
+      @dir_cache[dir] = [mtime, best]
+      best
+    rescue SystemCallError
+      @dir_cache.delete(dir)
+      nil
+    end
+
+    def checkout_version
+      mtime = File.mtime(@version_file)
+      return @file_cache[1] if @file_cache && @file_cache[0] == mtime
+
+      version = File.read(@version_file)[VERSION_LINE, 1]
+      version = nil unless version && Gem::Version.correct?(version)
+      @file_cache = [mtime, version]
+      version
+    rescue SystemCallError
+      nil
+    end
+  end
+end

data/lib/samagotchi/live_versions.rb

@@ -13,8 +13,9 @@ module Samagotchi
   module LiveVersions
     WEB_TIMEOUT = 0.5
 
-    # version is nil for a sidecar written before sidecars carried one.
-    Worker = Struct.new(:session_id, :version, keyword_init: true)
+    # version is nil for a sidecar written before sidecars carried one;
+    # restart: the worker takes `chi sessions restart` (its "restart" feature).
+    Worker = Struct.new(:session_id, :version, :restart, keyword_init: true)
 
     module_function
 
@@ -25,7 +26,8 @@ module Samagotchi
         sidecar = WorkerSidecar.live(session_dir, unlink: false)
         next unless sidecar
 
-        Worker.new(session_id: File.basename(session_dir), version: sidecar.version)
+        Worker.new(session_id: File.basename(session_dir), version: sidecar.version,
+                   restart: sidecar.features.include?("restart"))
       end
     end
 

data/lib/samagotchi/llm/usage.rb

@@ -12,7 +12,7 @@ module Samagotchi
         counts = TokenUsage.from_payload(payload)
         return nil unless counts
 
-        new(prompt_tokens: counts[:prompt_tokens].to_i, completion_tokens: counts[:completion_tokens].to_i,
+        new(prompt_tokens: counts.prompt_tokens.to_i, completion_tokens: counts.completion_tokens.to_i,
             source: :server)
       end
 

data/lib/samagotchi/memory_bundle/builder.rb

@@ -6,6 +6,7 @@ require "tmpdir"
 require_relative "manifest"
 require_relative "placeholder"
 require_relative "../memory_paths"
+require_relative "../model_overlay"
 
 module Samagotchi
   module MemoryBundle
@@ -40,7 +41,7 @@ module Samagotchi
       end
 
       def run
-        target_dir = resolve_target_dir(@scope)
+        target_dir = MemoryPaths.scope_dir(@scope) or raise BuildError, "invalid scope: #{@scope}"
         resolved_name = @name || default_name(@scope)
         resolved_version = @version || DEFAULT_VERSION
 
@@ -66,7 +67,7 @@ module Samagotchi
           unless missing.empty?
             raise BuildError, "Requested file(s) not found in #{@scope} scope: #{missing.join(', ')}"
           end
-          candidates = allow.map { |k| candidates_by_basename[k] }
+          candidates = with_overlays(allow, candidates_by_basename).map { |k| candidates_by_basename[k] }
         else
           candidates = leave_out_owned(candidates, resolved_name)
         end
@@ -302,6 +303,28 @@ module Samagotchi
         end
       end
 
+      # The named files, each base followed by its model overlays
+      # (<name>.<key>.md next to it, ModelOverlay.overlay_file?; a plain
+      # tips.v2.md with no tips.md isn't one), with a note listing them. An
+      # overlay named without its base is kept, with a warning.
+      def with_overlays(allow, candidates_by_basename)
+        dir = File.dirname(candidates_by_basename.values.first.to_s)
+        overlays = candidates_by_basename.keys.select { |k| ModelOverlay.overlay_file?(File.join(dir, k)) }
+        allow.flat_map do |key|
+          if overlays.include?(key)
+            base = ModelOverlay.base_file_for(key)
+            unless allow.include?(base)
+              @warnings << "#{key} is a model overlay of #{base}, which the bundle leaves out; it loads only where #{base} exists"
+            end
+            next [key]
+          end
+
+          own = overlays.select { |k| ModelOverlay.base_file_for(k) == key && !allow.include?(k) }.sort
+          @warnings << "Included the model overlays of #{key}: #{own.join(", ")}" unless own.empty?
+          [key, *own]
+        end.uniq
+      end
+
       def normalize_filter_entry(entry)
         s = entry.to_s.strip
         # Allow with or without .md extension, but normalize to basename with .md
@@ -310,10 +333,6 @@ module Samagotchi
         base
       end
 
-      def resolve_target_dir(scope)
-        MemoryPaths.scope_dir(scope) or raise BuildError, "invalid scope: #{scope}"
-      end
-
       def resolve_out_path(out_arg, default_name)
         if out_arg.nil? || out_arg.empty?
           # Default: <name>.zip in Dir.pwd

data/lib/samagotchi/memory_bundle/index_sync.rb

@@ -29,7 +29,7 @@ module Samagotchi
         return false unless scope && File.file?(path)
 
         name = File.basename(path, ".md")
-        return false if overlay?(path, name)
+        return false if ModelOverlay.overlay_file?(path)
 
         IndexUpdater.update_index(scope, name, File.size(path), nil)
       rescue StandardError => e
@@ -55,14 +55,6 @@ module Samagotchi
         nil
       end
 
-      def self.overlay?(path, name)
-        match = File.basename(path).match(ModelOverlay::OVERLAY_SUFFIX_PATTERN)
-        return false unless match
-
-        base = name.delete_suffix(".#{match[1]}")
-        File.file?(File.join(File.dirname(path), "#{base}.md"))
-      end
-
       def self.real(dir)
         File.realpath(dir)
       rescue SystemCallError

data/lib/samagotchi/memory_bundle/installer.rb

@@ -12,6 +12,7 @@ require_relative "merger"
 require_relative "trash"
 require_relative "../version"
 require_relative "../bundle_needs"
+require_relative "../model_overlay"
 
 module Samagotchi
   module MemoryBundle
@@ -42,6 +43,7 @@ module Samagotchi
         @warnings = []
         @placeholder_warnings = []
         @conflicts = {}
+        @overlays = []
         @trash = Trash.new(name)
       end
 
@@ -49,6 +51,22 @@ module Samagotchi
       # none moved).
       def trash_dir = @trash.dir
 
+      # The normalized source dir, kept alive past #run when an upgrade has
+      # conflicts (the agent step reads the incoming files); nil once cleaned.
+      attr_reader :source_dir
+
+      # Removes the normalized source dir an owned source (git/zip/tar) was
+      # extracted to. #run defers this when it found conflicts, so the
+      # conflict prompt and resolve_conflicts can still read the incoming
+      # files; the caller runs it once the agent step is done. Idempotent.
+      def cleanup_source!
+        return unless @defer_cleanup && @normalized_dir
+
+        SourceNormalizer.cleanup(@normalized_dir)
+        @normalized_dir = nil
+        @defer_cleanup = false
+      end
+
       def run
         normalized_dir = nil
         source_owned = false
@@ -56,6 +74,8 @@ module Samagotchi
         manifest = nil
         begin
           normalized_dir, source_owned, source_commit = SourceNormalizer.normalize(@source)
+          @bundle_dir = normalized_dir
+          @normalized_dir = normalized_dir
           manifest = Manifest.read(dir: normalized_dir)
         rescue SourceNormalizer::UnknownSourceError => e
           raise InstallError, "Source normalization failed: #{e.message}"
@@ -70,7 +90,7 @@ module Samagotchi
         # Determine target scope (CLI wins over manifest).
         cli_scope = @scope.to_s.strip.empty? ? nil : @scope
         target_scope = cli_scope || manifest&.scope || "system"
-        target_dir = resolve_target_dir(target_scope)
+        target_dir = MemoryPaths.scope_dir(target_scope) or raise InstallError, "invalid scope: #{target_scope}"
         FileUtils.mkdir_p(target_dir)
 
         # Copy .md files and update index for each.
@@ -89,6 +109,7 @@ module Samagotchi
         Dir.glob(File.join(normalized_dir, "*.md")).each do |file_path|
           file_key = File.basename(file_path)
           all_files_in_bundle << file_key
+          note_overlay(file_key, target_dir)
           target_path = File.join(target_dir, file_key)
 
           if @upgrade && existing_provenance && !@force && File.exist?(target_path) && !owned_before.include?(file_key)
@@ -195,12 +216,15 @@ module Samagotchi
             end
 
             FileUtils.mkdir_p(hooks_target)
+            unchanged = File.exist?(dest) && FileUtils.identical?(src, dest)
             FileUtils.cp(src, dest)
-            if @upgrade && existing_provenance
-              @results[basename] = { status: "updated" }
-            else
-              @results[basename] = { status: "installed" }
-            end
+            @results[basename] = if unchanged
+                                   { status: "skipped", reason: "already up to date" }
+                                 elsif @upgrade && existing_provenance
+                                   { status: "updated" }
+                                 else
+                                   { status: "installed" }
+                                 end
             hooks_files_for_provenance[basename] = dest
           end
         else
@@ -402,7 +426,17 @@ module Samagotchi
 
         [normalized_dir, manifest]
       ensure
-        SourceNormalizer.cleanup(normalized_dir) if source_owned
+        # An owned source (git/zip/tar) is cleaned up here, unless an upgrade
+        # kept conflicts: the agent step still needs the incoming files, so
+        # the caller runs #cleanup_source! when it is done.
+        if source_owned
+          if @conflicts.any? && !@dry_run
+            @defer_cleanup = true
+          else
+            SourceNormalizer.cleanup(normalized_dir)
+            @normalized_dir = nil
+          end
+        end
       end
 
       def summary
@@ -537,11 +571,18 @@ module Samagotchi
           return nil
         end
 
+        dest = File.join(provenance.plugin_dir, plugin[:file])
+        unchanged = File.file?(dest) && FileUtils.identical?(src, dest)
         FileUtils.rm_rf(provenance.plugin_dir)
         FileUtils.mkdir_p(provenance.plugin_dir)
-        dest = File.join(provenance.plugin_dir, plugin[:file])
         FileUtils.cp(src, dest)
-        @results[plugin[:file]] = { status: @upgrade && provenance.read ? "updated" : "installed" }
+        @results[plugin[:file]] = if unchanged
+                                   { status: "skipped", reason: "already up to date" }
+                                 elsif @upgrade && provenance.read
+                                   { status: "updated" }
+                                 else
+                                   { status: "installed" }
+                                 end
         expected = manifest.checksum_for_plugin
         actual = Digest::SHA256.hexdigest(File.binread(dest))
         if @strict && expected && actual != expected
@@ -550,9 +591,38 @@ module Samagotchi
         dest
       end
 
+      # A model overlay (<name>.<key>.md, docs/memory.md) loads only with
+      # its base, under the matching model: it gets no index line (every
+      # model would see it as a memory of its own). Its base is looked for
+      # in the bundle dir, not the target: Dir.glob sorts tips.<key>.md
+      # before tips.md, so on a fresh install the base isn't copied yet.
+      # An overlay-looking name with no base anywhere is an overlay too,
+      # with a warning (a dry run warns as well).
+      def note_overlay(file_key, target_dir)
+        @bundle_files ||= Dir.glob(File.join(@bundle_dir, "*.md")).map { |f| File.basename(f) }
+        return unless ModelOverlay.bundle_overlay?(file_key, bundle_files: @bundle_files, target_dir: target_dir)
+
+        @overlays << file_key
+        base = ModelOverlay.base_file_for(file_key)
+        return if @bundle_files.include?(base)
+
+        @warnings << if File.file?(File.join(target_dir, base))
+                       "#{file_key} is taken as a model overlay of your #{base}, which the bundle doesn't ship; " \
+                         "it gets no index line"
+                     else
+                       "#{file_key} is a model overlay with no #{base}; it loads only once #{base} exists"
+                     end
+      end
+
       # +owned+: the bundle wrote (owns) the file, so its line says
       # "· from <bundle>"; a skipped file's line keeps whatever it had.
+      # An overlay gets none: a stale one (an earlier install's) is removed.
       def update_target_index(scope, file_path, file_key, owned: true)
+        if @overlays.include?(file_key)
+          remove_target_index(scope, file_key) if owned
+          return
+        end
+
         byte_count = File.exist?(file_path) ? File.size(file_path) : 0
         entry_name = file_key.delete_suffix(".md")
         begin
@@ -565,10 +635,6 @@ module Samagotchi
           @warnings << "index.md: line for #{entry_name} not updated (#{e.message})"
         end
       end
-
-      def resolve_target_dir(scope)
-        MemoryPaths.scope_dir(scope) or raise InstallError, "invalid scope: #{scope}"
-      end
     end
   end
 end

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -9,6 +9,7 @@ require_relative "provenance"
 require_relative "source"
 require_relative "status"
 require_relative "system_bundle"
+require_relative "../memory_paths"
 require_relative "../version"
 
 module Samagotchi
@@ -112,6 +113,7 @@ module Samagotchi
           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"
+        return skip(row, "unknown scope #{row.scope}: upgrade chi or reinstall") unless MemoryPaths.scope_dir(row.scope)
 
         row.kept = conflicts(row, data)
         row.replaced = edited_executables(name, data)
@@ -147,7 +149,7 @@ module Samagotchi
       # version (a same-name file it didn't install is skipped, not merged).
       def conflicts(row, data)
         provenance = Provenance.new(name: row.name)
-        target_dir = Status.resolve_target_dir(row.scope)
+        target_dir = MemoryPaths.scope_dir!(row.scope)
         return [] unless data[:files].is_a?(Hash)
 
         owned = data[:files].keys.map(&:to_s)

data/lib/samagotchi/memory_bundle/status.rb

@@ -6,10 +6,14 @@ require_relative "../version"
 require_relative "index_updater"
 require_relative "../memory_paths"
 require_relative "../bundle_needs"
+require_relative "../model_overlay"
 
 module Samagotchi
   module MemoryBundle
     module Status
+      # A scope this chi can't resolve (a newer chi's, a hand edit) isn't
+      # guessed: scope_error says so, target_dir is nil and each file is
+      # unchecked (no disk reads, nothing counted as missing).
       def self.bundle_status(name, scope_override: nil)
         provenance = Provenance.new(name: name)
         data = provenance.read
@@ -17,11 +21,13 @@ module Samagotchi
 
         raw_scope = scope_override || data[:scope]&.to_s
         scope = (raw_scope.nil? || raw_scope.strip.empty?) ? "system" : raw_scope
-        target_dir = resolve_target_dir(scope)
+        target_dir = MemoryPaths.scope_dir(scope)
         files = data[:files] || {}
         details = {}
         files.each do |file_key, meta|
           file_key_str = file_key.to_s
+          next details[file_key_str] = unchecked_file(meta) unless target_dir
+
           target_path = File.join(target_dir, file_key_str)
           base_path = provenance.base_path(file_key_str)
           stored_checksum = meta[:checksum] || meta["checksum"]
@@ -29,7 +35,9 @@ module Samagotchi
           base_checksum = File.exist?(base_path) ? Digest::SHA256.hexdigest(File.read(base_path)) : nil
           modified = base_checksum && current_checksum && base_checksum != current_checksum
           missing = !File.exist?(target_path)
-          index_present = index_has_entry?(scope, file_key_str)
+          # A model overlay has no index line (Installer#note_overlay).
+          overlay = ModelOverlay.bundle_overlay?(file_key_str, bundle_files: files.keys.map(&:to_s), target_dir: target_dir)
+          index_present = overlay ? nil : index_has_entry?(scope, file_key_str)
           details[file_key_str] = {
             conflict: meta.is_a?(Hash) && meta[:conflict] == true,
             stored_checksum: stored_checksum,
@@ -38,11 +46,13 @@ module Samagotchi
             modified: modified,
             missing: missing,
             index_present: index_present,
+            overlay: overlay,
             target_path: target_path,
             base_path: base_path
           }
         end
-        { provenance: data, scope: scope, target_dir: target_dir, files: details, plugin: plugin_status(provenance, data),
+        { provenance: data, scope: scope, scope_error: target_dir ? nil : "unknown scope: #{scope}",
+          target_dir: target_dir, files: details, plugin: plugin_status(provenance, data),
           hooks_requires_failure: hooks_requires_failure(data), needs: needs_status(data) }
       end
 
@@ -87,9 +97,11 @@ module Samagotchi
           requires_failure: Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION) }
       end
 
-      def self.resolve_target_dir(scope)
-        MemoryPaths.scope_dir(scope) || MemoryPaths.system_dir
+      def self.unchecked_file(meta)
+        { conflict: meta.is_a?(Hash) && meta[:conflict] == true, stored_checksum: meta.is_a?(Hash) ? meta[:checksum] || meta["checksum"] : nil,
+          unchecked: true, modified: false, missing: false, index_present: nil, overlay: false }
       end
+      private_class_method :unchecked_file
 
       # Index lines name the entry without ".md" (Installer#update_target_index,
       # memory_write); a legacy "name.md" line counts too.

data/lib/samagotchi/memory_bundle/uninstaller.rb

@@ -6,6 +6,7 @@ require_relative "provenance"
 require_relative "index_updater"
 require_relative "merger"
 require_relative "trash"
+require_relative "../model_overlay"
 
 module Samagotchi
   module MemoryBundle
@@ -38,7 +39,7 @@ module Samagotchi
         cli_scope = @scope.to_s.strip.empty? ? nil : @scope
         raw = cli_scope || data[:scope]&.to_s
         target_scope = (raw.nil? || raw.strip.empty?) ? "system" : raw
-        target_dir = resolve_target_dir(target_scope)
+        target_dir = MemoryPaths.scope_dir(target_scope) or raise UninstallError, "invalid scope: #{target_scope}"
 
         files = data[:files] || {}
         hooks = data[:hooks] || {}
@@ -75,7 +76,9 @@ module Samagotchi
             next unless File.exist?(target_path)
 
             @warnings << "Kept #{file_key_str}: bundle #{others.join(", ")} has it too"
-            retag(target_scope, target_path, file_key_str, others.first)
+            unless ModelOverlay.bundle_overlay?(file_key_str, bundle_files: files.keys.map(&:to_s), target_dir: target_dir)
+              retag(target_scope, target_path, file_key_str, others.first)
+            end
             next
           end
           if File.exist?(target_path)
@@ -119,16 +122,13 @@ module Samagotchi
 
       private
 
-      # A kept shared file's index line names the bundle that still has it.
+      # A kept shared file's index line names the bundle that still has it
+      # (a model overlay has none: the caller skips it).
       def retag(scope, path, file_key, bundle)
         IndexUpdater.update_index(scope, file_key.delete_suffix(".md"), File.size(path), source: bundle)
       rescue StandardError => e
         @warnings << "index.md: line for #{file_key.delete_suffix(".md")} not updated (#{e.message})"
       end
-
-      def resolve_target_dir(scope)
-        MemoryPaths.scope_dir(scope) or raise UninstallError, "invalid scope: #{scope}"
-      end
     end
   end
 end

data/lib/samagotchi/memory_paths.rb

@@ -112,6 +112,12 @@ module Samagotchi
       end
     end
 
+    # scope_dir, or ArgumentError ("invalid scope: team") for a scope it
+    # doesn't know: for a caller that must not guess a folder.
+    def scope_dir!(scope, env: ENV, cwd: Dir.pwd)
+      scope_dir(scope, env: env, cwd: cwd) or raise ArgumentError, "invalid scope: #{scope}"
+    end
+
     def bundles_dir(env: ENV)
       File.join(system_dir(env: env), ".bundles")
     end