samagotchi 0.2.0

data/lib/samagotchi/project_scope.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "memory_paths"
+
+module Samagotchi
+  # Which project a folder belongs to, for scoping session lists (web and
+  # terminal alike): the project root memories use (MemoryPaths.project_root),
+  # so every worktree and subfolder of one repository is one project. A
+  # folder in no git repository has no project (nil): its scope is "all".
+  module ProjectScope
+    module_function
+
+    # @param cache [Hash, nil] folder → root, reused across one listing
+    # @return [String, nil]
+    def root_for(dir, cache: nil)
+      dir = dir.to_s
+      return nil if dir.empty?
+      return cache[dir] if cache&.key?(dir)
+
+      root = MemoryPaths.in_repo?(dir) ? MemoryPaths.project_root(File.expand_path(dir)) : nil
+      cache[dir] = root if cache
+      root
+    end
+  end
+end

data/lib/samagotchi/prompt.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "model_profile"
+require_relative "prompt_literal_guard"
+require_relative "vision_context"
+
+module Samagotchi
+  # Formats a message list into a prompt string ready for the /completion endpoint.
+  #
+  # Supports multiple model profiles (Gemma 4, Qwen 3.6, etc.) with different
+  # token formats, role prefixing strategies, and tool response handling.
+  #
+  # Gemma 4:
+  #   - Turn markers: <|turn>ROLE\n...<end_of_turn>\n
+  #   - Tool response: standalone <|tool_response>...<tool_response|>
+  #   - Generation cue: <|turn>model\n
+  #
+  # Qwen 3.6:
+  #   - Role framing: <|im_start|>ROLE\n...<|im_end|>
+  #   - Tool response: wrapped in user message with <tool_response>...</tool_response>
+  #   - Generation cue: <|im_start|>assistant\n
+  module Prompt
+    # Tail system messages whose text isn't the harness's own.
+    ESCAPED_KINDS = %w[note turn_note context].freeze
+
+    # @param messages [Array<Hash>] each element has :role and :content.
+    #   Recognised roles: "system", "user", "model", "tool_response".
+    # @param profile [ModelProfile] model token configuration
+    # @return [String] formatted prompt ready for the /completion endpoint.
+    def self.format(messages, profile: ModelProfile.default)
+      format_with_images(messages, profile: profile).first
+    end
+
+    # The prompt plus the base64 images it carries, in marker order. Each
+    # image a message sends is a line after its text: "[image N: name] "
+    # and the profile's image template around ImagePlan::NATIVE_PLACEHOLDER
+    # (Client#complete swaps in the server's media marker); an image left
+    # out is its placeholder line. With no images the prompt is exactly
+    # what it was before images existed.
+    #
+    # @param vision [VisionContext, nil] the turn's images context
+    # @return [Array(String, Array<String>)]
+    def self.format_with_images(messages, profile: ModelProfile.default, vision: nil)
+      plan = ImagePlan.new(messages, vision, data: :base64)
+      images = []
+      suffixes = messages.each_with_index.map { |m, index| image_lines(plan.items(m, index), profile, images) }
+      text = if profile.uses_role_prefixes?
+               format_with_prefixes(messages, profile, suffixes)
+             else
+               format_with_turn_markers(messages, profile, suffixes)
+             end
+      [text, images]
+    end
+
+    private
+
+    def self.image_lines(items, profile, images)
+      return "" if items.empty?
+
+      lines = items.each_with_index.map do |item, index|
+        next item.placeholder unless item.sent?
+        next ImageRef.placeholder(item.ref, ImagePlan::CANT_SEE) unless profile.image_template
+
+        images << item.data
+        "[image #{index + 1}: #{ImageRef.name(item.ref)}] " \
+          "#{Kernel.format(profile.image_template, marker: ImagePlan::NATIVE_PLACEHOLDER)}"
+      end
+      "\n#{lines.join("\n")}"
+    end
+
+    def self.format_with_turn_markers(messages, profile, suffixes)
+      # Gemma 4 style: <|turn>ROLE\n...<end_of_turn>\n
+      parts = messages.each_with_index.map do |m, index|
+        content = prompt_content_for(m, profile) + suffixes[index]
+        if m[:role] == "tool_response"
+          "#{profile.tool_response_open}\n#{content}#{profile.tool_response_close}\n"
+        else
+          "#{profile.turn_start}#{m[:role]}\n#{content}#{profile.turn_end}\n"
+        end
+      end
+      parts << "#{profile.turn_start}model\n"
+      parts.join
+    end
+
+    def self.format_with_prefixes(messages, profile, suffixes)
+      # Qwen 3.6 style: <|im_start|>ROLE\n...<|im_end|>
+      parts = []
+
+      messages.each_with_index do |m, index|
+        content = prompt_content_for(m, profile) + suffixes[index]
+        case m[:role]
+        when "system"
+          parts << "#{profile.system_prefix}#{content}<|im_end|>\n"
+        when "user"
+          parts << "#{profile.user_prefix}#{content}<|im_end|>\n"
+        when "model"
+          parts << "#{profile.model_prefix}#{content}<|im_end|>\n"
+        when "tool_response"
+          # Wrap tool response in user message for Qwen
+          parts << "#{profile.user_prefix}#{profile.tool_response_open}\n#{content}#{profile.tool_response_close}\n<|im_end|>\n"
+        end
+      end
+
+      # Cue generation as assistant
+      parts << profile.assistant_prefix
+      parts.join
+    end
+
+    def self.prompt_content_for(message, profile)
+      return message[:content].to_s if message[:preserve_literals]
+
+      # A context note is system-framed but its text is untrusted (Slack, a
+      # peer session), and a turn note carries an error's text: escaped like
+      # user content so it can't close its turn.
+      role = ESCAPED_KINDS.include?(message[:kind].to_s) ? "user" : message[:role]
+      PromptLiteralGuard.escape(message[:content], profile: profile, role: role)
+    end
+  end
+end

data/lib/samagotchi/prompt_literal_guard.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Escapes literal control-token text when arbitrary source/output is embedded
+  # inside prompts, then restores those placeholders when model text is used.
+  module PromptLiteralGuard
+    GEMMA_TOKEN_PAIRS = [
+      ["[[SAMAGOTCHI_LITERAL_TURN_START]]", "<|turn>"],
+      ["[[SAMAGOTCHI_LITERAL_TURN_END]]", "<end_of_turn>"],
+      ["[[SAMAGOTCHI_LITERAL_TOOL_CALL_OPEN]]", "<|tool_call>"],
+      ["[[SAMAGOTCHI_LITERAL_TOOL_CALL_CLOSE]]", "<tool_call|>"],
+      ["[[SAMAGOTCHI_LITERAL_TOOL_RESPONSE_OPEN]]", "<|tool_response>"],
+      ["[[SAMAGOTCHI_LITERAL_TOOL_RESPONSE_CLOSE]]", "<tool_response|>"],
+      ["[[SAMAGOTCHI_LITERAL_GEMMA_STRING_DELIM]]", '<|"|>'],
+      ["[[SAMAGOTCHI_LITERAL_THINK_OPEN]]", "<|think|>"],
+      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_OPEN]]", "<|channel>thought"],
+      ["[[SAMAGOTCHI_LITERAL_THOUGHT_CHANNEL_CLOSE]]", "<channel|>"]
+    ].freeze
+
+    QWEN_TOKEN_PAIRS = [
+      ["[[SAMAGOTCHI_LITERAL_IM_START]]", "<|im_start|>"],
+      ["[[SAMAGOTCHI_LITERAL_IM_END]]", "<|im_end|>"],
+      ["[[SAMAGOTCHI_LITERAL_TOOL_CALL_OPEN]]", "<tool_call>"],
+      ["[[SAMAGOTCHI_LITERAL_TOOL_CALL_CLOSE]]", "</tool_call>"],
+      ["[[SAMAGOTCHI_LITERAL_TOOL_RESPONSE_OPEN]]", "<tool_response>"],
+      ["[[SAMAGOTCHI_LITERAL_TOOL_RESPONSE_CLOSE]]", "</tool_response>"],
+      ["[[SAMAGOTCHI_LITERAL_THINK_OPEN]]", "<think>"],
+      ["[[SAMAGOTCHI_LITERAL_THINK_CLOSE]]", "</think>"],
+      ["[[SAMAGOTCHI_LITERAL_VISION_START]]", "<|vision_start|>"],
+      ["[[SAMAGOTCHI_LITERAL_VISION_END]]", "<|vision_end|>"]
+    ].freeze
+
+    def self.escape(text, profile:, role: nil)
+      value = text.to_s
+      return value if value.empty? || !escapable_role?(role)
+
+      token_pairs_for(profile).reduce(value) do |memo, (placeholder, token)|
+        memo.gsub(token, placeholder)
+      end
+    end
+
+    def self.restore(text, profile:)
+      value = text.to_s
+      return value if value.empty?
+
+      token_pairs_for(profile).reduce(value) do |memo, (placeholder, token)|
+        memo.gsub(placeholder, token)
+      end
+    end
+
+    def self.restore_call(call, profile:)
+      call.each_with_object({}) do |(key, value), restored|
+        restored[key] = value.is_a?(String) ? restore(value, profile: profile) : value
+      end
+    end
+
+    def self.token_pairs_for(profile)
+      case profile.name
+      when "qwen36"
+        QWEN_TOKEN_PAIRS
+      else
+        GEMMA_TOKEN_PAIRS
+      end
+    end
+
+    def self.escapable_role?(role)
+      %w[user tool_response].include?(role.to_s)
+    end
+  end
+end

data/lib/samagotchi/recap_store.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+require_relative "session"
+
+module Samagotchi
+  # The idle recap saved with its session, in <session dir>/recap.json:
+  #   {text, covered, covered_digest, model, created_at}
+  # A separate file, so it never races the session-file save at the end of a
+  # turn. Follows the Engine's current session (the REPL can switch).
+  class RecapStore
+    FILE = "recap.json"
+    # A session card's or the picker's recap line.
+    PREVIEW_CHARS = 140
+    # "The user was testing…" / "The user and the assistant were exploring…":
+    # the recap prompt opens with the user's task this way, which spent ~30
+    # of a card's visible characters on the same words every time. Only a
+    # subject plus an -ing verb ("was testing") or a regular past tense
+    # ("explored"); not one that names a wish or a request ("asked the
+    # assistant to", "wanted"), which reads wrong without its subject.
+    # Irregular past tenses ("ran", "made") keep their subject.
+    NOT_STRIPPED = %w[asked wanted requested needed hoped preferred expected seemed].freeze
+    SUBJECT_RE = /\AThe user(?: and (?:the )?assistant)? (?:(?:was|were|is|are) (?=[a-z]+ing\b)|(?=[a-z]+ed\b)(?!(?:#{NOT_STRIPPED.join("|")})\b))/
+
+    # @param session_id_lookup [#call] the current session's id, or nil
+    # @param state_dir_lookup [#call] the state dir holding the sessions
+    def initialize(session_id_lookup:, state_dir_lookup:)
+      @session_id_lookup = session_id_lookup
+      @state_dir_lookup = state_dir_lookup
+    end
+
+    # @return [String, nil] the session the store reads and writes now
+    def key
+      @session_id_lookup.call
+    end
+
+    # @return [Hash, nil] the saved recap (symbol keys), nil when none
+    def load
+      id = key
+      id && self.class.read(Session.session_dir(id, state_dir: @state_dir_lookup.call))
+    end
+
+    # Write +state+ atomically. Skipped when the session file is gone (deleted,
+    # or discarded as empty), so this never recreates a removed session's dir.
+    def save(state)
+      id = key
+      return unless id
+
+      state_dir = @state_dir_lookup.call
+      return unless File.exist?(File.join(state_dir, "#{id}.json"))
+
+      dir = Session.session_dir(id, state_dir: state_dir)
+      FileUtils.mkdir_p(dir)
+      path = File.join(dir, FILE)
+      File.write("#{path}.tmp", JSON.generate(state))
+      File.rename("#{path}.tmp", path)
+    end
+
+    # Remove the saved recap (it no longer describes the session).
+    def delete
+      id = key
+      return unless id
+
+      FileUtils.rm_f(File.join(Session.session_dir(id, state_dir: @state_dir_lookup.call), FILE))
+    end
+
+    # @return [Hash, nil] the recap saved in +session_dir+, nil when there is
+    #   none or it can't be read
+    def self.read(session_dir)
+      data = JSON.parse(File.read(File.join(session_dir, FILE)), symbolize_names: true)
+      return nil unless data.is_a?(Hash) && !data[:text].to_s.strip.empty?
+
+      data
+    rescue StandardError
+      nil
+    end
+
+    # @return [String, nil] the first sentence of the recap saved in
+    #   +session_dir+, on one line, without the subject phrase (SUBJECT_RE)
+    #   and cut to PREVIEW_CHARS. The full recap keeps its sentence.
+    def self.preview(session_dir)
+      text = read(session_dir)&.dig(:text).to_s.gsub(/\s+/, " ").strip
+      return nil if text.empty?
+
+      first = text[/\A.*?[.!?](?=\s|\z)/] || text
+      first = first.sub(SUBJECT_RE, "").sub(/\A[a-z]/, &:upcase)
+      first.length > PREVIEW_CHARS ? "#{first[0, PREVIEW_CHARS - 1]}…" : first
+    end
+  end
+end

data/lib/samagotchi/reminder_store.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "securerandom"
+
+module Samagotchi
+  # Thread-safe store for periodic reminders registered by the agent.
+  #
+  # The agent registers reminders via the `register_reminder` tool during a
+  # turn. The `IdleReminders` detector thread polls this store to find due
+  # reminders and signals the Engine to auto-create a turn when one is due.
+  #
+  # The store is owned by the Engine and injected into KernelLoop so both
+  # loops (native and chat) use the same dispatch path for tool calls.
+  #
+  # Reminder lifecycle:
+  #   1. Agent calls register_reminder → store adds entry
+  #   2. IdleReminders detects due → sets @due_reminder_name on Engine
+  #   3. Engine#run_turn reads @due_reminder_name, injects [SYSTEM:] message
+  #   4. Agent acts on reminder → calls cancel_reminder → store removes entry
+  class ReminderStore
+    # @return [Hash{String => Hash}] id => {id:, name:, description:, interval_minutes:, next_fire_at:}
+    attr_reader :reminders
+
+    def initialize
+      @mutex = Monitor.new
+      @reminders = {}
+    end
+
+    # Register a new reminder.
+    # @param call [Hash] the tool call params (from the model)
+    # @return [String] confirmation message
+    def register(call)
+      name = (call[:name] || call[:content]).to_s.strip
+      description = (call[:description] || "").to_s.strip
+      interval = (call[:interval_minutes] || 1).to_i
+
+      return "Error: name is required" if name.empty?
+      return "Error: description is required" if description.empty?
+      return "Error: interval_minutes must be >= 1" if interval < 1
+      return "Error: interval_minutes must be <= 1440" if interval > 1440
+
+      id = SecureRandom.hex(6)
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @mutex.synchronize do
+        @reminders[name] = {
+          id: id,
+          name: name,
+          description: description,
+          interval_minutes: interval,
+          last_fire_at: now,
+          next_fire_at: now + (interval * 60)
+        }
+      end
+
+      "Reminder '#{name}' registered (interval: #{interval}m, id: #{id})."
+    end
+
+    # Cancel a reminder by name.
+    # @param name [String] the reminder name to cancel
+    # @return [String] result message
+    def cancel(name)
+      name = name.to_s.strip
+      @mutex.synchronize do
+        if @reminders.delete(name)
+          "Reminder '#{name}' canceled."
+        else
+          "Error: no such reminder '#{name}'."
+        end
+      end
+    end
+
+    # @return [Boolean] whether any reminder is registered
+    def any?
+      @mutex.synchronize { !@reminders.empty? }
+    end
+
+    # List all active reminders.
+    # @return [String] formatted list
+    def list
+      @mutex.synchronize do
+        return "No active reminders." if @reminders.empty?
+
+        lines = @reminders.map do |name, r|
+          "  #{r[:name]} (interval: #{r[:interval_minutes]}m, id: #{r[:id]})"
+        end
+        "Active reminders:\n" + lines.join("\n")
+      end
+    end
+
+    # Get all due reminders whose interval has elapsed.
+    # Returns an Array of {name:, description:, interval_minutes:} hashes.
+    # Called by Engine#maybe_inject_reminders (synchronously, at run_turn start).
+    # Thread-safe. Returns a frozen copy so the caller can't mutate internal state.
+    # @return [Array<Hash>] array of due reminder hashes (may be empty)
+    def due_reminders
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @mutex.synchronize do
+        @reminders.each_value.filter_map do |r|
+          next unless r[:next_fire_at] && now >= r[:next_fire_at]
+          { name: r[:name], description: r[:description], interval_minutes: r[:interval_minutes] }
+        end.freeze
+      end
+    end
+
+    # Get the name of the next due reminder (if any) whose interval has elapsed.
+    # Kept for backward compatibility with IdleReminders thread.
+    # @return [String, nil] the reminder name, or nil if none are due
+    def next_due_name
+      due = due_reminders
+      due.first&.fetch(:name)
+    end
+
+    # Mark a reminder as fired — resets its next_fire_at to now + interval.
+    # Called by Engine after a due reminder has been delivered.
+    # @param name [String] the reminder name
+    def mark_fired(name)
+      name = name.to_s.strip
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @mutex.synchronize do
+        r = @reminders[name]
+        if r
+          r[:last_fire_at] = now
+          r[:next_fire_at] = now + (r[:interval_minutes] * 60)
+        end
+      end
+    end
+
+    # Mark multiple reminders as fired — resets each next_fire_at to now + interval.
+    # Called by Engine after injecting multiple due reminders (batch operation).
+    # Thread-safe, single lock acquisition.
+    # @param names [Array<String>] reminder names to mark as fired
+    def mark_fired_batch(names)
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @mutex.synchronize do
+        names.each do |name|
+          name = name.to_s.strip
+          r = @reminders[name]
+          if r
+            r[:last_fire_at] = now
+            r[:next_fire_at] = now + (r[:interval_minutes] * 60)
+          end
+        end
+      end
+    end
+
+    # Get the description of a due reminder (for injection into the system prompt).
+    # Called by Engine during run_turn. Thread-safe.
+    # @param name [String] the reminder name
+    # @return [String, nil] the description, or nil if not found
+    def get_description(name)
+      name = name.to_s.strip
+      @mutex.synchronize do
+        r = @reminders[name]
+        r[:description] if r
+      end
+    end
+
+    # Clear all reminders.
+    # Called when the session ends or the engine is reset.
+    def clear_all
+      @mutex.synchronize { @reminders.clear }
+    end
+  end
+end

data/lib/samagotchi/self_report.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "version"
+require_relative "config"
+require_relative "context_window"
+require_relative "session"
+require_relative "log_path"
+require_relative "model_profile"
+require_relative "served_model"
+require_relative "host_registry"
+require_relative "tools/memory"
+require_relative "hooks/loader"
+require_relative "memory_bundle/provenance"
+require_relative "memory_bundle/manifest"
+require_relative "memory_bundle/system_bundle"
+require_relative "desktop"
+
+module Samagotchi
+  # `chi self`: where this chi lives and what it is configured to use.
+  #
+  # Read-only and nearly offline (one short /props GET for the served model,
+  # nothing else asks a model server), so the agent can run it via `execute`
+  # to orient itself — source dir to rg, config path, memory dirs, sessions,
+  # model/host, bundle versions — without guessing from $PATH.
+  module SelfReport
+    SOURCE_DIR = File.expand_path("../..", __dir__)
+
+    module_function
+
+    def text(env: ENV)
+      rows = fields(env: env)
+      width = rows.map { |label, _| label.length }.max
+      rows.map { |label, value| "#{label.ljust(width)}  #{value}" }.join("\n")
+    end
+
+    def fields(env: ENV)
+      model = model_name
+      [
+        ["version", "#{VERSION} (ruby #{RUBY_VERSION})"],
+        ["source", "#{SOURCE_DIR} (#{install_kind})"],
+        ["config", with_presence(ConfigFile.global_path(env: env))],
+        ["hooks dir", hooks_dir(env)],
+        ["memories", Tools::MemoryRead.memories_dir("system", env: env)],
+        ["project memories", Tools::MemoryRead.memories_dir("project", env: env)],
+        ["sessions", Session.default_state_dir(env: env)],
+        ["log", log_path(env)],
+        ["model", model || "(not configured)"],
+        ["host", model ? host_for(model, env) : "-"],
+        ["api key", model ? api_key_for(model, env) : "-"],
+        ["loop", model ? loop_for(model, env) : "-"],
+        ["profile", model ? profile_for(model, env) : "-"],
+        ["served model", model ? served_model_for(model, env) : "-"],
+        ["context window", context_window(env)],
+        ["bundles", bundles_summary],
+        ["desktop", desktop_summary(env)]
+      ]
+    end
+
+    # "git checkout" when running from a repo (bin/chi), "installed gem" when
+    # under a gem path; the installed gem's files are not meant to be edited.
+    def install_kind(dir = SOURCE_DIR)
+      return "git checkout" if File.exist?(File.join(dir, ".git"))
+      return "installed gem" if Gem.path.any? { |p| dir.start_with?(File.join(p, "gems") + File::SEPARATOR) }
+
+      "directory"
+    end
+
+    # The debug log every chi process appends to (LogPath): the sessions
+    # dir's sibling by default, so a chi that wants to read its own trail
+    # doesn't guess ~/.local/state.
+    def log_path(env)
+      LogPath.resolve(env: env) || "(disabled: log.disable)"
+    end
+
+    def with_presence(path)
+      File.exist?(path) ? path : "#{path} (missing)"
+    end
+
+    def hooks_dir(env)
+      data = ConfigFile.read_yaml(path: ConfigFile.global_path(env: env))
+      configured = data.is_a?(Hash) && data["hooks"].is_a?(Hash) ? data["hooks"]["hooks_dir"] : nil
+      Hooks::Loader.expand_path(configured || Hooks::Loader.default_hooks_dir(env), env)
+    end
+
+    # Offline, so only the fallback: the running server's n_ctx wins at runtime.
+    def context_window(env)
+      window = ContextWindow.configured(env: env)
+      "#{window.tokens} (#{window.source}; the server's n_ctx wins at runtime)"
+    end
+
+    def model_name
+      ModelProfile.required_model_name
+    rescue ArgumentError
+      nil
+    end
+
+    # Routed without model discovery, so an unqualified name may land on
+    # another host at runtime after /models.
+    def loop_for(model, env)
+      entry, = HostRegistry.new(env: env).host_for_model(model)
+      return "-" unless entry
+
+      entry.chat? ? "chat (api: openai)" : "native (raw prompt)"
+    end
+
+    # chi self's one server call: a single-model llama.cpp answers any name
+    # with the model it loaded, and its /props names it (model_alias). One
+    # GET with the probe's short timeouts; a remote host isn't asked.
+    def served_model_for(model, env)
+      registry = HostRegistry.new(env: env)
+      entry, bare = registry.host_for_model(model)
+      return "-" unless entry
+      return "reported per turn (remote host)" if entry.remote?
+
+      client = registry.client_for(entry)
+      props = client.server_props(model: bare) if client.respond_to?(:server_props)
+      return "reported per turn (the server has no /props)" if props.nil?
+
+      served = ServedModel.from_props(props)
+      return "unknown (no answer from the server's /props)" unless served
+
+      ServedModel.differs?(bare, served) ? "#{served} (not #{bare}: the server serves its own model)" : served
+    rescue StandardError => e
+      "unknown (#{e.class})"
+    end
+
+    # Offline, so no /props probe: where nothing is configured, a native
+    # llama.cpp host's chat template decides at runtime.
+    def profile_for(model, env)
+      registry = HostRegistry.new(env: env)
+      entry, bare = registry.host_for_model(model)
+      return "name-based (chat API: only strips thoughts)" if entry&.chat?
+
+      # As typed, the part after a host prefix (maybe an alias), alias-resolved, bare.
+      names = [model, registry.parse_qualified_model(model).last, ConfigFile.resolve_model_alias(model, env: env), bare]
+      override = Config.resolve_with_origin("model.profile", env: env, cli_overrides: Config.cli_overrides)
+      result = ModelProfile.resolve(names: names, entry: entry, client: nil, bare_model: bare, override: override,
+                                    models: ConfigFile.model_settings(env: env))
+      name = result.profile.name
+      case result.source
+      when :config then "#{name} (config #{result.detail})"
+      when :cli, :env then "#{name} (#{result.source})"
+      else
+        return "#{name} (#{result.source})" unless entry.nil? || entry.transport.nil? || entry.transport == :llama_cpp
+
+        given = result.source == :name ? "name says #{name}" : "default #{name}"
+        "from the server at runtime (#{given})"
+      end
+    end
+
+    def host_for(model, env)
+      entry, bare = HostRegistry.new(env: env).host_for_model(model)
+      return "(no hosts configured)" unless entry
+
+      suffix = bare && bare != model ? " as #{bare}" : ""
+      location = entry.url || "#{entry.host}:#{entry.port}"
+      "#{entry.name} #{location}#{suffix}"
+    end
+
+    # The variable the host's API key comes from and whether it is set; the
+    # key itself is never shown.
+    def api_key_for(model, env)
+      entry, = HostRegistry.new(env: env).host_for_model(model)
+      name = entry&.api_key_env
+      return "-" unless name
+
+      "#{name} (#{env[name].to_s.empty? ? "unset" : "set"})"
+    end
+
+    # The Chi Helper app's version against this chi's (read from its
+    # Info.plist; no process or Services checks: chi desktop status has those).
+    def desktop_summary(env)
+      return "- (macOS only)" unless Desktop.supported?
+
+      version = Desktop::MacOS.new(env: env).app_version
+      return "not installed" unless version
+
+      version == VERSION ? "#{version} (matches)" : "#{version} (chi is #{VERSION}: chi desktop upgrade)"
+    end
+
+    # "samagotchi-system 0.1.5 (shipped 0.1.5), other 1.0.0"
+    def bundles_summary
+      shipped = MemoryBundle::Manifest.read(dir: MemoryBundle::SystemBundle::GEM_BUNDLE_DIR).version rescue nil
+      installed = Dir[File.join(MemoryBundle::Provenance.bundles_dir, "*", "manifest.json")].sort.map do |path|
+        name = File.basename(File.dirname(path))
+        version = (JSON.parse(File.read(path))["version"] rescue nil) || "?"
+        label = "#{name} #{version}"
+        label += " (shipped #{shipped})" if name == MemoryBundle::SystemBundle::BUNDLE_NAME
+        label
+      end
+      installed.empty? ? "(none installed; shipped system bundle #{shipped || "?"})" : installed.join(", ")
+    end
+  end
+end