samagotchi 0.3.0 → 0.5.0

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)
@@ -269,9 +283,26 @@ module Samagotchi
           return nil
         end
 
+        from_error_json(raw, host: host)
+      end
+
+      # The error a 200's whole body carries when it is a plain JSON error
+      # object instead of a stream (OpenRouter's "503 inside a 200":
+      # {"error":{"code":503,"message":"…"}}), or nil for anything else.
+      def from_error_body(body, host:)
+        parsed = parse_json(body.to_s)
+        return nil unless parsed.is_a?(Hash) && parsed.key?("error")
+
+        from_error_json(body.to_s, host: host)
+      end
+
+      # The ProviderError for a JSON error object, by its error.code (an HTTP
+      # status); 500 when it has none.
+      def from_error_json(raw, host:)
         parsed = parse_json(raw)
         error = parsed.is_a?(Hash) && parsed["error"].is_a?(Hash) ? parsed["error"] : parsed
         code = error.is_a?(Hash) ? error["code"] : nil
+        code = code.to_i if code.is_a?(String) && code.match?(/\A\d{3}\z/)
         status = code.is_a?(Integer) && code.between?(400, 599) ? code : 500
         from_response(status: status, body: raw, host: host)
       end

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
@@ -20,9 +21,6 @@ module Samagotchi
     # the listener falls back to raising RequestCancelled in the requesting
     # thread, as Client did before.
     class HTTP
-      RETRY_MAX_ENV = "SAMAGOTCHI_RETRY_MAX"
-      RETRY_BASE_DELAY_ENV = "SAMAGOTCHI_RETRY_BASE_DELAY"
-      RETRY_MAX_DELAY_ENV = "SAMAGOTCHI_RETRY_MAX_DELAY"
       DEFAULT_RETRY_MAX = 5
       DEFAULT_RETRY_BASE_DELAY = 0.5
       DEFAULT_RETRY_MAX_DELAY = 8.0
@@ -45,15 +43,14 @@ module Samagotchi
       # Exponential backoff: base_delay * 2^(attempt-1), capped at max_delay,
       # for up to +max+ retries (max + 1 attempts).
       RetryPolicy = Data.define(:max, :base_delay, :max_delay) do
-        # retry.* from config, then the SAMAGOTCHI_RETRY_* env, then defaults.
+        # retry.* (Config); a value out of range is the default.
         def self.from_config
           new(
-            max: config_value("retry.max") { |v| v.is_a?(Integer) && v >= 0 } ||
-              env_integer(RETRY_MAX_ENV, DEFAULT_RETRY_MAX),
+            max: config_value("retry.max") { |v| v.is_a?(Integer) && v >= 0 } || DEFAULT_RETRY_MAX,
             base_delay: config_value("retry.base_delay") { |v| v.is_a?(Numeric) && v.positive? }&.to_f ||
-              env_float(RETRY_BASE_DELAY_ENV, DEFAULT_RETRY_BASE_DELAY),
+              DEFAULT_RETRY_BASE_DELAY,
             max_delay: config_value("retry.max_delay") { |v| v.is_a?(Numeric) && v.positive? }&.to_f ||
-              env_float(RETRY_MAX_DELAY_ENV, DEFAULT_RETRY_MAX_DELAY)
+              DEFAULT_RETRY_MAX_DELAY
           )
         end
 
@@ -66,16 +63,6 @@ module Samagotchi
           nil
         end
 
-        def self.env_integer(name, default)
-          value = ENV.fetch(name, default.to_s).to_i
-          value.negative? ? default : value
-        end
-
-        def self.env_float(name, default)
-          value = ENV.fetch(name, default.to_s).to_f
-          value.positive? ? value : default
-        end
-
         # Seconds to wait before retrying after failed attempt +attempt+
         # (1-based), or nil when the budget is spent.
         def delay_for(attempt)
@@ -101,8 +88,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 +201,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 +382,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 +391,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

@@ -44,6 +44,8 @@ module Samagotchi
     # only; the chat loop owns the conversation and the tools.
     class OpenAIChat
       MAX_MODEL_PAGES = 20
+      # How much of a 200's non-stream body is read as a possible JSON error.
+      PLAIN_ERROR_LIMIT = 64 * 1024
       DEFAULT_MODELS_TTL = 60
 
       attr_reader :base_url, :host_name, :api_key_env, :models_ttl, :first_token_timeout
@@ -90,13 +92,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,
@@ -120,15 +122,18 @@ module Samagotchi
         assembly = Assembly.new
         events = 0
         other = +""
+        plain = +""
         # A retry streams the answer from the start again.
         restart = lambda do |**event|
           assembly = Assembly.new
+          plain = +""
           on_retry&.call(**event)
         end
         @http.stream_lines(URI(request.uri.to_s), request, cancel_controller: cancel_controller, on_retry: restart,
                                                            log_fields: log_fields) do |line, shown|
           events += 1 if line.start_with?("data:")
           other << line[0, 200] if !line.start_with?("data:") && other.length < 200
+          raise_plain_error(plain, line) if events.zero?
           payload = parse_line(line)
           next unless payload
 
@@ -184,20 +189,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,
@@ -263,6 +261,18 @@ module Samagotchi
 
       # The parsed payload of a `data:` line; nil for blank lines, comments
       # and [DONE]. Error events raise their ProviderError.
+      # A 200 whose body is a plain JSON error instead of a stream (OpenRouter
+      # sends an upstream 503 so): raised, from inside the stream so it is
+      # retried by its kind, once the lines so far parse as an error object.
+      def raise_plain_error(plain, line)
+        return if line.empty? || line.start_with?(":") || (plain.empty? && !line.start_with?("{"))
+        return if plain.bytesize > PLAIN_ERROR_LIMIT
+
+        plain << line << "\n"
+        error = ProviderErrors.from_error_body(plain, host: @host_name)
+        raise error if error
+      end
+
       def parse_line(line)
         error = HTTP.sse_error(line, host: @host_name)
         raise error if error
@@ -286,25 +296,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)