samagotchi 0.3.0 → 0.4.0

data/lib/samagotchi/llm/chat_loop.rb

@@ -17,6 +17,7 @@ require_relative "../vision_context"
 require_relative "../log"
 require_relative "../empty_answer_retry"
 require_relative "../turn_note"
+require_relative "../thinking"
 
 module Samagotchi
   module LLM
@@ -139,6 +140,34 @@ module Samagotchi
         @kernel.respond_to?(:sampling) ? @kernel.sampling || {} : {}
       end
 
+      # The turn's thinking level (the Engine sets it on the kernel).
+      def thinking
+        (@kernel.respond_to?(:thinking) && @kernel.thinking) || Thinking::DEFAULT
+      end
+
+      # The request fields the thinking level adds (Thinking.chat_fields);
+      # none for a model whose host refused them (#thinking_refused!).
+      def thinking_fields(model = nil)
+        return {} if model && (@thinking_refused ||= Set.new).include?(model)
+
+        Thinking.chat_fields(thinking)
+      end
+
+      # The host refused +model+'s thinking fields: leave them out from now on.
+      def thinking_refused!(model)
+        (@thinking_refused ||= Set.new) << model
+      end
+
+      # One generation's options: the thinking fields under the sampling
+      # (a sampling key wins, chat_template_kwargs merges per sub-key), the
+      # empty-answer retry's temperature on top, then every null dropped at
+      # any depth (a sampling null means "don't send it").
+      def request_options(retry_generation: false, model: nil)
+        options = deep_merge(thinking_fields(model), sampling)
+        options = EmptyAnswerRetry.sampling(options) if retry_generation
+        deep_compact(options)
+      end
+
       def strip_model_thought(text)
         @kernel.respond_to?(:strip_model_thought) ? @kernel.strip_model_thought(text) : text
       end
@@ -180,7 +209,7 @@ module Samagotchi
       # reasoning, never sent back), a result's tool_call_id, the image
       # refs of a user message or a tool result, and a plugin tool result's
       # tool_params and tool_labels (the live row's params line and label,
-      # never sent back).
+      # never sent back), and an edit/write result's tool_diffs (never sent).
       def plain(conversation)
         conversation.map do |entry|
           content = entry[:content].is_a?(Array) ? entry[:content] : entry[:content].to_s
@@ -191,6 +220,7 @@ module Samagotchi
           message[:thinking] = entry[:thinking] if entry[:thinking].is_a?(String) && !entry[:thinking].empty?
           message[:tool_params] = entry[:tool_params] if entry[:tool_params]
           message[:tool_labels] = entry[:tool_labels] if entry[:tool_labels]
+          message[:tool_diffs] = entry[:tool_diffs] if entry[:tool_diffs]
           message[AnswerDisplay::KEY] = entry[AnswerDisplay::KEY] if entry[AnswerDisplay::KEY]
           ContextNote::KEYS.each { |key| message[key] = entry[key] if entry.key?(key) }
           message
@@ -199,6 +229,18 @@ module Samagotchi
 
       private
 
+      def deep_merge(base, over)
+        base.merge(over) { |_key, a, b| a.is_a?(Hash) && b.is_a?(Hash) ? deep_merge(a, b) : b }
+      end
+
+      def deep_compact(hash)
+        hash.each_with_object({}) do |(key, value), out|
+          next if value.nil?
+
+          out[key] = value.is_a?(Hash) ? deep_compact(value) : value
+        end
+      end
+
       # Ids of the calls whose assistant turn is followed by a tool message
       # for every one of them (before the next non-tool message).
       def paired_call_ids(conversation)
@@ -364,23 +406,22 @@ module Samagotchi
         # text] when it was cancelled.
         def generate(iteration)
           window = @window = @loop.context_window(@model_name)
-          options = @loop.sampling
-          options = EmptyAnswerRetry.sampling(options) if @retry_generation
+          retry_generation = @retry_generation
           @retry_generation = false
           emit(type: :generation_started, iteration: iteration, context_window_tokens: window&.tokens,
                context_window_source: window&.source)
           @loop.fire_hook(:before_generation, { type: :before_generation, iteration: iteration })
           streamed = +""
-          response = @loop.adapter.chat(
-            messages: @loop.wire_messages(@conversation), tools: @loop.tool_definitions, model: @model_name,
-            cancel_controller: @cancel_controller, session_id: @loop.session_id, options: options,
-            on_delta: lambda { |content:, reasoning:, payload:|
-              streamed << content
-              emit(type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
-                   thinking: reasoning, payload: payload)
-            },
-            on_retry: ->(**retry_event) { emit({ type: :generation_retrying, iteration: iteration }.merge(retry_event)) }
-          )
+          response = begin
+            request(iteration, retry_generation, streamed)
+          rescue BadRequest => e
+            raise unless thinking_refused?(e)
+
+            # Once per model: asked again without the thinking fields.
+            @loop.thinking_refused!(@model_name)
+            emit(type: :thinking_refused, iteration: iteration, model: @model_name, level: @loop.thinking, detail: e.detail)
+            request(iteration, retry_generation, streamed)
+          end
           record_context_status(response.usage, window)
           emit(type: :generation_completed, iteration: iteration, content_length: response.text.length,
                thinking_chars: response.reasoning.to_s.length, served_model: response.model,
@@ -393,6 +434,27 @@ module Samagotchi
           [e.reason, streamed]
         end
 
+        def request(iteration, retry_generation, streamed)
+          @loop.adapter.chat(
+            messages: @loop.wire_messages(@conversation), tools: @loop.tool_definitions, model: @model_name,
+            cancel_controller: @cancel_controller, session_id: @loop.session_id,
+            options: @loop.request_options(retry_generation: retry_generation, model: @model_name),
+            on_delta: lambda { |content:, reasoning:, payload:|
+              streamed << content
+              emit(type: :generation_chunk, iteration: iteration, content: reasoning + content, text: content,
+                   thinking: reasoning, payload: payload)
+            },
+            on_retry: ->(**retry_event) { emit({ type: :generation_retrying, iteration: iteration }.merge(retry_event)) }
+          )
+        end
+
+        # A 400 about reasoning, for a request that carried thinking fields
+        # (not a missing-tools, image or context error).
+        def thinking_refused?(error)
+          error.reasoning_refused? && !error.is_a?(VisionUnsupported) && !error.tools_unsupported? &&
+            !error.context_overflow? && !@loop.thinking_fields(@model_name).empty?
+        end
+
         # The status line's value from the server's counts for this request
         # (prompt + answer); without them the last value stays.
         def record_context_status(usage, window)
@@ -429,6 +491,8 @@ module Samagotchi
             # A plugin tool's params line, for the web's reload; never sent.
             entry[:tool_params] = run[:shown_params] if run[:shown_params]
             entry[:tool_labels] = run[:shown_label] if run[:shown_label]
+            # What an edit/write changed, for the web's reload; never sent.
+            entry[:tool_diffs] = run[:diff] if run[:diff]
             @conversation << entry
           end
           emit(type: :tool_dispatch_completed, iteration: iteration, call_count: tool_calls.length)

data/lib/samagotchi/llm/errors.rb

@@ -52,14 +52,14 @@ module Samagotchi
       # One line for the UIs, e.g. "auth failed for host fw: set FW_KEY".
       def summary = "error from host #{host}: #{detail}"
 
-      private
-
-      def default_retryable? = false
-
       # The message without its leading "host: ".
       def detail
         host && message.start_with?("#{host}: ") ? message.delete_prefix("#{host}: ") : message
       end
+
+      private
+
+      def default_retryable? = false
     end
 
     class ConnectionError < ProviderError
@@ -91,18 +91,23 @@ module Samagotchi
     end
 
     class AuthError < ProviderError
+      # What to try (LLM::ApiKey), added to the summary.
+      attr_accessor :hint
+
       def kind = :auth
 
-      def summary = "auth failed for host #{host}: #{detail}"
+      def summary = "auth failed for host #{host}: #{detail}#{"; #{hint}" if hint}"
     end
 
     class BadRequest < ProviderError
       TOOLS_HINT = "this model can't use tools, and chi needs them: pick another model (/model) or host"
 
       # @param hint [String, nil] what to try, added to the summary
-      def initialize(message = nil, context_overflow: false, tools_unsupported: false, hint: nil, **options)
+      def initialize(message = nil, context_overflow: false, tools_unsupported: false, reasoning_refused: false, hint: nil,
+                     **options)
         @context_overflow = context_overflow
         @tools_unsupported = tools_unsupported
+        @reasoning_refused = reasoning_refused
         @hint = hint
         super(message, **options)
       end
@@ -116,6 +121,10 @@ module Samagotchi
       # and chi always sends them.
       def tools_unsupported? = @tools_unsupported
 
+      # A 400 about reasoning or thinking: the request's thinking fields may
+      # be what the host refuses (gpt-oss: "Reasoning is mandatory").
+      def reasoning_refused? = @reasoning_refused
+
       def kind = :bad_request
 
       def summary
@@ -227,6 +236,8 @@ module Samagotchi
       TOOLS_UNSUPPORTED_RE = /support tool use|(does not|doesn't) support tools|tool choice requires --enable-auto-tool-choice/i
       # A model or server that can't take images (see VisionUnsupported).
       VISION_UNSUPPORTED_RE = /support image input|image input is not supported|mmproj/i
+      # A 400 about the thinking fields chi sent (Thinking.chat_fields).
+      REASONING_REFUSED_RE = /reasoning|thinking/i
       RETRYABLE_SERVER_STATUSES = [500, 502, 503, 504, 529].freeze
 
       module_function
@@ -248,7 +259,10 @@ module Samagotchi
         when 401, 403 then AuthError.new(text, **options)
         when 429 then RateLimited.new(text, retry_after: parse_retry_after(retry_after), **options)
         when 408 then ServerError.new(text, retryable: true, **options)
-        when 400..499 then BadRequest.new(text, tools_unsupported: TOOLS_UNSUPPORTED_RE.match?(message), **options)
+        when 400..499
+          tools = TOOLS_UNSUPPORTED_RE.match?(message)
+          BadRequest.new(text, tools_unsupported: tools,
+                               reasoning_refused: status == 400 && !tools && REASONING_REFUSED_RE.match?(message), **options)
         when 500..599
           ServerError.new(text, retryable: RETRYABLE_SERVER_STATUSES.include?(status),
                                 retry_after: parse_retry_after(retry_after), **options)

data/lib/samagotchi/llm/http.rb

@@ -6,6 +6,7 @@ require_relative "../config"
 require_relative "../version"
 require_relative "../log"
 require_relative "errors"
+require_relative "api_key"
 
 module Samagotchi
   module LLM
@@ -101,8 +102,12 @@ module Samagotchi
       # @param sleeper [#call] waits the given seconds (specs pass a no-op)
       # @param first_token_timeout [Numeric, nil] seconds a stream may take to
       #   show something (see #stream_lines); nil: no limit
-      def initialize(label:, open_timeout:, read_timeout:, retry_policy: nil, sleeper: nil, first_token_timeout: nil)
+      # @param api_key [ApiKey, nil] sent on every request; nil: no
+      #   Authorization header (a local server)
+      def initialize(label:, open_timeout:, read_timeout:, retry_policy: nil, sleeper: nil, first_token_timeout: nil,
+                     api_key: nil)
         @label = label
+        @api_key = api_key
         @open_timeout = open_timeout
         @read_timeout = read_timeout
         @first_token_timeout = first_token_timeout&.positive? ? first_token_timeout : nil
@@ -210,8 +215,11 @@ module Samagotchi
 
       private
 
+      # User-Agent, and the host's key when it has one (AuthError, before
+      # any request, when its variable is not set).
       def identify(request)
         request["User-Agent"] = Samagotchi::USER_AGENT
+        @api_key&.authorize(request)
       end
 
       def start(uri, open_timeout: nil, read_timeout: nil, max_retries: nil, &block)
@@ -388,7 +396,8 @@ module Samagotchi
                                  status: error.is_a?(ProviderError) ? error.status : nil, error: error.class.name,
                                  msg: error.message.to_s[0, 300])
         on_retry&.call(attempt: attempts, max_retries: @retry_policy.max, next_delay: delay,
-                       error_class: error.class.name, error_message: error.message)
+                       error_class: error.class.name, error_message: error.message,
+                       status: error.is_a?(ProviderError) ? error.status : nil)
         wait(delay, cancel_controller)
       end
 
@@ -396,8 +405,10 @@ module Samagotchi
         status = response.code.to_i
         return if status.between?(200, 299)
 
-        raise ProviderErrors.from_response(status: status, body: response.body.to_s, host: @label,
-                                           retry_after: response["Retry-After"])
+        error = ProviderErrors.from_response(status: status, body: response.body.to_s, host: @label,
+                                             retry_after: response["Retry-After"])
+        error.hint ||= @api_key ? @api_key.hint : ApiKey.missing_hint(@label) if error.is_a?(AuthError)
+        raise error
       end
 
       def abort_request(current, requesting_thread, reason)

data/lib/samagotchi/llm/openai_chat.rb

@@ -90,13 +90,13 @@ module Samagotchi
         @host_name = host_name.to_s
         @api_key_env = api_key_env
         @stream = stream
-        @env = env
         @models_ttl = models_ttl
         @models_mutex = Mutex.new
         open_timeout, read_timeout = timeouts(timeout)
         policy = retry_policy || (retries ? nil : HTTP::RetryPolicy.none)
         @http = HTTP.new(label: @host_name, open_timeout: open_timeout, read_timeout: read_timeout,
-                         retry_policy: policy, sleeper: sleeper, first_token_timeout: first_token_timeout)
+                         retry_policy: policy, sleeper: sleeper, first_token_timeout: first_token_timeout,
+                         api_key: ApiKey.for(api_key_env, host: @host_name, env: env))
       end
 
       # @param messages [Array<Hash>] wire messages (role, content, tool_calls,
@@ -184,20 +184,13 @@ module Samagotchi
       private
 
       def timeouts(timeout)
-        open_timeout = config_integer("server.open_timeout", 10)
-        read_timeout = config_integer("server.read_timeout", 600)
+        open_timeout = Samagotchi::Config.positive_seconds("server.open_timeout")
+        read_timeout = Samagotchi::Config.positive_seconds("server.read_timeout")
         return [open_timeout, read_timeout] unless timeout
 
         [[open_timeout, timeout].min, timeout]
       end
 
-      def config_integer(key, default)
-        value = Samagotchi::Config.get(key).to_i
-        value.positive? ? value : default
-      rescue StandardError
-        default
-      end
-
       def request_body(messages, tools, model, options)
         body = {
           model: model,
@@ -286,25 +279,11 @@ module Samagotchi
         Net::HTTP::Post.new(uri).tap do |request|
           request["Content-Type"] = "application/json"
           request["Session-Id"] = session_id.to_s unless session_id.to_s.empty?
-          authorize(request)
           request.body = JSON.generate(body)
         end
       end
 
-      def get_request(uri)
-        Net::HTTP::Get.new(uri).tap { |request| authorize(request) }
-      end
-
-      def authorize(request)
-        return unless @api_key_env
-
-        key = @env[@api_key_env].to_s
-        if key.strip.empty?
-          raise AuthError.new("#{@host_name}: set #{@api_key_env} (the API key for host #{@host_name})",
-                              host: @host_name)
-        end
-        request["Authorization"] = "Bearer #{key}"
-      end
+      def get_request(uri) = Net::HTTP::Get.new(uri)
 
       def model_entries(body)
         return [] unless body.is_a?(Hash)

data/lib/samagotchi/memory_bundle/installer.rb

@@ -295,79 +295,81 @@ module Samagotchi
 
         warn_missing_needs(manifest) if manifest
 
-        # Write provenance (only if we had a manifest and not dry_run).
+        # Write provenance (only if we had a manifest and not dry_run). An
+        # upgrade with conflicts writes it too: the new version, the plugin's
+        # and hooks' new shas, and the old base for each conflicted file,
+        # marked conflict (chi bundle status shows it). Skipping it left the
+        # replaced plugin failing its sha check.
         if manifest && !@dry_run
-          skip_provenance = @upgrade && @conflicts.any? && !@force
-          unless skip_provenance
-            provenance_files = {}
-            if @upgrade && existing_provenance
-              all_files_in_bundle.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
-                if %w[kept noop conflict kept_pruned].include?(status)
-                  # Keep old base snapshot — do not overwrite with edited current
-                  # Use base snapshot as source if it exists to preserve old checksum
-                  base_path = provenance.base_path(file_key)
-                  if File.exist?(base_path)
-                    # Keep existing provenance entry by re-using base content
-                    # We still need to include it to prevent pruning, but with base content
-                    provenance_files[file_key] = base_path
-                  else
-                    provenance_files[file_key] = target_path
-                  end
+          provenance_files = {}
+          if @upgrade && existing_provenance
+            all_files_in_bundle.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
+              if %w[kept noop conflict kept_pruned].include?(status)
+                # Keep old base snapshot — do not overwrite with edited current
+                # Use base snapshot as source if it exists to preserve old checksum
+                base_path = provenance.base_path(file_key)
+                if File.exist?(base_path)
+                  # Keep existing provenance entry by re-using base content
+                  # We still need to include it to prevent pruning, but with base content
+                  provenance_files[file_key] = base_path
                 else
-                  # installed, updated, skipped — use current target (which is incoming for updated)
                   provenance_files[file_key] = target_path
                 end
+              else
+                # installed, updated, skipped — use current target (which is incoming for updated)
+                provenance_files[file_key] = target_path
               end
-              # Handle pruned but kept files (bundle removed file but local kept)
-              if existing_provenance[:files]
-                existing_provenance[:files].keys.each do |old_key|
-                  old_key_str = old_key.to_s
-                  next if all_files_in_bundle.include?(old_key_str)
-                  # If it was kept_pruned, include it with base content to prevent pruning
-                  if @results[old_key_str] && @results[old_key_str][:status].to_s == "kept_pruned"
-                    base_path = provenance.base_path(old_key_str)
-                    target_path = File.join(target_dir, old_key_str)
-                    # Use base if exists to keep old checksum, else target
-                    src = File.exist?(base_path) ? base_path : target_path
-                    provenance_files[old_key_str] = src if File.exist?(src)
-                  end
+            end
+            # Handle pruned but kept files (bundle removed file but local kept)
+            if existing_provenance[:files]
+              existing_provenance[:files].keys.each do |old_key|
+                old_key_str = old_key.to_s
+                next if all_files_in_bundle.include?(old_key_str)
+                # If it was kept_pruned, include it with base content to prevent pruning
+                if @results[old_key_str] && @results[old_key_str][:status].to_s == "kept_pruned"
+                  base_path = provenance.base_path(old_key_str)
+                  target_path = File.join(target_dir, old_key_str)
+                  # Use base if exists to keep old checksum, else target
+                  src = File.exist?(base_path) ? base_path : target_path
+                  provenance_files[old_key_str] = src if File.exist?(src)
                 end
               end
-            else
-              all_files_in_bundle.each do |file_key|
-                target_path = File.join(target_dir, file_key)
-                provenance_files[file_key] = target_path if File.exist?(target_path)
-              end
             end
-            # Build hooks metadata for provenance
-            hooks_for_provenance = {}
-            if manifest && manifest.hooks && !manifest.hooks.empty?
-              hooks_for_provenance = manifest.hooks
-            elsif hooks_files_for_provenance.any?
-              hooks_files_for_provenance.each do |basename, path|
-                next unless File.exist?(path)
-                sha = Digest::SHA256.hexdigest(File.read(path))
-                hooks_for_provenance[basename] = { "sha256" => "sha256:#{sha}", "event" => "", "on_error" => "skip", "priority" => 100 }
-              end
+          else
+            all_files_in_bundle.each do |file_key|
+              target_path = File.join(target_dir, file_key)
+              provenance_files[file_key] = target_path if File.exist?(target_path)
+            end
+          end
+          # Build hooks metadata for provenance
+          hooks_for_provenance = {}
+          if manifest && manifest.hooks && !manifest.hooks.empty?
+            hooks_for_provenance = manifest.hooks
+          elsif hooks_files_for_provenance.any?
+            hooks_files_for_provenance.each do |basename, path|
+              next unless File.exist?(path)
+              sha = Digest::SHA256.hexdigest(File.read(path))
+              hooks_for_provenance[basename] = { "sha256" => "sha256:#{sha}", "event" => "", "on_error" => "skip", "priority" => 100 }
             end
-            Provenance.new(name: @name).write(
-              files: provenance_files,
-              scope: target_scope,
-              version: manifest.version,
-              source_path: @source,
-              hooks: hooks_for_provenance,
-              trust_level: manifest.respond_to?(:trust_level) ? manifest.trust_level : nil,
-              source_commit: source_commit,
-              hooks_files: hooks_files_for_provenance,
-              guardrails_files: guardrail_files_for_provenance,
-              plugin_file: plugin_file_for_provenance,
-              requires_chi: manifest.requires_chi,
-              needs: manifest.needs
-            )
           end
+          Provenance.new(name: @name).write(
+            files: provenance_files,
+            scope: target_scope,
+            version: manifest.version,
+            source_path: @source,
+            hooks: hooks_for_provenance,
+            trust_level: manifest.respond_to?(:trust_level) ? manifest.trust_level : nil,
+            source_commit: source_commit,
+            hooks_files: hooks_files_for_provenance,
+            guardrails_files: guardrail_files_for_provenance,
+            plugin_file: plugin_file_for_provenance,
+            requires_chi: manifest.requires_chi,
+            needs: manifest.needs,
+            conflicts: @conflicts.keys
+          )
         end
 
         # Detect placeholders.

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -94,14 +94,23 @@ module Samagotchi
         end
       end
 
+      # Yields [name, data] for each installed bundle with hooks, by name.
+      # A manifest that doesn't parse is yielded as {error:} when its
+      # bundle has a hooks/ dir, and skipped otherwise; the rest still load.
       def self.each_installed_holding_hooks
         return enum_for(:each_installed_holding_hooks) unless block_given?
         dir = self.bundles_dir
         return unless Dir.exist?(dir)
         Dir[File.join(dir, "*", "manifest.json")].sort.each do |mjson|
-          data = JSON.parse(File.read(mjson), symbolize_names: true)
-          next unless data && data[:hooks].is_a?(Hash) && !data[:hooks].empty?
-          yield File.basename(File.dirname(mjson)), data
+          name = File.basename(File.dirname(mjson))
+          begin
+            data = JSON.parse(File.read(mjson), symbolize_names: true)
+          rescue JSON::ParserError, SystemCallError => e
+            yield name, { error: "manifest.json is unreadable: #{e.message}" } if Dir.exist?(File.join(File.dirname(mjson), "hooks"))
+            next
+          end
+          next unless data.is_a?(Hash) && data[:hooks].is_a?(Hash) && !data[:hooks].empty?
+          yield name, data
         end
       end
 
@@ -116,8 +125,10 @@ module Samagotchi
       #   snapshot
       # @param requires_chi [String, nil] the manifest's requirement
       # @param needs [Array<Hash>] the manifest's needs ({command:, why:, hint:})
+      # @param conflicts [Array<String>] files an upgrade kept with local
+      #   edits that conflict with it; their entries get conflict: true
       def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
-                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil)
+                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [])
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -134,6 +145,7 @@ module Samagotchi
           # Save base snapshot — use file_key as-is (it already includes .md).
           File.write(File.join(bases_dir, file_key), content)
           merged_entries[file_key] = { checksum: checksum }
+          merged_entries[file_key][:conflict] = true if conflicts.include?(file_key.to_s)
         end
 
         # Prune stale base snapshots for files no longer in the bundle.
@@ -226,14 +238,29 @@ module Samagotchi
         manifest_data["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
         manifest_data["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } if needs.is_a?(Array) && !needs.empty?
 
-        # Write aside and rename, so a reader in another process (a parallel
-        # chi start) never parses a truncated manifest.json.
-        manifest_path = File.join(@bundle_dir, "manifest.json")
-        tmp_path = "#{manifest_path}.#{Process.pid}.tmp"
-        File.write(tmp_path, JSON.pretty_generate(manifest_data))
-        File.rename(tmp_path, manifest_path)
-      ensure
-        FileUtils.rm_f(tmp_path) if tmp_path
+        write_manifest(manifest_data)
+      end
+
+      # After a conflict was resolved by hand: each file's base becomes the
+      # bundle's version (the incoming file, else what's on disk now) and
+      # its conflict mark goes. The rest of the manifest stays as is.
+      # @param conflicts [Hash{String => Hash}] Installer#conflicts
+      def resolve_conflicts(conflicts)
+        return unless installed?
+
+        raw = JSON.parse(File.read(File.join(@bundle_dir, "manifest.json")))
+        raw["files"] ||= {}
+        conflicts.each do |file_key, info|
+          key = file_key.to_s
+          next unless raw["files"].key?(key)
+          src = [info[:incoming], info[:current]].find { |p| p && File.exist?(p) }
+          next unless src
+
+          content = File.read(src)
+          File.write(base_path(key), content)
+          raw["files"][key] = { "checksum" => Digest::SHA256.hexdigest(content) }
+        end
+        write_manifest(raw)
       end
 
       # Reads provenance data (returns nil if not installed).
@@ -243,6 +270,18 @@ module Samagotchi
         JSON.parse(File.read(manifest_path), symbolize_names: true)
       end
 
+      # Write aside and rename, so a reader in another process (a parallel
+      # chi start) never parses a truncated manifest.json.
+      def write_manifest(manifest_data)
+        manifest_path = File.join(@bundle_dir, "manifest.json")
+        tmp_path = "#{manifest_path}.#{Process.pid}.tmp"
+        File.write(tmp_path, JSON.pretty_generate(manifest_data))
+        File.rename(tmp_path, manifest_path)
+      ensure
+        FileUtils.rm_f(tmp_path) if tmp_path
+      end
+      private :write_manifest
+
       # Returns the path to a base snapshot for a given file key.
       def base_path(file_key)
         File.join(@bundle_dir, "bases", file_key)