samagotchi 0.75.0 → 0.76.0

data/lib/samagotchi/memory_bundle/installer.rb

@@ -34,8 +34,16 @@ module Samagotchi
 
       attr_reader :results, :warnings, :placeholder_warnings, :conflicts
 
-      def initialize(source:, name:, scope: nil, force: false, strict: true, upgrade: false, dry_run: false)
+      # prepared: the source already normalized (a PreparedSource, which the
+      # Installer then owns and cleans up as its own); nil normalizes source.
+      # shipped_dir: the bundles this chi ships (a bundle of their names
+      # installs from a dir in it only, unless force); ShippedUpdate,
+      # Profile and SystemBundle pass the one they install from.
+      def initialize(source:, name:, scope: nil, force: false, strict: true, upgrade: false, dry_run: false, prepared: nil,
+                     shipped_dir: SourceNormalizer::SHIPPED_DIR)
         @source = source
+        @shipped_dir = shipped_dir
+        @prepared = prepared
         @name = name
         @scope = scope&.to_s&.strip&.downcase || ""
         @force = force
@@ -50,6 +58,10 @@ module Samagotchi
         @trash = Trash.new(name)
       end
 
+      # [recorded source, this source] when an upgrade switches the bundle's
+      # source (Installer#check_source), else nil.
+      attr_reader :source_change
+
       # Where an upgrade moved the files the bundle no longer ships (nil:
       # none moved).
       def trash_dir = @trash.dir
@@ -78,6 +90,7 @@ module Samagotchi
         @file_descriptions = @manifest&.file_descriptions || {}
         @provenance = Provenance.new(name: @name)
         @existing = @provenance.record
+        check_source
         # A plain install over an installed bundle: summary points at upgrade.
         @reinstall = @existing && !@upgrade && !@force && !@dry_run
         install_memories
@@ -114,6 +127,7 @@ module Samagotchi
 
       def summary
         lines = []
+        lines << "Source changes: #{@source_change.join(" → ")}" if @source_change
         installed = @results.select { |_, r| r[:status].to_s == "installed" }.keys
         updated = @results.select { |_, r| r[:status].to_s == "updated" }.keys
         kept = @results.select { |_, r| %w[kept kept_pruned].include?(r[:status].to_s) }.keys
@@ -142,12 +156,90 @@ module Samagotchi
 
       private
 
+      # Who may install under this name (a manifest can take any name: a
+      # repo calling itself guardrails). Sources compare by SourceIdentity
+      # (a shipped dir by name, in any gem or checkout; a git URL without
+      # #ref; a path resolved); one it can't place (an older record's
+      # relative path) never refuses.
+      #   - a name chi ships comes from a shipped dir only, unless --force
+      #     (install and upgrade): the plugin and hooks it replaces are chi's;
+      #   - a plain install over a bundle from another source is refused,
+      #     --force too (that overwrites files, it doesn't switch sources):
+      #     it would delete the plugin and hooks and rewrite the record;
+      #   - an upgrade may switch sources (a URL and a local copy of it are
+      #     one bundle, an archive's file name has its version), and
+      #     #source_change says so (the summary's first line).
+      def check_source
+        refuse_case_twin
+        refuse_shipped_name
+        now = incoming_identity
+        return if now.nil?
+
+        was = @existing && SourceIdentity.of(@existing.source)
+        return if was.nil? || was == now
+        return @source_change = [@existing.source, @source.to_s] if @upgrade
+
+        raise InstallError, "#{@name} is installed from #{@existing.source}; `chi bundle upgrade #{@source}` " \
+                            "switches its source, or `chi bundle uninstall #{@name}` first"
+      end
+
+      # A name that differs from an installed bundle's only in case is that
+      # bundle's dir on a case-insensitive file system (macOS): BTW would
+      # replace btw. Refused, --force too.
+      def refuse_case_twin
+        twin, = Provenance.each_installed.find { |name, _| name != @name && name.casecmp?(@name) }
+        raise InstallError, "#{@name} differs only in case from the installed #{twin}" if twin
+      end
+
+      # A shipped name (in any case) from anything but this chi's own
+      # shipped dir. A recorded source may be an older gem's (SourceIdentity
+      # matches the path); an incoming one must be a dir in SHIPPED_DIR, so
+      # a fork's lib/samagotchi/bundles/btw isn't chi's.
+      def refuse_shipped_name
+        return if @force || chi_copy?(@source)
+
+        shipped = shipped_names.find { |name| name.casecmp?(@name) }
+        return unless shipped
+
+        what = shipped == @name ? "#{@name} is a bundle shipped with chi" : "#{@name} is #{shipped}, a bundle shipped with chi"
+        raise InstallError, "#{what}; #{@source} isn't chi's copy of it (--force to install it anyway)"
+      end
+
+      # This source's SourceIdentity; one that looks shipped by its path (a
+      # fork's lib/samagotchi/bundles/btw) but isn't a dir in the shipped
+      # dir is its path, so it isn't taken for chi's btw. A recorded source
+      # keeps the path match (older gems).
+      def incoming_identity
+        identity = SourceIdentity.of(@source)
+        identity&.shipped? && !chi_copy?(@source) ? SourceIdentity.path(@source) : identity
+      end
+
+      # Whether +source+ is a dir in the shipped dir.
+      def chi_copy?(source)
+        path = File.realpath(source.to_s)
+        File.directory?(path) && File.dirname(path) == File.realpath(@shipped_dir)
+      rescue SystemCallError
+        false
+      end
+
+      # The names of the bundles shipped with chi (their manifests'),
+      # samagotchi-system and profiles included.
+      def shipped_names
+        Dir.glob(File.join(@shipped_dir, "*", "manifest.yml")).filter_map do |path|
+          Manifest.read(dir: File.dirname(path)).name
+        rescue Manifest::ValidationError
+          nil
+        end
+      end
+
       # The source normalized to a dir (@bundle_dir; an owned one, extracted
       # from git/zip/tar, is cleaned up after #run) and its manifest.yml
       # (@manifest, nil when it has none and the install isn't strict).
       def load_source
-        @bundle_dir, @source_owned, @source_commit = SourceNormalizer.normalize(@source)
-        @source_dir = @bundle_dir
+        prepared = @prepared || PreparedSource.prepare(@source)
+        @bundle_dir = @source_dir = prepared.dir
+        @source_owned = prepared.owned
+        @source_commit = prepared.commit
         @manifest = Manifest.read(dir: @bundle_dir)
       rescue SourceNormalizer::UnknownSourceError => e
         raise InstallError, "Source normalization failed: #{e.message}"
@@ -181,6 +273,7 @@ module Samagotchi
         @bundle_md = []
         @owned = []
         warn_unshipped_files
+        warn_symlinked_files
         memory_files.each do |file_key|
           file_path = File.join(@bundle_dir, file_key)
           @bundle_md << file_key
@@ -220,6 +313,11 @@ module Samagotchi
         @warnings << "files: names #{missing.join(", ")}, which the bundle doesn't ship (not installed)" unless missing.empty?
       end
 
+      # A memory that is a symlink isn't installed (MemoryFiles.symlinks).
+      def warn_symlinked_files
+        MemoryFiles.symlinks(@bundle_dir, @manifest).each { |name| @warnings << "#{name} is a symlink (not installed)" }
+      end
+
       # An upgrade's 3-way merge of one file (Merger.classify against the
       # base the last install recorded); a conflict leaves the local file
       # and is recorded in @conflicts for the agent step.
@@ -356,13 +454,32 @@ module Samagotchi
       # for a local edit: keep the installed base, so the next upgrade still
       # sees the edit (not a fast-forward over it).
       def install_provenance_files
-        @owned.each_with_object({}) do |file_key, files|
+        files = @owned.each_with_object({}) do |file_key, map|
           target_path = File.join(@target_dir, file_key)
           next unless File.exist?(target_path)
 
           base_path = @provenance.base_path(file_key)
           kept = @existing && @results.dig(file_key, :reason) == "already exists" && File.exist?(base_path)
-          files[file_key] = kept ? base_path : target_path
+          map[file_key] = kept ? base_path : target_path
+        end
+        files.merge(dropped_owned_files)
+      end
+
+      # file key => its base, for each file an earlier install owned that
+      # this version doesn't ship and that is still on disk. A plain
+      # install leaves such a file where it is, and keeps its record, so the
+      # upgrade the summary points at still moves it to the trash
+      # (prune_dropped_files); dropping the record orphaned it as a memory.
+      def dropped_owned_files
+        return {} unless @existing
+
+        @existing.files.each_key.with_object({}) do |key, files|
+          file_key = key.to_s
+          next if @bundle_md.include?(file_key)
+          next unless File.exist?(File.join(@target_dir, file_key))
+
+          base_path = @provenance.base_path(file_key)
+          files[file_key] = base_path if File.exist?(base_path)
         end
       end
 

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -64,8 +64,13 @@ module Samagotchi
 
       def initialize(path:)
         @path = path
-        raw = YAML.load_file(path) || {}
+        raw = load_mapping(path)
         @name     = require_str(raw, "name")
+        # The name is a directory under .bundles/: never a path.
+        if @name.match?(%r{[/\\\0]}) || %w[. ..].include?(@name)
+          raise ValidationError, "name: #{@name.inspect} is not a bundle name (no path separators, not . or ..)"
+        end
+
         @version  = require_str(raw, "version")
         @scope    = normalize_scope(raw["scope"])
         @description = (raw["description"] || "").to_s
@@ -188,6 +193,20 @@ module Samagotchi
 
       private
 
+      # The manifest.yml's top-level mapping ({} for an empty file); YAML that
+      # doesn't parse, or isn't a mapping, raises ValidationError, as every
+      # other manifest problem does.
+      def load_mapping(path)
+        raw = YAML.load_file(path) || {}
+        raise ValidationError, "manifest.yml is not a YAML mapping in #{File.dirname(path)}" unless raw.is_a?(Hash)
+
+        raw
+      rescue Psych::SyntaxError => e
+        raise ValidationError, "manifest.yml is not valid YAML in #{File.dirname(path)}: line #{e.line}, column #{e.column}: #{e.problem}"
+      rescue Psych::Exception => e
+        raise ValidationError, "manifest.yml is not valid YAML in #{File.dirname(path)}: #{e.message}"
+      end
+
       def require_str(hash, key)
         val = hash[key]
         return val if val.is_a?(String) && !val.empty?

data/lib/samagotchi/memory_bundle/memory_files.rb

@@ -13,6 +13,9 @@ module Samagotchi
     # files: {} means "no list" rather than "no memories": shipped bundles
     # with nothing to install write it (mcp), and an external bundle that
     # left the map empty installed its *.md before this rule.
+    # A symlink is never a memory (.symlinks names the ones skipped): a
+    # tar, zip or git repo keeps links, and copying through one would put
+    # any file the user can read (~/.ssh/..., an API key) into a memory.
     module MemoryFiles
       # A repo's meta files, by name without extension (case-insensitive).
       REPO_META = %w[readme changelog license licence contributing code_of_conduct security].freeze
@@ -22,18 +25,33 @@ module Samagotchi
 
       # @return [Array<String>] the memories' basenames, sorted
       def select(bundle_dir, manifest)
-        present = Dir.glob(File.join(bundle_dir, "*.md")).map { |f| File.basename(f) }.sort
-        listed = manifest&.files&.keys
-        return present & listed if listed && !listed.empty?
+        candidates(bundle_dir, manifest).reject { |name| File.symlink?(File.join(bundle_dir, name)) }
+      end
 
-        present.reject { |name| repo_meta?(name) }
+      # The memories .select leaves out because they are symlinks, sorted.
+      def symlinks(bundle_dir, manifest)
+        candidates(bundle_dir, manifest).select { |name| File.symlink?(File.join(bundle_dir, name)) }
       end
 
-      # The files: entries that name no top-level *.md of the bundle.
+      # The files: entries that name no top-level *.md of the bundle (a
+      # symlink is in .symlinks, not here).
       def unshipped(bundle_dir, manifest)
         listed = manifest&.files&.keys || []
-        listed.reject { |name| name.end_with?(".md") && File.file?(File.join(bundle_dir, name)) && !name.include?("/") }
+        listed.reject do |name|
+          path = File.join(bundle_dir, name)
+          name.end_with?(".md") && !name.include?("/") && (File.symlink?(path) || File.file?(path))
+        end
+      end
+
+      # The top-level *.md files the rules above pick, symlinks included.
+      def candidates(bundle_dir, manifest)
+        present = Dir.glob(File.join(bundle_dir, "*.md")).map { |f| File.basename(f) }.sort
+        listed = manifest&.files&.keys
+        return present & listed if listed && !listed.empty?
+
+        present.reject { |name| repo_meta?(name) }
       end
+      private_class_method :candidates
 
       # Whether +name+ is a repo's meta file: README, README.md,
       # readme.markdown, LICENSE.txt, ...

data/lib/samagotchi/memory_bundle/profile.rb

@@ -109,7 +109,7 @@ module Samagotchi
         return result.skipped[member] = failure if failure
         return result.installed << member if dry_run
 
-        Installer.new(source: member_dir, name: member, scope: "system", force: force, strict: true).run
+        Installer.new(source: member_dir, name: member, scope: "system", force: force, strict: true, shipped_dir: shipped_dir).run
         result.installed << member
       rescue StandardError => e
         result.failed[member] = e.message.lines.first.to_s.strip

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -65,7 +65,8 @@ module Samagotchi
           next row unless row.status == :would_update
           next apply_profile(row) if row.adds
 
-          installer = Installer.new(source: row.source_dir, name: row.name, scope: row.scope, strict: true, upgrade: true)
+          installer = Installer.new(source: row.source_dir, name: row.name, scope: row.scope, strict: true, upgrade: true,
+                                    shipped_dir: File.dirname(row.source_dir))
           installer.run
           row.dup.tap do |r|
             r.status = :updated

data/lib/samagotchi/memory_bundle/source.rb

@@ -50,6 +50,10 @@ module Samagotchi
         return nil unless name.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
         return nil if File.exist?(File.join(cwd, name))
 
+        # Dir.children, not File.file? alone: the name in its exact case
+        # (a case-insensitive file system finds btw's dir for BTW).
+        return nil unless File.directory?(SHIPPED_DIR) && Dir.children(SHIPPED_DIR).include?(name)
+
         dir = File.join(SHIPPED_DIR, name)
         File.file?(File.join(dir, "manifest.yml")) ? dir : nil
       end
@@ -128,6 +132,9 @@ module Samagotchi
       # Copies the contents of `src_dir` into a new permanent directory, stripping
       # one level of nesting if there's a single top-level entry.
       # The returned path survives after `src_dir` is cleaned up.
+      # A symlink stays a symlink, at the top level too (cp_r dereferences
+      # its root by default): the Installer then skips it (MemoryFiles,
+      # AssetInstaller#linked?) instead of installing what it points at.
       def self.clean_copy_of(src_dir)
         contents = Dir.entries(src_dir).reject { |e| e.start_with?(".") }
         # Zip-slip check: reject entries with ".." path components.
@@ -139,21 +146,77 @@ module Samagotchi
 
         if contents.size == 1
           entry_path = File.join(src_dir, contents.first)
-          if File.directory?(entry_path) && !Dir.empty?(entry_path)
+          if File.directory?(entry_path) && !File.symlink?(entry_path) && !Dir.empty?(entry_path)
             dst = Dir.mktmpdir("samagotchi-bundle-")
-            FileUtils.cp_r("#{entry_path}/.", dst)
+            FileUtils.cp_r("#{entry_path}/.", dst, dereference_root: false)
             return [dst, true]
           end
         end
 
         dst = Dir.mktmpdir("samagotchi-bundle-")
         contents.each do |entry|
-          FileUtils.cp_r(File.join(src_dir, entry), dst)
+          FileUtils.cp_r(File.join(src_dir, entry), dst, dereference_root: false)
         end
         [dst, true]
       end
 
       private_class_method :normalize_zip, :normalize_tar, :clean_copy_of
     end
+
+    # What a bundle's source is, for telling whether two installs of one
+    # name come from the same place (Installer: a bundle from elsewhere
+    # doesn't silently replace an installed one). key is
+    #   shipped:<dir>  a shipped dir (SHIPPED_SOURCE), in any gem or checkout,
+    #                  so `chi update` and a newer chi upgrade it
+    #   git:<url>      a git URL without its #ref, a trailing / or .git
+    #   path:<path>    an absolute path, symlinks resolved when it exists
+    # .of is nil for a source it can't place (empty, or a relative path an
+    # older record may hold): unknown never refuses.
+    SourceIdentity = Data.define(:key) do
+      def self.of(source)
+        s = source.to_s.strip
+        return nil if s.empty?
+
+        if SourceNormalizer.git_url?(s)
+          url = SourceNormalizer.strip_git_ref(s).first.sub(%r{/+\z}, "").delete_suffix(".git")
+          new(key: "git:#{url}")
+        elsif s.match?(SourceNormalizer::SHIPPED_SOURCE)
+          new(key: "shipped:#{File.basename(s.chomp("/"))}")
+        elsif s.start_with?("/")
+          new(key: "path:#{real(s)}")
+        end
+      end
+
+      # +source+ as a path:<realpath>, whatever it looks like.
+      def self.path(source) = new(key: "path:#{real(source.to_s)}")
+
+      def self.real(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+      private_class_method :real
+
+      def shipped? = key.start_with?("shipped:")
+
+      def to_s = key
+    end
+
+    # A source normalized once to a local dir (SourceNormalizer.normalize):
+    # owned when it is a git clone or a zip/tar extract, which #cleanup
+    # removes; commit is a git clone's HEAD (nil otherwise). BundleCommand
+    # reads the bundle's name from it and the Installer installs from it, so
+    # a source is cloned or extracted once per command.
+    PreparedSource = Data.define(:dir, :owned, :commit) do
+      # @raise [SourceNormalizer::UnknownSourceError]
+      def self.prepare(source)
+        dir, owned, commit = SourceNormalizer.normalize(source)
+        new(dir: dir, owned: owned, commit: commit)
+      end
+
+      def cleanup
+        SourceNormalizer.cleanup(dir) if owned
+      end
+    end
   end
 end

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -141,7 +141,8 @@ module Samagotchi
           name: BUNDLE_NAME,
           scope: SCOPE,
           force: false,
-          strict: true
+          strict: true,
+          shipped_dir: File.dirname(GEM_BUNDLE_DIR)
         )
         installer.run
         result(:installed, to: to, warnings: installer.warnings)
@@ -182,7 +183,8 @@ module Samagotchi
       end
 
       def upgrade_installer
-        Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true)
+        Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true,
+                      shipped_dir: File.dirname(GEM_BUNDLE_DIR))
       end
       private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present,
                            :upgrade_installer, :result, :conflicting

data/lib/samagotchi/model_price.rb

@@ -37,9 +37,10 @@ module Samagotchi
     # USD for one generation, OpenAI usage semantics: +prompt_tokens+ holds
     # the cached reads and the cache writes (OpenRouter keeps that for
     # Anthropic models), and reasoning is inside +completion_tokens+.
-    # llama.cpp's native timings.prompt_n leaves its cache_n out, so the
-    # uncached part is clamped at 0: an undercount, harmless because priced
-    # models are remote.
+    # llama.cpp's native stream ends with tokens_evaluated, the whole prompt
+    # (SessionMetrics keeps the largest count, so not timings.prompt_n,
+    # which leaves cache_n out); the uncached part is clamped at 0 for a
+    # report that has prompt_n alone.
     def cost(prompt_tokens:, cached_tokens:, cache_write_tokens:, completion_tokens:)
       uncached = (prompt_tokens - cached_tokens - cache_write_tokens).clamp(0..)
       ((uncached * input) + (cached_tokens * cache_read) + (cache_write_tokens * cache_write) +

data/lib/samagotchi/paths.rb

@@ -28,7 +28,21 @@ module Samagotchi
     # @return [String] $XDG_CONFIG_HOME (absolute), else ~/.config
     def config_home(env: ENV)
       xdg = env.fetch("XDG_CONFIG_HOME", "").to_s.strip
-      xdg.empty? ? File.expand_path("~/.config") : File.absolute_path(xdg)
+      xdg.empty? ? File.join(Dir.home, ".config") : File.absolute_path(xdg)
+    end
+
+    # The set XDG dirs, made absolute. +set+ is :nonblank (unset or blank
+    # values omitted) or :key (present keys included, even when blank).
+    # @return [Hash{String => String}]
+    def absolute_xdg(env: ENV, set: :nonblank)
+      included = case set
+                 when :nonblank then ->(key) { !env.fetch(key, "").to_s.strip.empty? }
+                 when :key then ->(key) { env.key?(key) }
+                 else raise ArgumentError, "set must be :nonblank or :key"
+                 end
+      { "XDG_STATE_HOME" => :state_home, "XDG_CONFIG_HOME" => :config_home }.each_with_object({}) do |(key, home), dirs|
+        dirs[key] = public_send(home, env: env) if included.call(key)
+      end
     end
 
     # +path+ as chi shows it: ~ for the home folder (~/a for one in it),

data/lib/samagotchi/session_commands.rb

@@ -592,6 +592,8 @@ module Samagotchi
       @engine.switch_model!(name, persist_default: persist_default)
       @default_model = @engine.default_model_name if persist_default
       persist_session_model
+      # The ctx % on the new model's window, before its first turn.
+      @engine.announce_switched_context!
     end
 
     def persist_session_model

data/lib/samagotchi/session_manager.rb

@@ -244,8 +244,7 @@ module Samagotchi
       end
       # And the spawner's XDG dirs, absolute: a relative XDG_STATE_HOME or
       # XDG_CONFIG_HOME would otherwise be read from the session's directory.
-      child_env["XDG_STATE_HOME"] = Paths.state_home unless ENV.fetch("XDG_STATE_HOME", "").to_s.strip.empty?
-      child_env["XDG_CONFIG_HOME"] = Paths.config_home unless ENV.fetch("XDG_CONFIG_HOME", "").to_s.strip.empty?
+      child_env.merge!(Paths.absolute_xdg)
       # The spawner's environment must not reach the worker's guardrails (a
       # parent agent starting or waking a session): Process.spawn unsets a
       # key mapped to nil. config.yml no longer reads them; this keeps an

data/lib/samagotchi/session_metrics/model_segment.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "totals"
+
+module Samagotchi
+  class SessionMetrics
+    # A run of consecutive turns on one model (their records' model_ref, the
+    # asked host:model): /stats and the web's ctx/cost tooltip split the
+    # session's tokens, cost and speed by these, in order, so A -> B -> A is
+    # three. Derived from the turn records as they are counted, never saved
+    # on their own. A record with no ref (a turn stopped before it asked a
+    # model) joins the segment before it; records with none before the first
+    # one that names a model (a session older than model_ref) make one
+    # leading segment with no ref.
+    #
+    # +prefill_tokens+ / +prefill_cost_estimate+: what the segment's first
+    # turn prefilled on its model after the switch (the records'
+    # switch_prefill_*), 0 / nil for none.
+    class ModelSegment < Data.define(:model_ref, :started_at, :ended_at, :turns, :totals, :prefill_tokens,
+                                     :prefill_cost_estimate)
+      # The most rows a snapshot sends: older ones fold into one.
+      CAP = 6
+
+      # A segment opened by +record+ (its first turn).
+      # @param record [Hash] a turn record (symbol keys)
+      # @return [ModelSegment]
+      def self.open(record)
+        ref = record[:model_ref].to_s
+        new(model_ref: ref.empty? ? nil : ref, started_at: record[:started_at], ended_at: nil, turns: 0,
+            totals: Totals.zero, prefill_tokens: 0, prefill_cost_estimate: nil).add(record)
+      end
+
+      # The segment a snapshot shows for the running turn when it is on
+      # another model than the last segment's: no finished turn yet.
+      # @param ref [String]
+      # @param started_at [String, nil]
+      # @return [ModelSegment]
+      def self.empty(ref, started_at)
+        new(model_ref: ref, started_at: started_at, ended_at: nil, turns: 0, totals: Totals.zero, prefill_tokens: 0,
+            prefill_cost_estimate: nil)
+      end
+
+      # Whether +record+ starts a new segment after this one: it names a
+      # model, and another one than this segment's.
+      def self.splits?(segment, record)
+        ref = record[:model_ref].to_s
+        segment.nil? || (!ref.empty? && segment.model_ref != ref)
+      end
+
+      # This segment with one more finished turn record.
+      # @return [ModelSegment]
+      def add(record)
+        tokens = record[:switch_prefill_tokens]
+        estimate = record[:switch_prefill_cost_estimate]
+        with(ended_at: record[:completed_at] || ended_at, turns: turns + 1, totals: totals.add(record),
+             prefill_tokens: prefill_tokens + (tokens.is_a?(Numeric) ? tokens : 0),
+             prefill_cost_estimate: estimate.is_a?(Numeric) ? prefill_cost_estimate.to_f + estimate : prefill_cost_estimate)
+      end
+
+      # This segment with the running turn (SessionMetrics::TurnState) in:
+      # its finished generations and the prefill it recorded so far; it
+      # runs on, so it has no end.
+      # @return [ModelSegment]
+      def with_running(turn)
+        estimate = turn.switch_prefill_cost_estimate
+        with(ended_at: nil, turns: turns + 1, totals: totals.with_running(turn),
+             prefill_tokens: prefill_tokens + turn.switch_prefill_tokens.to_i,
+             prefill_cost_estimate: estimate ? prefill_cost_estimate.to_f + estimate : prefill_cost_estimate)
+      end
+
+      # The row a snapshot carries (JSON-ready). +ended_at+ nil: the segment
+      # runs now.
+      # @return [Hash]
+      def to_h
+        tokens = totals.tokens_block
+        {
+          model_ref: model_ref, started_at: started_at, ended_at: ended_at, turns: turns,
+          **tokens.slice(:prompt_sum, :completion_sum, :cached_sum, :cost_sum, :cost_estimate_sum, :avg_decode_tps,
+                         :last_decode_tps, :tps_source),
+          prefill_tokens: prefill_tokens, prefill_cost_estimate: prefill_cost_estimate
+        }
+      end
+
+      # The rows of +segments+ a snapshot sends: none for fewer than 2 (one
+      # model: the plain totals say it all); over CAP, the oldest fold into
+      # one row with no ref that says how many it holds (folded_segments).
+      # @param segments [Array<ModelSegment>]
+      # @return [Array<Hash>]
+      def self.rows(segments)
+        return [] if segments.size < 2
+        return segments.map(&:to_h) if segments.size <= CAP
+
+        older = segments.first(segments.size - CAP + 1)
+        folded = older.drop(1).reduce(older.first.with(model_ref: nil)) do |sum, segment|
+          sum.merge(segment)
+        end
+        [folded.to_h.merge(folded_segments: older.size), *segments.last(CAP - 1).map(&:to_h)]
+      end
+
+      # This segment and a later one as one row (the folded older ones).
+      # @return [ModelSegment]
+      def merge(later)
+        estimate = [prefill_cost_estimate, later.prefill_cost_estimate].compact
+        with(ended_at: later.ended_at, turns: turns + later.turns, totals: totals.merge(later.totals),
+             prefill_tokens: prefill_tokens + later.prefill_tokens, prefill_cost_estimate: estimate.empty? ? nil : estimate.sum)
+      end
+    end
+  end
+end