samagotchi 0.15.0 → 0.17.0

data/lib/samagotchi/engine.rb

@@ -56,6 +56,7 @@ require_relative "thinking"
 require_relative "answer_display"
 require_relative "edit_preview"
 require_relative "question_desk"
+require_relative "relay_desk"
 require_relative "guardrail_wiring"
 require_relative "plugin_tasks"
 
@@ -161,6 +162,8 @@ module Samagotchi
         interface: -> { interface },
         user_input: ->(sid) { ArchiveStore.user_input(sid, state_dir: session_state_dir) }
       )
+      # Built here, not on first use: the turn thread and the Bridge's read it.
+      @relay_desk = RelayDesk.new
       @hooks = load_hooks_from_config
       load_hooks_from_bundles
       # The tools this session offers (the prompts' declarations and the
@@ -240,7 +243,7 @@ module Samagotchi
       Log.debug(:model, "backend", provider: backend.provider) if Log.level?(:debug)
       @resume_session = session_id ? Session.load(session_id) : nil
       @prompt_builder = SystemPrompt.new(profile: -> { self.profile }, tools: -> { @tools }, session: -> { @session },
-                                         thinking: -> { turn_thinking }, memories: memories,
+                                         thinking: -> { turn_thinking }, model: -> { model_identity }, memories: memories,
                                          muted_memory_names: @muted_memory_names)
       @session = nil
       @session_observer = SessionObserver.new
@@ -408,6 +411,18 @@ module Samagotchi
       model_ref_for(@effective_model_name)
     end
 
+    # The effective model as the system prompt names it (SystemPrompt::ModelIdentity):
+    # the ref, its host, the overlay key and, for a local llama.cpp host
+    # only, the model its /props names when that differs. Never a new
+    # request: only the /props answer profile resolution already cached.
+    def model_identity
+      target = @host_registry.resolve(@effective_model_name)
+      entry = target.entry
+      host = entry && "host #{entry.name}, #{entry.url || "#{entry.host}:#{entry.port}"}"
+      SystemPrompt::ModelIdentity.new(ref: effective_model_ref, host: host, key: @model_key,
+                                      served: prompt_served_model(target), fallback_key: @fallback_model_key)
+    end
+
     # +name+'s resolved ref (ModelRef#ref).
     def model_ref_for(name)
       @host_registry.model_ref(name).ref
@@ -460,8 +475,8 @@ module Samagotchi
     def sync_model_key!
       @model_key = ModelOverlay.key_for(bare_model_name(@effective_model_name))
       typed_key = ModelOverlay.key_for(@host_registry.parse_qualified_model(@typed_model_name).last)
-      fallback = typed_key == @model_key ? nil : typed_key
-      @kernel.sync_model_key!(@model_key, fallback: fallback)
+      @fallback_model_key = typed_key == @model_key ? nil : typed_key
+      @kernel.sync_model_key!(@model_key, fallback: @fallback_model_key)
     end
     private :sync_model_key!
 
@@ -901,7 +916,7 @@ module Samagotchi
     # else [nil, nil].
     # @return [Array(String, String), Array(nil, nil)]
     def served_model(probe: true)
-      served_model_for(@metrics.snapshot, target: probe ? @host_registry.resolve(@effective_model_name) : nil)
+      served_model_for(@metrics.served_report, target: probe ? @host_registry.resolve(@effective_model_name) : nil)
     end
 
     # Read-only snapshot of the engine's view of the current session plus the
@@ -1232,15 +1247,25 @@ module Samagotchi
     # Open a question for the UIs and wait for its answer
     # (QuestionDesk#open_question: BLOCKS until answered or cancelled).
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
+    #   (as a Hash or as keywords)
+    # @param watch [#call, nil] closes the question with the reason it returns
     # @return [Hash, String] the answer, or {error:, …}
-    def open_question(fields)
-      @question_desk.open_question(fields)
+    def open_question(fields = nil, watch: nil, **more)
+      @question_desk.open_question({ **fields.to_h, **more }, watch: watch)
     end
 
     # Answer the pending question (called from UI thread; QuestionDesk#answer).
     # @return [Hash] normalized answer
-    def answer_question(id:, selected:, freeform: nil, client_id: nil)
-      @question_desk.answer(id: id, selected: selected, freeform: freeform, client_id: client_id)
+    def answer_question(id:, selected:, freeform: nil, client_id: nil, parent_agent: nil)
+      @question_desk.answer(id: id, selected: selected, freeform: freeform, client_id: client_id,
+                            parent_agent: parent_agent)
+    end
+
+    # Mark the pending question as relayed, or clear the mark
+    # (QuestionDesk#annotate).
+    # @return [Boolean]
+    def annotate_question(id, relayed_to:, reason: nil)
+      @question_desk.annotate(id, relayed_to: relayed_to, reason: reason)
     end
 
     def set_question_sync_handler(&block)
@@ -1293,6 +1318,31 @@ module Samagotchi
       def cwd = engine.session&.working_directory
       def state_dir = engine.peer_state_dir
       def cancelled? = !!engine.active_cancel_controller&.cancelled?
+      def relay = engine.relay_peer
+      def model_ref = engine.effective_model_ref
+    end
+
+    # What the approval relay needs from the parent's Engine (Peers#relay):
+    # its own question flow, which every UI attached to it answers.
+    RelayPeer = Struct.new(:engine) do
+      def open_question(fields, watch: nil) = engine.open_question(fields, watch: watch)
+      def interface = engine.interface
+      def relay_desk = engine.relay_desk
+    end
+
+    # This worker's relays of its delegates' approvals (memory only).
+    # @return [RelayDesk]
+    attr_reader :relay_desk
+
+    # The relay's view of this Engine, or nil when it can't host a relay: a
+    # worker's Engine only (its Bridge is what a child verifies against;
+    # --non-interactive has no one to ask), never with a REPL's sync
+    # handler (no wait loop, no watch).
+    # @return [RelayPeer, nil]
+    def relay_peer
+      return nil unless interface == :worker && !@question_desk.sync_handler?
+
+      RelayPeer.new(self)
     end
 
     # @return [String] the state dir holding this Engine's sessions
@@ -1692,17 +1742,15 @@ module Samagotchi
     # continue resumes from them rather than after a made-up reply.
     def kept_messages(turn, result, seconds)
       conversation = result.conversation if result.conversation.is_a?(Array)
-      # Nothing visible (the native loop: no text; the chat loop: its
-      # placeholder text) is a turn the model should know ended that way.
+      # Nothing visible (no text) is a turn the model should know ended
+      # that way: the note, and nothing made up as its answer. The note's
+      # marker is for the UIs (the notice, and the empty steps after a
+      # reload); it goes on the result's conversation too (the REPL keeps it).
+      # A retry's nudge at the tail goes: this note says it all.
       if result.empty_answer?
-        # The placeholder is for the UIs (a new array: it must not leak
-        # into the result); the note is for the model, so it goes on the
-        # result's conversation too.
-        # A retry's nudge at the tail goes: this note says it all.
-        note = TurnNote.empty
+        note = TurnNote.empty(retries: result.empty_retries, steps: result.empty_steps)
         conversation&.replace(TurnNote.without_trailing(conversation))
         saved = TurnNote.without_trailing(conversation || turn.session.messages)
-        saved << { role: "model", content: "[No response]" } if result.output.to_s.strip.empty?
         conversation << note if conversation
         saved + [note]
       elsif result.canceled? && conversation
@@ -1901,7 +1949,7 @@ module Samagotchi
     # @param result [LLM::ModelResult]
     # @return [Hash]
     def turn_summary(result)
-      {
+      summary = {
         output: result.output.to_s,
         exhausted: result.exhausted?,
         resumable: result.resumable?,
@@ -1909,6 +1957,9 @@ module Samagotchi
         tool_activity: Array(result.tool_activity).map(&:dup),
         context_status: result.context_status&.dup
       }
+      # No answer: every UI shows its notice (TurnNote.empty_answer_line).
+      summary[:empty_answer] = { retries: result.empty_retries.to_i } if result.empty_answer?
+      summary
     end
 
     # ── Session messages API ───────────────────────────────────────────────
@@ -2087,7 +2138,8 @@ module Samagotchi
         ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
           ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller)
         },
-        model_name: -> { @session&.model_name || @effective_model_name },
+        model_name: -> { effective_model_ref },
+        model_key: -> { @model_key },
         state_dir: -> { session_state_dir },
         scratch: -> { @scratch }
       )
@@ -2282,6 +2334,18 @@ module Samagotchi
       [nil, nil]
     end
 
+    # What a local native host's cached /props names, when it isn't the
+    # model asked for; nil for a chat or remote host, or before any probe.
+    def prompt_served_model(target)
+      entry = target.entry
+      return nil if entry.nil? || entry.chat? || entry.remote? || !target.client.respond_to?(:cached_server_props)
+
+      served = ServedModel.from_props(target.client.cached_server_props(model: target.bare_model))
+      served if ServedModel.differs?(target.bare_model, served)
+    rescue StandardError
+      nil
+    end
+
     # ── Prompt profile ─────────────────────────────────────────────────────────
 
     def resolve_profile

data/lib/samagotchi/kernel_loop.rb

@@ -219,7 +219,7 @@ module Samagotchi
     # the prefill, and what the caller gave.
     Turn = Struct.new(:conversation, :context, :empty_retry, :tool_activity, :buffer, :qwen_attempts, :qwen_partial,
                       :prefill, :pending_tool_calls, :model_name, :pending_input, :on_stream_event,
-                      :cancel_controller, :cap, :emit, :iteration, keyword_init: true)
+                      :cancel_controller, :cap, :emit, :iteration, :empty_steps, :ended_empty, keyword_init: true)
     # One request: the prompt and its images as sent, the images' token
     # estimate, and the window it was measured against.
     Request = Struct.new(:prompt, :images, :image_tokens, :window, keyword_init: true)
@@ -234,7 +234,7 @@ module Samagotchi
       conversation = prepare_conversation(messages)
       Turn.new(
         conversation: conversation, context: ContextStatus.new(conversation: conversation),
-        empty_retry: EmptyAnswerRetry.new, tool_activity: [], buffer: +"", qwen_attempts: 0, qwen_partial: nil,
+        empty_retry: EmptyAnswerRetry.new, empty_steps: [], tool_activity: [], buffer: +"", qwen_attempts: 0, qwen_partial: nil,
         # 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.
@@ -418,11 +418,18 @@ module Samagotchi
       # The empty generation goes (its thinking would be sent again and
       # prime the same loop); an empty answer that will be retried is no
       # answer site, so a plugin's steer joins the retry.
-      turn.conversation.pop if retry_empty
+      turn.empty_steps << turn.conversation.pop if retry_empty
       # Queued steering keeps the turn going: the model answers the
       # injected message instead of stopping here.
       return :next if inject_pending_input!(turn, answer: retry_empty ? nil : answer)
 
+      # The last one goes too: earlier thinking is stripped from the prompt,
+      # so it would be an empty assistant turn there. The UIs draw it from
+      # the result's empty_steps.
+      if empty && !retry_empty
+        turn.empty_steps << turn.conversation.pop
+        turn.ended_empty = true
+      end
       if retry_empty
         turn.empty_retry.nudge!(turn.conversation, TurnNote.empty_retry,
                                 emit: turn.emit, iteration: turn.iteration, finish_reason: generation.finish_reason,
@@ -452,7 +459,9 @@ module Samagotchi
     # then the answer shows only its text.
     def finish(turn)
       exhausted = turn.pending_tool_calls && tool_response_turn?(turn.conversation.last)
-      output = strip_thought_blocks(last_model_content(turn.conversation))
+      # An empty answer left the conversation: an earlier model message
+      # isn't this turn's answer.
+      output = turn.ended_empty ? "" : strip_thought_blocks(last_model_content(turn.conversation))
       output = parser.strip_tool_calls(output) if exhausted
       LLM::ModelResult.new(
         text: PromptLiteralGuard.restore(output, profile: @profile).to_s,
@@ -460,7 +469,9 @@ module Samagotchi
         exhausted: exhausted,
         pending_tool_calls: turn.pending_tool_calls,
         tool_activity: turn.tool_activity,
-        context_status: turn.context.display
+        context_status: turn.context.display,
+        empty_steps: turn.empty_steps,
+        empty_retries: turn.empty_retry.attempts
       )
     end
 

data/lib/samagotchi/llm/chat_loop.rb

@@ -195,8 +195,9 @@ module Samagotchi
       # reasoning, never sent back), a result's tool_call_id, the image
       # refs of a user message or a tool result, a prompt's turn_id (Engine,
       # never sent), and a plugin tool result's tool_params and tool_labels
-      # (the live row's params line and label, never sent back), and an
-      # edit/write result's tool_diffs (never sent).
+      # (the live row's params line and label, never sent back), an
+      # edit/write result's tool_diffs (never sent), and an empty-answer
+      # note's marker (TurnNote.empty, never sent).
       def plain(conversation)
         conversation.map do |entry|
           content = entry[:content].is_a?(Array) ? entry[:content] : entry[:content].to_s
@@ -208,6 +209,8 @@ module Samagotchi
           message[:thinking] = entry[:thinking] if entry[:thinking].is_a?(String) && !entry[:thinking].empty?
           ToolResponse::SAVED_KEYS.each { |key| message[key] = entry[key] if entry[key] }
           message[TurnNote::RETRY_NUDGE] = true if TurnNote.retry_nudge?(entry)
+          marker = TurnNote.empty_answer(entry)
+          message[TurnNote::EMPTY_ANSWER] = marker if marker
           message[AnswerDisplay::KEY] = entry[AnswerDisplay::KEY] if entry[AnswerDisplay::KEY]
           ContextNote::KEYS.each { |key| message[key] = entry[key] if entry.key?(key) }
           message
@@ -302,11 +305,12 @@ module Samagotchi
           @pending_input = pending_input
           @tool_activity = []
           @empty_retry = EmptyAnswerRetry.new
+          # The empty generations, never saved: the UIs draw the turn's
+          # steps from them (ModelResult#empty_steps).
+          @empty_steps = []
           @context = ContextStatus.new(conversation: conversation)
         end
 
-        EMPTY_ANSWER = "(the model returned an empty answer)"
-
         def call(max_iterations:, cap:)
           last_text = ""
           exhausted = true
@@ -340,11 +344,13 @@ module Samagotchi
               # plugin's steer joins the retry instead of being dropped, and
               # queued input (a user's line, a steer) goes in place of the nudge.
               next if inject_pending_input(iteration, answer: retry_empty ? nil : last_text)
+
+              # An empty answer (content "" + stop, seen from a remote host)
+              # ends the turn with no text: the UIs show their notice.
+              @empty_steps << with_thinking({ role: "model", content: "" }, response) if empty
               next if retry_empty && nudge_empty_answer(iteration, response)
 
-              # Shown, not saved: an empty answer (content "" + stop, seen from
-              # a remote host) would otherwise end the turn with nothing.
-              last_text = EMPTY_ANSWER if empty
+              last_text = "" if empty
               exhausted = false
               break
             end
@@ -573,7 +579,7 @@ module Samagotchi
 
         def result(text, exhausted:)
           ModelResult.new(text: text, conversation: @loop.plain(@conversation), exhausted: exhausted,
-                          tool_activity: @tool_activity, empty_answer: text == EMPTY_ANSWER,
+                          tool_activity: @tool_activity, empty_steps: @empty_steps, empty_retries: @empty_retry.attempts,
                           context_status: @context.display)
         end
 

data/lib/samagotchi/llm/model_result.rb

@@ -9,13 +9,19 @@ module Samagotchi
     # .canceled?, .cancellation_reason, .exhausted?, .resumable?,
     # .empty_answer?, plus the native loop's .tool_activity, .context_status
     # and .pending_tool_calls, which the interactive renderer needs.
+    #
+    # A turn with no answer also carries .empty_steps (its empty
+    # generations as model messages, which the loops keep out of the
+    # conversation) and .empty_retries (the retries spent): the Engine saves
+    # them on the turn's note for the UIs (TurnNote.empty).
     class ModelResult
       attr_reader :text, :conversation, :canceled, :cancellation_reason, :exhausted,
-                  :tool_activity, :context_status, :pending_tool_calls
+                  :tool_activity, :context_status, :pending_tool_calls, :empty_steps, :empty_retries
 
       def initialize(text:, conversation: nil, canceled: false, cancellation_reason: nil, exhausted: false,
-                     tool_activity: [], context_status: nil, pending_tool_calls: false, empty_answer: false)
-        @empty_answer = empty_answer
+                     tool_activity: [], context_status: nil, pending_tool_calls: false, empty_steps: [], empty_retries: 0)
+        @empty_steps = Array(empty_steps)
+        @empty_retries = empty_retries.to_i
         @text = text
         @conversation = conversation
         @canceled = canceled
@@ -35,13 +41,12 @@ module Samagotchi
         !!canceled
       end
 
-      # The turn ended with nothing visible: no text, or the chat loop's
-      # placeholder (empty_answer:). A cancelled turn or one that can be
-      # continued is not an empty answer.
+      # The turn ended with nothing visible (no text). A cancelled turn or
+      # one that can be continued is not an empty answer.
       def empty_answer?
         return false if canceled? || resumable?
 
-        !!@empty_answer || text.to_s.strip.empty?
+        text.to_s.strip.empty?
       end
 
       def exhausted?

data/lib/samagotchi/log_subscriber.rb

@@ -27,6 +27,7 @@ module Samagotchi
       question_requested: [],
       question_answered: %i[id],
       question_cancelled: %i[id reason],
+      question_relay: %i[id reason],
       generation_cancelled: %i[iteration],
       empty_answer_retry: %i[iteration attempt of finish_reason thinking_chars stopped_by]
     }.freeze

data/lib/samagotchi/memory_bundle/builder.rb

@@ -67,6 +67,8 @@ module Samagotchi
             raise BuildError, "Requested file(s) not found in #{@scope} scope: #{missing.join(', ')}"
           end
           candidates = allow.map { |k| candidates_by_basename[k] }
+        else
+          candidates = leave_out_owned(candidates, resolved_name)
         end
 
         # Compute checksums and detect placeholders
@@ -250,6 +252,26 @@ module Samagotchi
 
       private
 
+      # Without an allowlist, a memory another installed bundle owns (its
+      # record lists it) isn't the user's to share: left out, one line
+      # each. The bundle being built (same name) keeps its own.
+      def leave_out_owned(candidates, name)
+        require_relative "provenance"
+        owners = candidates.to_h do |path|
+          [path, Provenance.claimants(File.basename(path), scope: @scope, except: name)]
+        end
+        left_out = owners.reject { |_, names| names.empty? }
+        left_out.each do |path, names|
+          @warnings << "Left out #{File.basename(path)}: installed by bundle #{names.join(", ")} (name it to include it)"
+        end
+        kept = candidates - left_out.keys
+        if kept.empty?
+          raise BuildError, "No memories to build in #{@scope} scope: every one belongs to an installed bundle " \
+                            "(#{left_out.keys.map { |p| File.basename(p) }.join(", ")}); name the ones to include"
+        end
+        kept
+      end
+
       def normalize_scope(val)
         return nil if val.nil? || val.to_s.strip.empty?
         v = val.to_s.strip.downcase

data/lib/samagotchi/memory_bundle/index_updater.rb

@@ -10,18 +10,22 @@ module Samagotchi
     module IndexUpdater
       MEMORY_INDEX = "index"
       LOCK_FILE = ".index.lock"
-      def self.update_index(scope, entry_name, byte_count, description = nil)
+      # @param source [String, false, nil] the bundle the memory came from
+      #   ("· from <bundle>"): a name sets it, false drops it, nil keeps the
+      #   line's (memory_write and write/edit pass nil)
+      def self.update_index(scope, entry_name, byte_count, description = nil, source: nil)
         index_path = index_path_for(scope)
         return true unless index_path
         locked_write(File.dirname(index_path)) do |content|
-          new_line = managed_line(entry_name, scope, byte_count, description)
+          new_line = managed_line(entry_name, scope, byte_count, description, source || nil)
           next auto_index_header + "\n\n" + new_line + "\n" if content.nil? || content.strip.empty?
 
           pattern = managed_pattern(entry_name)
           if content.match?(pattern)
-            existing_desc = extract_description(content[pattern].to_s)
-            resolved_desc = description&.to_s&.strip || existing_desc
-            new_line = managed_line(entry_name, scope, byte_count, resolved_desc)
+            existing = content[pattern].to_s.chomp
+            resolved_desc = description&.to_s&.strip || extract_description(existing)
+            resolved_source = source.nil? ? extract_source(existing) : (source || nil)
+            new_line = managed_line(entry_name, scope, byte_count, resolved_desc, resolved_source)
             next content.sub(pattern) { new_line + $1 }
           end
           content.end_with?("\n") ? "#{content}#{new_line}\n" : "#{content}\n#{new_line}\n"
@@ -57,8 +61,9 @@ module Samagotchi
           Samagotchi::AtomicFile.write(index_path, updated) unless updated.nil?
         end
       end
-      def self.managed_line(name, scope, byte_count, description)
+      def self.managed_line(name, scope, byte_count, description, source = nil)
         line = "- **#{name}** · #{scope} · #{date_str} · #{byte_count}"
+        line += " · from #{source}" unless source.to_s.strip.empty?
         desc = description&.to_s&.strip
         line += " — #{desc}" unless desc.to_s.empty?
         line
@@ -70,6 +75,12 @@ module Samagotchi
           $1
         end
       end
+      # The bundle a managed line names ("· from <bundle>", before any
+      # " — description"), or nil.
+      def self.extract_source(line)
+        line.to_s.chomp.split(" — ", 2).first[/ · from (\S+)/, 1]
+      end
+
       def self.auto_index_header
         "# Memory Index\n\n" \
           "Managed entries below are auto-maintained by memory_write " \

data/lib/samagotchi/memory_bundle/installer.rb

@@ -9,6 +9,7 @@ require_relative "source"
 require_relative "placeholder"
 require_relative "index_updater"
 require_relative "merger"
+require_relative "trash"
 require_relative "../version"
 require_relative "../bundle_needs"
 
@@ -41,8 +42,13 @@ module Samagotchi
         @warnings = []
         @placeholder_warnings = []
         @conflicts = {}
+        @trash = Trash.new(name)
       end
 
+      # Where an upgrade moved the files the bundle no longer ships (nil:
+      # none moved).
+      def trash_dir = @trash.dir
+
       def run
         normalized_dir = nil
         source_owned = false
@@ -73,14 +79,24 @@ module Samagotchi
         existing_provenance = provenance.read
         # A plain install over an installed bundle: summary points at upgrade.
         @reinstall = existing_provenance && !@upgrade && !@force && !@dry_run
+        # The bundle owns (records, upgrades, removes) only the files it
+        # wrote: these, from an earlier install, and the ones written now.
+        # A same-name file that was already there is the user's: skipped
+        # and never recorded.
+        owned_before = existing_provenance && existing_provenance[:files].is_a?(Hash) ? existing_provenance[:files].keys.map(&:to_s) : []
+        owned = []
 
         Dir.glob(File.join(normalized_dir, "*.md")).each do |file_path|
           file_key = File.basename(file_path)
           all_files_in_bundle << file_key
           target_path = File.join(target_dir, file_key)
 
-          if @upgrade && existing_provenance && !@force && !@dry_run
+          if @upgrade && existing_provenance && !@force && File.exist?(target_path) && !owned_before.include?(file_key)
+            # Not the bundle's (the user's, or another bundle's): no merge.
+            skip_existing(file_key, file_path, target_path, target_scope)
+          elsif @upgrade && existing_provenance && !@force && !@dry_run
             # 3-way merge path for upgrades
+            owned << file_key
             base_path = provenance.base_path(file_key)
             classification = Merger.classify(base_path: base_path, current_path: target_path, incoming_path: file_path)
             case classification
@@ -120,16 +136,13 @@ module Samagotchi
             else
               @results[file_key] = { status: "would_install" }
             end
-          elsif File.exist?(target_path) && !@force && FileUtils.identical?(file_path, target_path)
-            @results[file_key] = { status: "skipped", reason: "already up to date" }
-            update_target_index(target_scope, target_path, file_key)
           elsif File.exist?(target_path) && !@force
-            @results[file_key] = { status: "skipped", reason: "already exists" }
-            @warnings << "Skipped #{file_key} (already exists; use --force to overwrite)"
-            # Still update the index for skipped files.
-            update_target_index(target_scope, target_path, file_key)
+            # A re-install keeps what an earlier install wrote.
+            owned << file_key if owned_before.include?(file_key)
+            skip_existing(file_key, file_path, target_path, target_scope, owned: owned_before.include?(file_key))
           else
             FileUtils.cp(file_path, target_path) unless @dry_run
+            owned << file_key
             @results[file_key] = { status: "installed" }
             # Update index for newly installed files.
             update_target_index(target_scope, target_path, file_key) unless @dry_run
@@ -302,7 +315,7 @@ module Samagotchi
         if manifest && !@dry_run
           provenance_files = {}
           if @upgrade && existing_provenance
-            all_files_in_bundle.each do |file_key|
+            owned.each do |file_key|
               target_path = File.join(target_dir, file_key)
               next unless File.exist?(target_path)
               status = @results[file_key] ? @results[file_key][:status].to_s : nil
@@ -338,7 +351,7 @@ module Samagotchi
               end
             end
           else
-            all_files_in_bundle.each do |file_key|
+            owned.each do |file_key|
               target_path = File.join(target_dir, file_key)
               next unless File.exist?(target_path)
 
@@ -408,7 +421,7 @@ module Samagotchi
         lines << "Updated: #{updated.join(', ')}" unless updated.empty?
         lines << "Would install: #{would_install.join(', ')}" unless would_install.empty?
         lines << "Fast-forward: #{fast_forward.join(', ')}" unless fast_forward.empty?
-        lines << "Removed (no longer in the bundle): #{removed.join(', ')}" unless removed.empty?
+        lines << "Removed (no longer in the bundle): #{removed.join(', ')}#{trash_dir ? " (moved to #{trash_dir})" : ""}" unless removed.empty?
         lines << "Would remove (no longer in the bundle): #{would_remove.join(', ')}" unless would_remove.empty?
         lines << "Kept (local edits preserved): #{kept.join(', ')}" unless kept.empty?
         lines << "Skipped: #{skipped.join(', ')}" unless skipped.empty?
@@ -422,9 +435,27 @@ module Samagotchi
 
       private
 
+      # A file already in the target dir that the install doesn't write: the
+      # same bytes are "already up to date", others are skipped with a
+      # --force hint (a dry run: would_skip). Its index line is refreshed
+      # (not on a dry run).
+      def skip_existing(file_key, file_path, target_path, scope, owned: false)
+        if FileUtils.identical?(file_path, target_path)
+          @results[file_key] = { status: "skipped", reason: "already up to date" }
+        elsif @dry_run
+          @results[file_key] = { status: "would_skip" }
+          return
+        else
+          @results[file_key] = { status: "skipped", reason: "already exists" }
+          @warnings << "Skipped #{file_key} (already exists; use --force to overwrite)"
+        end
+        update_target_index(scope, target_path, file_key, owned: owned) unless @dry_run
+      end
+
       # A file the previous version installed that this one doesn't ship is
-      # removed (with its index line) when it still matches what was
-      # installed, or with --force; one the user edited is kept with a note.
+      # moved to the trash (with its index line removed) when it still
+      # matches what was installed, or with --force; one the user edited is
+      # kept with a note.
       def prune_dropped_files(previous_files, bundle_files, target_dir, scope, provenance)
         previous_files.each do |old_key, meta|
           key = old_key.to_s
@@ -432,10 +463,14 @@ module Samagotchi
           target = File.join(target_dir, key)
           next unless File.exist?(target)
 
-          if @force || installed_unchanged?(target, meta, provenance.base_path(key))
+          others = Provenance.claimants(key, scope: scope, except: @name)
+          if others.any?
+            @results[key] = { status: "kept_shared", reason: "bundle #{others.join(", ")} has it too" }
+            @warnings << "Kept #{key}: no longer in the bundle, but bundle #{others.join(", ")} has it too"
+          elsif @force || installed_unchanged?(target, meta, provenance.base_path(key))
             @results[key] = { status: @dry_run ? "would_remove" : "removed", reason: "no longer in the bundle" }
             next if @dry_run
-            FileUtils.rm_f(target)
+            @trash.move(target)
             remove_target_index(scope, key)
           else
             @results[key] = { status: "kept_pruned", reason: "local edits preserved" }
@@ -452,11 +487,12 @@ module Samagotchi
         File.exist?(base_path) && Provenance.file_sha(target) == Provenance.file_sha(base_path)
       end
 
+      # Not fatal, like update_target_index: a warning says so.
       def remove_target_index(scope, file_key)
         IndexUpdater.remove_index(scope, file_key.delete_suffix(".md"))
         IndexUpdater.remove_index(scope, file_key) # legacy "name.md" line
-      rescue StandardError
-        # Best-effort, like update_target_index.
+      rescue StandardError => e
+        @warnings << "index.md: line for #{file_key.delete_suffix(".md")} not removed (#{e.message})"
       end
 
       # One warning per need not found on this PATH (read-only, so dry-run
@@ -514,16 +550,19 @@ module Samagotchi
         dest
       end
 
-      def update_target_index(scope, file_path, file_key)
+      # +owned+: the bundle wrote (owns) the file, so its line says
+      # "· from <bundle>"; a skipped file's line keeps whatever it had.
+      def update_target_index(scope, file_path, file_key, owned: true)
         byte_count = File.exist?(file_path) ? File.size(file_path) : 0
         entry_name = file_key.delete_suffix(".md")
         begin
           # Index lines use the entry name (as memory_write does); drop the
           # legacy "name.md" line older installs wrote.
           IndexUpdater.remove_index(scope, file_key) unless entry_name == file_key
-          IndexUpdater.update_index(scope, entry_name, byte_count)
-        rescue => _e
-          # Silently skip index updates — they're best-effort.
+          IndexUpdater.update_index(scope, entry_name, byte_count, source: owned ? @name : nil)
+        rescue StandardError => e
+          # Not fatal (the file is in place): a warning says so.
+          @warnings << "index.md: line for #{entry_name} not updated (#{e.message})"
         end
       end