samagotchi 0.18.1 → 0.19.0

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -88,7 +88,7 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 | `install <source> [--scope system\|project] [--force]` | Install from dir/zip/tar.gz/git URL. `--force` overwrites existing entries, otherwise skips them; a skipped file stays the user's (not recorded, never upgraded or removed by the bundle). Writes provenance to `.bundles/<name>/` (base snapshots + `manifest.json`) and updates `index.md`. Warns on double-brace placeholders and checksum mismatches (strict mode). |
 | `upgrade <source> [--force] [--dry-run] [--agent]` | 3-way merge upgrade (base vs current vs incoming) per `Merger.classify`: `install` (new file), `noop` (current==incoming), `fast_forward` (current==base, not edited → auto-update), `keep` (incoming==base → preserve local edits), `conflict` (both edited → warn, needs `--force` or interactive `memory_write` resolution). Pruned files (removed from new bundle) are kept if locally edited, otherwise warned. |
 | `uninstall <bundle> [--force]` | Moves the bundle's memory files to `.bundles/.trash/<bundle>-<time>/` (refuses locally edited ones unless `--force`; keeps a file another installed bundle also lists), removes their `index.md` lines, deletes the provenance dir. |
-| `status [<bundle>]` | Provenance + per-file `ok|modified|missing|no-index` vs stored checksum and base snapshot. |
+| `status [<bundle>]` | Provenance + per-file `ok|modified|missing|no-index` vs stored checksum and base snapshot; a model overlay (`<name>.<key>.md`) has no index line and reads `ok (model overlay)`. |
 | `diff <bundle> [file]` | Prints `base` (provenance snapshot) vs `current` (on-disk) for each file. |
 | `list` | Lists installed bundles (`name v<version> scope files installed_at`, plus the shipped version when newer) and the bundles shipped with chi that are not installed (`install <name>` installs one), grouped under their profile; an installed profile shows `includes=` and `left out=`. |
 | `build [--scope system\|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]` | **Inverse of install** — builds a shareable bundle from local memories and installed hooks. Infers `zip` vs `dir`/`tar.gz` from `--out` extension; default `chi_system_memories.zip` (system) or `chi_<repo>_memories.zip` (project, named after the project root) v`1.0.0` in `Dir.pwd`. `FILES...` is an optional allowlist of memory basenames (`identity` or `identity.md`); if omitted, all `*.md` except `index.md`/hidden/non-md and the memories other installed bundles own (each named in a `Left out` line) are included. Installed hooks are copied to `hooks/` with their manifest metadata. Computes `sha256:` checksums and writes `manifest.yml` via `Manifest.write`. No provenance write. |

data/lib/samagotchi/engine.rb

@@ -169,9 +169,10 @@ module Samagotchi
       # kernel's dispatch): the built-ins, per Engine.
       @tools = Tools::Builtins.registry
       if @scratch
-        # A scratch session's children would outlive it; its memories
-        # would too (write and edit into the memories: ScratchWrites).
-        [Tools::Delegate::NAME, Tools::DelegateResult::NAME].each { |name| @tools.unregister(name) }
+        # A scratch session's children would outlive it, and so would a
+        # note it left in a peer; its memories would too (write and edit
+        # into the memories: ScratchWrites).
+        [Tools::Delegate::NAME, Tools::DelegateResult::NAME, Tools::SendNote::NAME].each { |name| @tools.unregister(name) }
         @tools[Tools::MemoryWrite::NAME].handler = ->(_call, _kctx) { SCRATCH_MEMORY_WRITE }
       end
       # Likewise the slash commands its SessionCommands run.
@@ -614,6 +615,11 @@ module Samagotchi
       Thread.current[key] = outer
     end
 
+    # Whether an anytime command (/btw) still runs on its thread.
+    def anytime_running?
+      @lifecycle_mutex.synchronize { @anytime_threads.any?(&:alive?) }
+    end
+
     # Start an anytime command on its own thread (D8), one #shutdown waits
     # for, so its command_ran is announced before the process leaves.
     # @return [Thread]

data/lib/samagotchi/guardrail_wiring.rb

@@ -70,10 +70,15 @@ module Samagotchi
       @interface = value
     end
 
+    # The approval scopes a scratch session offers: nothing outlives it.
+    SCRATCH_SCOPES = %w[once session].freeze
+
     # Where the approval store lives: beside Session's state dir
-    # ($XDG_STATE_HOME/samagotchi/guardrails/).
+    # ($XDG_STATE_HOME/samagotchi/guardrails/). A scratch session reads
+    # it but keeps its own session approvals in memory.
     def state_dir=(state_dir)
       @approvals = Guardrails::Approvals.new(dir: Guardrails::Approvals.dir_for(state_dir))
+      @approvals = Guardrails::Approvals::InMemory.new(@approvals) if @scratch
       @protected = nil
     end
 
@@ -207,7 +212,8 @@ module Samagotchi
       # A plugin tool is asked about by its label, as its row shows it.
       label = ToolActivity.plugin_label(verdict.call[:name].to_s, registry: @tools_lookup.call)
       # verdict.call is the call that will run (a hook may have replaced it).
-      payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call))
+      payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call),
+                                                      only: (SCRATCH_SCOPES if @scratch))
       Guardrails::Approval.settle(verdict, @ask.call(payload), payload[:approval][:scopes])
     end
 

data/lib/samagotchi/guardrails/approval.rb

@@ -22,9 +22,11 @@ module Samagotchi
       #   approval[:tool] stays the raw name
       # @param preview [Hash, nil] EditPreview.for(verdict.call) for edit and
       #   write: the card shows its diff, the question text one change line
+      # @param only [Array<String>, nil] offer no scope beyond these (a
+      #   scratch session: once, session); "once" when none is left
       # @return [Hash] open_question fields
-      def payload(verdict, label: nil, preview: nil)
-        scopes = offered_scopes(verdict)
+      def payload(verdict, label: nil, preview: nil, only: nil)
+        scopes = offered_scopes(verdict, only: only)
         targets = verdict.targets
         {
           question: question_text(verdict, label: label, preview: preview),
@@ -81,8 +83,12 @@ module Samagotchi
       end
 
       # The rule's scopes; "rule" only when a rule id names what to approve.
-      def offered_scopes(verdict)
-        verdict.scopes.reject { |scope| scope == "rule" && verdict.rule.nil? }
+      def offered_scopes(verdict, only: nil)
+        scopes = verdict.scopes.reject { |scope| scope == "rule" && verdict.rule.nil? }
+        return scopes unless only
+
+        scopes &= only
+        scopes.empty? ? ["once"] : scopes
       end
 
       def label(scope, verdict)

data/lib/samagotchi/guardrails/approvals.rb

@@ -45,10 +45,25 @@ module Samagotchi
       # @param verdict [Verdict] an ask with its targets and context
       # @return [Hash, nil] the first entry that allows it
       def match(verdict)
-        key = self.class.key_for(verdict)
-        place = self.class.place_for(verdict)
+        self.class.find_in(read, verdict)
+      end
+
+      # Store the verdict's allowed scope (not "once").
+      # @return [Hash, nil] the entry
+      def add(verdict, scope)
+        entry = self.class.entry_for(verdict, scope) or return nil
+
+        update { |list| list << entry unless list.any? { |e| e.except("created_at") == entry.except("created_at") } }
+        entry
+      end
+
+      # @param list [Array<Hash>] entries
+      # @return [Hash, nil] the first of +list+ that allows +verdict+
+      def self.find_in(list, verdict)
+        key = key_for(verdict)
+        place = place_for(verdict)
         session_id = verdict.context&.session_id
-        read.find do |e|
+        list.find do |e|
           case e["scope"]
           when "session" then session_id && e["session_id"] == session_id && e["key"] == key
           when "repo" then e["repo_root"] == place && e["key"] == key
@@ -58,21 +73,18 @@ module Samagotchi
         end
       end
 
-      # Store the verdict's allowed scope (not "once").
-      # @return [Hash, nil] the entry
-      def add(verdict, scope)
+      # @return [Hash, nil] the entry that stores +scope+ for +verdict+; nil for "once"
+      def self.entry_for(verdict, scope)
         return nil unless STORED_SCOPES.include?(scope)
 
         entry = { "scope" => scope, "tool" => verdict.targets&.tool || verdict.call[:name].to_s,
                   "rule" => verdict.rule, "source" => verdict.source, "created_at" => Time.now.utc.iso8601 }
         case scope
-        when "session" then entry.merge!("session_id" => verdict.context&.session_id, "key" => self.class.key_for(verdict))
-        when "repo" then entry.merge!("repo_root" => self.class.place_for(verdict), "key" => self.class.key_for(verdict))
-        when "rule" then entry["repo_root"] = self.class.place_for(verdict)
+        when "session" then entry.merge!("session_id" => verdict.context&.session_id, "key" => key_for(verdict))
+        when "repo" then entry.merge!("repo_root" => place_for(verdict), "key" => key_for(verdict))
+        when "rule" then entry["repo_root"] = place_for(verdict)
         end
-        entry.compact!
-        update { |list| list << entry unless list.any? { |e| e.except("created_at") == entry.except("created_at") } }
-        entry
+        entry.compact
       end
 
       # Remove entry +index+ (0-based, as #entries lists them).
@@ -167,6 +179,42 @@ module Samagotchi
           AtomicFile.write(@path, JSON.pretty_generate(list))
         end
       end
+
+      # A scratch session's approvals: the store's entries still apply, and
+      # its own session approvals are kept in memory, so none outlives it
+      # (it offers no wider scope; one that comes anyway is not kept).
+      class InMemory
+        def initialize(store)
+          @store = store
+          @own = []
+          @mutex = Mutex.new
+        end
+
+        def path = @store.path
+
+        # The store's entries, then this session's own.
+        def entries = @store.entries + @mutex.synchronize { @own.dup }
+
+        def match(verdict)
+          @mutex.synchronize { Approvals.find_in(@own, verdict) } || @store.match(verdict)
+        end
+
+        def add(verdict, scope)
+          return nil unless scope == "session"
+
+          entry = Approvals.entry_for(verdict, scope)
+          @mutex.synchronize { @own << entry unless @own.any? { |e| e.except("created_at") == entry.except("created_at") } }
+          entry
+        end
+
+        # Index as #entries lists them: the store's first, then its own.
+        def revoke(index)
+          stored = @store.entries.size
+          return @store.revoke(index) if index < stored
+
+          @mutex.synchronize { index - stored < @own.size ? @own.delete_at(index - stored) : nil }
+        end
+      end
     end
   end
 end

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_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/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
@@ -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

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
 
@@ -56,6 +58,7 @@ module Samagotchi
         manifest = nil
         begin
           normalized_dir, source_owned, source_commit = SourceNormalizer.normalize(@source)
+          @bundle_dir = normalized_dir
           manifest = Manifest.read(dir: normalized_dir)
         rescue SourceNormalizer::UnknownSourceError => e
           raise InstallError, "Source normalization failed: #{e.message}"
@@ -89,6 +92,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)
@@ -550,9 +554,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

data/lib/samagotchi/memory_bundle/status.rb

@@ -6,6 +6,7 @@ require_relative "../version"
 require_relative "index_updater"
 require_relative "../memory_paths"
 require_relative "../bundle_needs"
+require_relative "../model_overlay"
 
 module Samagotchi
   module MemoryBundle
@@ -29,7 +30,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,6 +41,7 @@ module Samagotchi
             modified: modified,
             missing: missing,
             index_present: index_present,
+            overlay: overlay,
             target_path: target_path,
             base_path: base_path
           }

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
@@ -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,7 +122,8 @@ 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

data/lib/samagotchi/model_overlay.rb

@@ -49,5 +49,44 @@ module Samagotchi
     # Regex matching overlay file names: /<something>.<lowercase-dashed-key>.md\z
     # Useful for tooling, tests, and future index suppression.
     OVERLAY_SUFFIX_PATTERN = /\.([a-z0-9\-]+)\.md\z/
+
+    # The base file name (`tips.md`) an overlay-looking name
+    # (`tips.qwen3.md`) would belong to, or nil when it doesn't match the
+    # suffix pattern.
+    def self.base_file_for(path)
+      match = File.basename(path.to_s).match(OVERLAY_SUFFIX_PATTERN)
+      return nil unless match
+
+      stem = File.basename(path.to_s).delete_suffix(match[0])
+      stem.empty? ? nil : "#{stem}.md"
+    end
+
+    # Whether +path+ is a model overlay: its name matches the suffix pattern
+    # and its base `<stem>.md` exists in one of +base_dirs+ (default: the
+    # file's own dir) or is one of +base_names+. A memory whose name has a
+    # dot and a sibling of the same stem reads as an overlay too (a
+    # leftover ambiguity).
+    def self.overlay_file?(path, base_dirs: [File.dirname(path.to_s)], base_names: [])
+      base = base_file_for(path)
+      return false unless base
+
+      base_names.map { |n| File.basename(n.to_s) }.include?(base) ||
+        base_dirs.compact.any? { |dir| File.file?(File.join(dir, base)) }
+    end
+
+    # How a bundle's installer, status and uninstaller tell an overlay
+    # (they agree, so a line the installer left out isn't "no-index"): the
+    # base is one of +bundle_files+ (basenames), or it is nowhere in
+    # +target_dir+ (an orphan overlay; it loads once the base exists).
+    # A base only in +target_dir+ (an installed memory, maybe the user's
+    # own) counts too: the installer warns, so the dot-name ambiguity
+    # (notes.v2.md next to a user's notes.md) is visible.
+    def self.bundle_overlay?(file_key, bundle_files:, target_dir:)
+      base = base_file_for(file_key)
+      return false unless base
+
+      overlay_file?(file_key, base_dirs: [target_dir], base_names: bundle_files) ||
+        !File.file?(File.join(target_dir, base))
+    end
   end
 end

data/lib/samagotchi/model_profile.rb

@@ -11,6 +11,10 @@ module Samagotchi
   #   gemma4  — Gemma 4 format
   class ModelProfile
     MODEL_ENV = "SAMAGOTCHI_DEFAULT_MODEL"
+    # Set beside MODEL_ENV for a worker spawned by a `chi --model X`: X is
+    # that run's default, not one its commands' chi should inherit
+    # (SessionManager.spawn_options, Tools::Builtins.parent_env).
+    MODEL_FROM_CLI_ENV = "SAMAGOTCHI_DEFAULT_MODEL_FROM_CLI"
     # 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)

data/lib/samagotchi/relay_desk.rb

@@ -63,6 +63,15 @@ module Samagotchi
       end
     end
 
+    # Whether a relay is open, or settled recently enough that its child
+    # may still ask about it: a restart would drop them.
+    def active?
+      @mutex.synchronize do
+        prune
+        !@relays.empty?
+      end
+    end
+
     private
 
     def prune