samagotchi 0.21.0 → 0.23.0

data/lib/samagotchi/llm/errors.rb

@@ -22,6 +22,9 @@ module Samagotchi
     #   ConnectionError  no answer (refused, reset, timeout); RetryExhausted,
     #                    ConnectionRefused
     #   RateLimited      429, with retry_after when the server says
+    #   CreditsHeld      402 "… in-flight requests": credit reserved by other
+    #                    requests; a RateLimited, retried after 20 s
+    #   OutOfCredits     any other 402; never retried
     #   ServerError      5xx or a server's error event mid-stream
     #   AuthError        401/403, or an API key variable that is not set
     #   BadRequest       other 4xx (a context overflow is one, whatever status;
@@ -84,6 +87,24 @@ module Samagotchi
       def default_retryable? = true
     end
 
+    # A 402 that says the account's credit is reserved by requests still in
+    # flight (OpenRouter: "This request would exceed your available credits
+    # given your current in-flight requests"): it clears once they settle,
+    # so it is retried like a 429, after CREDITS_SETTLE_DELAY unless the
+    # server says how long.
+    class CreditsHeld < RateLimited
+      def kind = :credits_held
+
+      def summary = "credits on host #{host} are held by in-flight requests (retry after #{retry_after.to_f.ceil}s)"
+    end
+
+    # Any other 402: the account has run out of credits. Never retried.
+    class OutOfCredits < ProviderError
+      def kind = :credits
+
+      def summary = "out of credits on host #{host}: #{detail}; add credits, then send again"
+    end
+
     class ServerError < ProviderError
       def kind = :server
 
@@ -104,12 +125,12 @@ module Samagotchi
 
       # @param hint [String, nil] what to try, added to the summary
       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)
+        super(message, **)
       end
 
       attr_reader :hint
@@ -238,6 +259,10 @@ module Samagotchi
       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
+      # A 402 about credit held by in-flight requests (see CreditsHeld).
+      CREDITS_HELD_RE = /in-flight requests/i
+      # Seconds to wait before retrying a CreditsHeld without a Retry-After.
+      CREDITS_SETTLE_DELAY = 20.0
       RETRYABLE_SERVER_STATUSES = [500, 502, 503, 504, 529].freeze
 
       module_function
@@ -259,6 +284,12 @@ 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 402
+          if CREDITS_HELD_RE.match?(message) || CREDITS_HELD_RE.match?(body.to_s)
+            CreditsHeld.new(text, retry_after: parse_retry_after(retry_after) || CREDITS_SETTLE_DELAY, **options)
+          else
+            OutOfCredits.new(text, **options)
+          end
         when 400..499
           tools = TOOLS_UNSUPPORTED_RE.match?(message)
           BadRequest.new(text, tools_unsupported: tools,

data/lib/samagotchi/llm/http.rb

@@ -138,7 +138,7 @@ module Samagotchi
         end
       end
 
-      def stream_attempt(uri, request, current, &on_line)
+      def stream_attempt(uri, request, current, &)
         # Time to first token is the answering attempt's, not the retries'.
         current[:attempt_started_at] = monotonic_now
         shown = lambda do
@@ -155,11 +155,11 @@ module Samagotchi
               response.read_body do |chunk|
                 buffer << chunk
                 while (newline_index = buffer.index("\n"))
-                  on_line.call(buffer.slice!(0, newline_index + 1).strip, shown)
+                  yield(buffer.slice!(0, newline_index + 1).strip, shown)
                 end
               end
               # A body that doesn't end in a newline still has a last line.
-              on_line.call(buffer.strip, shown) unless buffer.strip.empty?
+              yield(buffer.strip, shown) unless buffer.strip.empty?
             end
           end
         end
@@ -192,7 +192,7 @@ module Samagotchi
           cancellable(cancel_controller, current) do
             attempt.call(current.merge!(attempts: 1))
           rescue StandardError => e
-            raise RequestCancelled.new(cancel_controller.reason) if !e.is_a?(RequestCancelled) && cancel_controller&.cancelled?
+            raise RequestCancelled, cancel_controller.reason if !e.is_a?(RequestCancelled) && cancel_controller&.cancelled?
 
             raise
           end
@@ -208,7 +208,7 @@ module Samagotchi
         @api_key&.authorize(request)
       end
 
-      def start(uri, open_timeout: nil, read_timeout: nil, max_retries: nil, &block)
+      def start(uri, open_timeout: nil, read_timeout: nil, max_retries: nil, &)
         options = { open_timeout: open_timeout || @open_timeout, read_timeout: read_timeout || @read_timeout }
         # Net::HTTP retries an idempotent request once on its own (max_retries
         # defaults to 1) when the connection drops before an answer: chi's
@@ -218,15 +218,15 @@ module Samagotchi
         retries = max_retries || 0
         options[:max_retries] = retries
         options[:use_ssl] = true if uri.scheme == "https"
-        Net::HTTP.start(uri.host, uri.port, **options, &block)
+        Net::HTTP.start(uri.host, uri.port, **options, &)
       end
 
       # Runs the block (one attempt) until it returns, retrying network
       # errors. The block gets a hash to put the attempt's Net::HTTP in, so a
       # cancel can reach its socket.
-      def with_retries(cancel_controller, on_retry, on_network_error, current = { mutex: Mutex.new })
+      def with_retries(cancel_controller, on_retry, on_network_error, current = { mutex: Mutex.new }, &block)
         cancellable(cancel_controller, current) do
-          retrying(cancel_controller, on_retry, on_network_error, current) { |state| yield(state) }
+          retrying(cancel_controller, on_retry, on_network_error, current, &block)
         end
       end
 
@@ -236,7 +236,7 @@ module Samagotchi
       def cancellable(cancel_controller, current)
         requesting_thread = Thread.current
         listener_id = cancel_controller&.on_cancel { |reason| abort_request(current, requesting_thread, reason) }
-        raise RequestCancelled.new(cancel_controller.reason) if cancel_controller&.cancelled?
+        raise RequestCancelled, cancel_controller.reason if cancel_controller&.cancelled?
 
         yield
       ensure
@@ -257,7 +257,7 @@ module Samagotchi
           rescue RequestCancelled
             raise
           rescue ProviderError => e
-            raise RequestCancelled.new(cancel_controller.reason) if cancel_controller&.cancelled?
+            raise RequestCancelled, cancel_controller.reason if cancel_controller&.cancelled?
 
             e.attempts = attempts
             raise if !e.retryable? || current[:streamed]
@@ -267,7 +267,7 @@ module Samagotchi
 
             retry_after(e, attempts, delay, on_retry, cancel_controller, current)
           rescue StandardError => e
-            raise RequestCancelled.new(cancel_controller.reason) if cancel_controller&.cancelled?
+            raise RequestCancelled, cancel_controller.reason if cancel_controller&.cancelled?
             raise first_token_timeout if current[:first_token_expired]
             raise unless self.class.network_error?(e)
 
@@ -432,7 +432,7 @@ module Samagotchi
 
         remaining = seconds
         while remaining.positive?
-          raise RequestCancelled.new(cancel_controller.reason) if cancel_controller.cancelled?
+          raise RequestCancelled, cancel_controller.reason if cancel_controller.cancelled?
 
           slice = [remaining, WAIT_TICK].min
           @sleeper.call(slice)

data/lib/samagotchi/llm/openai_chat.rb

@@ -6,6 +6,7 @@ require_relative "../config"
 require_relative "../sampling_settings"
 require_relative "errors"
 require_relative "http"
+require_relative "prompt_cache"
 require_relative "usage"
 require_relative "utf8_scrub"
 
@@ -52,13 +53,28 @@ module Samagotchi
       # 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
+      # OpenRouter holds a paid request's estimated cost against the balance
+      # while it runs: the input plus the output max_tokens allows (a fixed
+      # per-request cap when it is unset), and refuses a request with a 402
+      # once the running ones fill the budget. A request that names a sane
+      # limit holds less. 32k leaves room for any one step's answer.
+      OPENROUTER_MAX_TOKENS = 32_768
 
-      attr_reader :base_url, :host_name, :api_key_env, :models_ttl, :first_token_timeout
+      attr_reader :base_url, :host_name, :api_key_env, :models_ttl, :first_token_timeout, :default_max_tokens
 
       # @param entry [HostRegistry::HostEntry]
-      def self.for(entry, **options)
+      def self.for(entry, **)
         new(base_url: entry.openai_base_url, host_name: entry.name, api_key_env: entry.api_key_env,
-            remote: entry.remote?, **options)
+            remote: entry.remote?, default_max_tokens: (OPENROUTER_MAX_TOKENS if openrouter?(entry.openai_base_url)),
+            **)
+      end
+
+      # true when +url+ is OpenRouter's API (openrouter.ai or a subdomain).
+      def self.openrouter?(url)
+        host = URI(url.to_s).host.to_s.downcase
+        host == "openrouter.ai" || host.end_with?(".openrouter.ai")
+      rescue URI::Error
+        false
       end
 
       # Tool arguments as a Hash; "" is {}, invalid JSON stays a String.
@@ -86,10 +102,13 @@ module Samagotchi
       # @param remote [Boolean] a provider on the network, not a local server
       # @param first_token_timeout [Numeric, nil] seconds a streamed answer
       #   may take to show something (LLM::HTTP); nil: no limit
+      # @param default_max_tokens [Integer, nil] max_tokens for a request
+      #   whose options name none (OPENROUTER_MAX_TOKENS); nil sends none
       def initialize(base_url:, host_name:, api_key_env: nil, stream: true, retries: true, timeout: nil,
                      env: ENV, sleeper: nil, retry_policy: nil, models_ttl: DEFAULT_MODELS_TTL, remote: false,
-                     first_token_timeout: nil, purpose: "chat")
+                     first_token_timeout: nil, purpose: "chat", default_max_tokens: nil)
         @remote = remote
+        @default_max_tokens = default_max_tokens
         # What its requests are for, in the log (LLM::HTTP::LOGGED_PURPOSES).
         @purpose = purpose
         @first_token_timeout = first_token_timeout
@@ -121,7 +140,8 @@ module Samagotchi
                session_id: nil)
         body = request_body(messages, tools, model, options)
         request = post_request("#{@base_url}/chat/completions", body, session_id: session_id)
-        log_fields = { model: model, purpose: @purpose, sampling: sampling_summary(body) }
+        log_fields = { model: model, purpose: @purpose, sampling: sampling_summary(body),
+                       cache: ("on" if PromptCache.marked?(body[:messages])) }
         return chat_once(request, cancel_controller, log_fields) unless @stream
 
         assembly = Assembly.new
@@ -161,7 +181,7 @@ module Samagotchi
         models = []
         after = nil
         MAX_MODEL_PAGES.times do
-          uri = URI("#{@base_url}/models#{after ? "?after=#{URI.encode_www_form_component(after)}" : ""}")
+          uri = URI("#{@base_url}/models#{"?after=#{URI.encode_www_form_component(after)}" if after}")
           body = parse_json(@http.fetch(uri, get_request(uri), log_fields: { purpose: "models" }).body, "model list")
           models.concat(model_entries(body).map { |raw| model_info(raw) })
           break unless body.is_a?(Hash) && body["has_more"] && body["last_id"]
@@ -191,6 +211,18 @@ module Samagotchi
         nil
       end
 
+      def self.served_model(payload)
+        model = payload.is_a?(Hash) ? payload["model"] : nil
+        model.is_a?(String) && !model.strip.empty? ? model : nil
+      end
+
+      # OpenRouter names the provider that served a request (Baseten,
+      # Fireworks, …) in the body's `provider`; other servers send none.
+      def self.served_provider(payload)
+        provider = payload.is_a?(Hash) ? payload["provider"] : nil
+        provider.is_a?(String) && !provider.strip.empty? ? provider : nil
+      end
+
       private
 
       def timeouts(timeout)
@@ -204,19 +236,30 @@ module Samagotchi
       def request_body(messages, tools, model, options)
         body = {
           model: model,
-          messages: Array(messages).map { |message| wire_message(message) },
+          messages: cache_breakpoints(Array(messages).map { |message| wire_message(message) }, model),
           temperature: 0.0,
           stream: @stream
         }
         body[:stream_options] = { include_usage: true } if @stream
+        body[:max_tokens] = @default_max_tokens if @default_max_tokens
         unless Array(tools).empty?
           body[:tools] = tools
           body[:tool_choice] = "auto"
         end
-        # A configured value replaces chi's own (temperature); nil drops it.
+        # A configured value replaces chi's own (temperature, max_tokens); nil drops it.
         body.merge(options || {}).compact
       end
 
+      # Prompt-cache breakpoints (PromptCache) on the wire copies, for a
+      # Claude model's chat requests to a remote host: a one-shot side ask
+      # would pay for a cache write nothing reads, and a local model named
+      # after Claude must not get Array content.
+      def cache_breakpoints(messages, model)
+        return messages unless @remote && @purpose == "chat"
+
+        PromptCache.mark(messages, model: model)
+      end
+
       # The body's fields beyond the conversation and the stream, for the
       # log line: "temperature=0.6 presence_penalty=1.5".
       def sampling_summary(body)
@@ -247,34 +290,15 @@ module Samagotchi
           function = call["function"] || {}
           ToolCall.new(id: call["id"], name: function["name"].to_s, arguments: self.class.parse_arguments(function["arguments"]))
         end
-        ChatResponse.new(text: OpenAIChat.drop_leading_newlines(message["content"].to_s),
+        ChatResponse.new(text: message["content"].to_s,
                          reasoning: (message["reasoning_content"] || message["reasoning"]).to_s,
                          tool_calls: calls, usage: Usage.from_payload(body) || Usage.none,
                          finish_reason: body.dig("choices", 0, "finish_reason"), model: served_model(body),
                          provider: self.class.served_provider(body))
       end
 
-      # Workaround for Splash 1.0.2/1.1.0, which keeps the "\n\n" the model
-      # writes after </think> at the start of the answer
-      # (https://github.com/incoai/splash/issues/254). Remove once Splash
-      # strips it; llama.cpp already does. Streamed, it applies to the chunks
-      # until the first text.
-      def self.drop_leading_newlines(text) = text.sub(/\A[\r\n]+/, "")
-
-      def self.served_model(payload)
-        model = payload.is_a?(Hash) ? payload["model"] : nil
-        model.is_a?(String) && !model.strip.empty? ? model : nil
-      end
-
       def served_model(payload) = self.class.served_model(payload)
 
-      # OpenRouter names the provider that served a request (Baseten,
-      # Fireworks, …) in the body's `provider`; other servers send none.
-      def self.served_provider(payload)
-        provider = payload.is_a?(Hash) ? payload["provider"] : nil
-        provider.is_a?(String) && !provider.strip.empty? ? provider : nil
-      end
-
       def served_provider(payload) = self.class.served_provider(payload)
 
       # The parsed payload of a `data:` line; nil for blank lines, comments
@@ -345,7 +369,7 @@ module Samagotchi
         listed = raw["supported_parameters"] || raw["capabilities"]
         return nil unless listed.is_a?(Array)
 
-        listed.include?("tools") ? true : nil
+        listed.include?("tools") || nil
       end
 
       def cached_models
@@ -393,7 +417,6 @@ module Samagotchi
           @finish_reason = choice["finish_reason"] if choice["finish_reason"]
           delta = choice["delta"].is_a?(Hash) ? choice["delta"] : {}
           content = delta["content"].to_s
-          content = OpenAIChat.drop_leading_newlines(content) if @text.empty?
           reasoning = (delta["reasoning_content"] || delta["reasoning"]).to_s
           @text << content
           @reasoning << reasoning

data/lib/samagotchi/llm/prompt_cache.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module LLM
+    # Prompt-cache breakpoints for Claude models behind an OpenAI-compatible
+    # host (OpenRouter, a gateway). Anthropic caches a prompt only up to a
+    # content part marked with cache_control, in the order tools → system →
+    # messages, so two marks cover a chat request:
+    # - the first system message (with it, the tool list), and
+    # - the last non-system message with content, so the next request (the
+    #   same prefix plus new messages) reads everything up to it.
+    # Mid and tail system messages (reminders, turn notes) never take the
+    # second mark. Other models' messages pass through untouched.
+    module PromptCache
+      CONTROL = { type: "ephemeral" }.freeze
+
+      module_function
+
+      # Whether +model+ (the bare id a host is asked for) names a Claude model.
+      def claude?(model) = model.to_s.match?(/claude/i)
+
+      # +messages+ (wire messages: symbol keys, content a String or an Array
+      # of parts) with the breakpoints set when +model+ is a Claude model;
+      # the given messages as they are otherwise. The marked messages and
+      # parts are copies: the caller's are never changed.
+      # @return [Array<Hash>]
+      def mark(messages, model:)
+        return messages unless claude?(model)
+
+        indexes = [system_index(messages), last_index(messages)].compact.uniq
+        return messages if indexes.empty?
+
+        messages.each_with_index.map { |message, index| indexes.include?(index) ? marked(message) : message }
+      end
+
+      # Whether any message in +messages+ carries a breakpoint.
+      def marked?(messages)
+        Array(messages).any? do |message|
+          content = message[:content]
+          content.is_a?(Array) && content.any? { |part| part.is_a?(Hash) && control?(part) }
+        end
+      end
+
+      def system_index(messages)
+        index = messages.index { |message| message[:role].to_s == "system" }
+        index if index && content?(messages[index][:content])
+      end
+
+      # The last message that isn't a system message and has content (an
+      # assistant tool_calls message has nil or "").
+      def last_index(messages)
+        messages.rindex { |message| message[:role].to_s != "system" && content?(message[:content]) }
+      end
+
+      def content?(content)
+        case content
+        when String then !content.empty?
+        when Array then content.any?(Hash)
+        else false
+        end
+      end
+
+      # A String becomes one text part; an Array gets the mark on its last
+      # text part (the last part when none is text).
+      def marked(message)
+        content = message[:content]
+        return message.merge(content: [{ type: "text", text: content, cache_control: CONTROL }]) if content.is_a?(String)
+
+        target = content.rindex { |part| part.is_a?(Hash) && (part[:type] || part["type"]).to_s == "text" } ||
+                 content.rindex { |part| part.is_a?(Hash) }
+        part = content[target]
+        key = part.key?("type") ? "cache_control" : :cache_control
+        parts = content.dup
+        parts[target] = part.merge(key => CONTROL)
+        message.merge(content: parts)
+      end
+
+      def control?(part) = part.key?(:cache_control) || part.key?("cache_control")
+
+      private_class_method :system_index, :last_index, :content?, :marked, :control?
+    end
+  end
+end

data/lib/samagotchi/log.rb

@@ -143,7 +143,7 @@ module Samagotchi
       def safe_value(key, value)
         return "[redacted]" if key.match?(SECRET_KEY)
 
-        value = value.is_a?(Float) ? value.round(3) : value
+        value = value.round(3) if value.is_a?(Float)
         value.is_a?(String) && value.match?(URL) ? safe_url(value) : value
       end
 
@@ -185,7 +185,7 @@ module Samagotchi
       def build_state
         options = @options
         path = options.fetch(:path, :auto)
-        path = (LogPath.resolve rescue nil) if path == :auto
+        path = LogPath.resolve rescue nil if path == :auto
         level = options[:level] || (Config.get("log.level") rescue nil)
         level = LEVELS.key?(level.to_s.downcase.to_sym) ? level.to_s.downcase.to_sym : DEFAULT_LEVEL
         { writer: DebugLog.new(path: path), level: LEVELS.fetch(level), mirror: options[:mirror] ? true : false }

data/lib/samagotchi/log_subscriber.rb

@@ -46,7 +46,8 @@ module Samagotchi
       type = event[:type]&.to_sym
       return unless type
 
-      if respond_to?(handler = :"on_#{type}", true)
+      handler = :"on_#{type}"
+      if respond_to?(handler, true)
         send(handler, event)
       elsif ANNOUNCED.key?(type)
         log(:info, type, **event.slice(*ANNOUNCED[type]), **origin(event), **items(event))

data/lib/samagotchi/memory_bundle/builder.rb

@@ -65,8 +65,9 @@ module Samagotchi
           candidates_by_basename = candidates.map { |p| [File.basename(p), p] }.to_h
           missing = allow.reject { |k| candidates_by_basename.key?(k) }
           unless missing.empty?
-            raise BuildError, "Requested file(s) not found in #{@scope} scope: #{missing.join(', ')}"
+            raise BuildError, "Requested file(s) not found in #{@scope} scope: #{missing.join(", ")}"
           end
+
           candidates = with_overlays(allow, candidates_by_basename).map { |k| candidates_by_basename[k] }
         else
           candidates = leave_out_owned(candidates, resolved_name)
@@ -107,6 +108,7 @@ module Samagotchi
             src = File.join(prov.hooks_dir, basename)
             # Skip if hook file missing on disk
             next unless File.exist?(src)
+
             # meta may be symbol-keyed
             m = meta.is_a?(Hash) ? meta.transform_keys(&:to_s) : {}
             sha = (m["sha256"] || m["checksum"] || "").to_s
@@ -245,7 +247,7 @@ module Samagotchi
       def summary
         lines = []
         lines << "Built #{@built_files.size} file(s) to #{@out_path}"
-        lines << "Files: #{@built_files.join(', ')}" unless @built_files.empty?
+        lines << "Files: #{@built_files.join(", ")}" unless @built_files.empty?
         lines.concat(@placeholder_warnings.map { |w| "Placeholder: #{w}" }) unless @placeholder_warnings.empty?
         lines.concat(@warnings) unless @warnings.empty?
         lines.join("\n")
@@ -275,6 +277,7 @@ module Samagotchi
 
       def normalize_scope(val)
         return nil if val.nil? || val.to_s.strip.empty?
+
         v = val.to_s.strip.downcase
         %w[project system].include?(v) ? v : nil
       end
@@ -295,7 +298,7 @@ module Samagotchi
       def default_name(scope)
         if scope == "project"
           base = File.basename(MemoryPaths.project_root).gsub(/[^A-Za-z0-9_-]/, "-").downcase
-          base = base.gsub(/-+/, "-").gsub(/\A-+|-+\z/, "")
+          base = base.squeeze("-").gsub(/\A-+|-+\z/, "")
           base = "project" if base.empty?
           "chi_#{base}_memories"
         else
@@ -356,6 +359,7 @@ module Samagotchi
           if File.exist?(expanded) && !File.directory?(expanded)
             raise BuildError, "Output path exists and is not a directory: #{expanded}"
           end
+
           [expanded, :dir]
         end
       end
@@ -365,6 +369,7 @@ module Samagotchi
         if File.exist?(out_path)
           raise BuildError, "Output file already exists: #{out_path} — remove it or choose different --out"
         end
+
         # Use zip CLI like source.rb does with unzip
         Dir.chdir(staging) do
           result = system("zip", "-r", out_path, ".")
@@ -377,6 +382,7 @@ module Samagotchi
         if File.exist?(out_path)
           raise BuildError, "Output file already exists: #{out_path} — remove it or choose different --out"
         end
+
         # Use tar CLI
         Dir.chdir(staging) do
           cmd = case format

data/lib/samagotchi/memory_bundle/index_updater.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "fileutils"
 require "digest"
 require_relative "../atomic_file"
@@ -16,6 +17,7 @@ module Samagotchi
       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, source || nil)
           next auto_index_header + "\n\n" + new_line + "\n" if content.nil? || content.strip.empty?
@@ -32,20 +34,25 @@ module Samagotchi
         end
         true
       end
+
       def self.managed_pattern(name)
         /^- \*\*#{Regexp.escape(name)}\*\*[ \t]*(?:[·•].*|:.*)?(\r?\n|\z)/
       end
+
       def self.remove_index(scope, entry_name)
         index_path = index_path_for(scope)
         return true unless index_path && File.exist?(index_path)
+
         locked_write(File.dirname(index_path)) do |content|
           pattern = managed_pattern(entry_name)
           next nil unless content&.match?(pattern)
+
           # Clean up extra blank lines: collapse 3+ newlines to 2
           content.gsub(pattern, "").gsub(/\n{3,}/, "\n\n")
         end
         true
       end
+
       # Read-modify-write of <dir>/index.md under an exclusive flock on a sidecar
       # <dir>/.index.lock, so sessions in several worktrees of one repository
       # (one shared project folder) don't drop each other's lines. Yields the
@@ -61,6 +68,7 @@ module Samagotchi
           Samagotchi::AtomicFile.write(index_path, updated) unless updated.nil?
         end
       end
+
       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?
@@ -68,6 +76,7 @@ module Samagotchi
         line += " — #{desc}" unless desc.to_s.empty?
         line
       end
+
       def self.extract_description(line)
         if line =~ /\s—\s(.*)\s*\z/
           $1
@@ -75,6 +84,7 @@ module Samagotchi
           $1
         end
       end
+
       # The bundle a managed line names ("· from <bundle>", before any
       # " — description"), or nil.
       def self.extract_source(line)
@@ -86,14 +96,16 @@ module Samagotchi
           "Managed entries below are auto-maintained by memory_write " \
           "(name, scope, last-written date, size). Free-form sections are preserved."
       end
+
       def self.date_str
         require "date"
         Date.today.iso8601
       end
+
       def self.index_path_for(scope)
         base_dir = MemoryPaths.scope_dir(scope.to_s.strip)
         base_dir && File.join(base_dir, "#{MEMORY_INDEX}.md")
       end
     end
   end
-end
+end