samagotchi 0.131.0 → 0.133.0

data/lib/samagotchi/plugin/context.rb

@@ -8,6 +8,7 @@ require_relative "../session_metrics/usage"
 require_relative "../guardrails/context"
 require_relative "../hook_question"
 require_relative "../idle_client"
+require_relative "../cache_confirm"
 require_relative "service"
 require_relative "side_question"
 
@@ -58,10 +59,15 @@ module Samagotchi
     # plugin handler: +handler+) until the turn has ended.
     # +cost+ returns the session's spend now (SessionMetrics::Cost),
     # +usage+ its work now (SessionMetrics::Usage).
+    # +cache_confirm+ takes (line, changed) and returns a
+    # CacheConfirm::Confirm when the change must ask first (CacheConfirm.ask
+    # with cost :full), else nil. +model_names+ returns the names the
+    # session's model is looked up under (EffectiveModel#names).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
-                      :cancel_controller, :cost, :usage, :turn_author, keyword_init: true)
+                      :cancel_controller, :cost, :usage, :turn_author, :cache_confirm, :model_names,
+                      keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -164,6 +170,14 @@ module Samagotchi
       #   current_model_only names it
       def model_key = @host.model_key&.call
 
+      # The names the session's model is looked up under now, as chi's own
+      # per-model config is (models: maps, ConfigFile.model_setting): as
+      # typed (an alias), the alias's target, the resolved ref ("host:id"),
+      # without the host, the bare id the host serves; deduped, first the
+      # most specific. Compare them downcased, first hit, as chi does.
+      # @return [Array<String>] frozen; [] when the model doesn't resolve
+      def model_names = Array(@host.model_names&.call).map(&:to_s).freeze
+
       # @return [SessionMetrics::Cost] the session's spend so far, read now:
       #   #total, #reported, #estimated, #side (Float USD) and #known?
       #   (docs/plugins.md); zero and known with no session
@@ -215,6 +229,25 @@ module Samagotchi
         Array(@host.load_tools&.call(names.map(&:to_s), @bundle))
       end
 
+      # Whether a change the plugin's command is about to make (its prompt
+      # section's text: chi.prompt_changed!) must ask first. nil: apply it
+      # now (nothing changes, no model reply yet, a sender no one answers
+      # for: chi send, a delegate, chi -p, the line had --yes, or not
+      # inside a command). Else a CacheConfirm::Confirm: change nothing and
+      # return [text, confirm] from the command, so the TUI prefills the
+      # line and the web shows Apply (it sends +line+ with --yes). The cost
+      # is a full re-read (the section is in the system prompt's stable
+      # part); the text says how big and, on api: anthropic, that preserved
+      # thinking is dropped.
+      # @param line [String] the command line that applies it, without --yes
+      # @param changed [Boolean] whether the section's text would change
+      # @return [CacheConfirm::Confirm, nil]
+      def cache_confirm(line, changed:)
+        return nil unless CacheConfirm.asking?
+
+        @host.cache_confirm&.call(line.to_s, changed ? true : false)
+      end
+
       # Whether the session is a `chi scratch` one (deleted when it ends).
       def scratch? = !!@host.scratch&.call
 

data/lib/samagotchi/plugin/loader.rb

@@ -20,9 +20,12 @@ module Samagotchi
     # +init+ adds a chi.init task (Engine#add_init_task); +toolkits+ is the
     # Engine's list of the plugins' toolkits (chi.toolkit: Toolkit::Kit);
     # +tool_index+ the Engine's Tools::ToolIndex (chi.tool_source);
-    # +peer_sources+ the Engine's PeerSources (chi.peer_source).
+    # +peer_sources+ the Engine's PeerSources (chi.peer_source);
+    # +prompt_sections+ the Engine's PromptSections (chi.prompt_section),
+    # +prompt_changed+ rebuilds its system prompts (chi.prompt_changed!).
     Registries = Struct.new(:commands, :tools, :hooks, :context_for, :tools_changed, :services, :stage_tools, :init,
-                            :toolkits, :tool_index, :peer_sources, keyword_init: true)
+                            :toolkits, :tool_index, :peer_sources, :prompt_sections, :prompt_changed,
+                            keyword_init: true)
 
     # Loads installed bundles' plugins (manifest plugin: {file:, sha256:})
     # into an Engine's registries (docs/plugins.md).

data/lib/samagotchi/plugin/prompt_sections.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "../log"
+require_relative "../toolkit"
+
+module Samagotchi
+  module Plugin
+    # The system-prompt text plugins add (chi.prompt_section): one per
+    # (bundle, name), each a block given the plugin's Context that returns
+    # a String or nil (no section). SystemPrompt runs them inside a build
+    # only (lazy, once per build key until a reset), never per request, on
+    # whatever thread builds: a block must be quick and thread-safe.
+    #
+    # Prompt-cache contract (docs/internals/prompt-caching.md): sections go
+    # sorted by (bundle, name), so the text is the same for the same
+    # inputs. A block that raises, returns something other than a String
+    # or nil, or text over MAX characters keeps the section's last good
+    # text for this session (a skip on a transient error would break the
+    # cache twice), with one warn; with no good text yet the section is
+    # left out.
+    class PromptSections
+      # As a kit prompt's (Toolkit::PROMPT_MAX): a cached prefix, not a document.
+      MAX = Toolkit::PROMPT_MAX
+      NAME = /\A[a-z][a-z0-9_-]{0,31}\z/
+
+      Section = Data.define(:bundle, :name, :block, :context)
+
+      # A section as one build holds it.
+      Built = Data.define(:bundle, :name, :text) do
+        # "From <bundle> (<name>):\n<text>", as the prompt has it.
+        def prompt_text = "From #{bundle} (#{name}):\n#{text}"
+
+        # /stats' record (Engine#stats_snapshot's prompt_sections).
+        def to_stats = { bundle: bundle, name: name }
+      end
+
+      def initialize
+        @sections = []
+        @mutex = Mutex.new
+        # [session id, bundle, name] => the last good text (nil: none)
+        @last_good = {}
+        @warned = Set.new
+      end
+
+      # @raise [ArgumentError] a (bundle, name) already added
+      def add(bundle:, name:, context:, &block)
+        @mutex.synchronize do
+          if @sections.any? { |section| section.bundle == bundle && section.name == name }
+            raise ArgumentError, "prompt section #{name} is registered twice (bundle #{bundle})"
+          end
+
+          @sections << Section.new(bundle: bundle.to_s, name: name.to_s, block: block, context: context)
+          @sections.sort_by! { |section| [section.bundle, section.name] }
+        end
+        nil
+      end
+
+      # @return [Boolean]
+      def any? = @mutex.synchronize { @sections.any? }
+
+      # Whether +bundle+ already has a section +name+.
+      def registered?(bundle, name)
+        @mutex.synchronize { @sections.any? { |section| section.bundle == bundle.to_s && section.name == name.to_s } }
+      end
+
+      # Run every block for +session_id+ and keep what they gave.
+      # @param session_id [String, nil] whose last good text a failure keeps
+      # @return [Array<Built>] in prompt order, the sections with text
+      def render(session_id)
+        sections = @mutex.synchronize { @sections.dup }
+        sections.filter_map do |section|
+          text = evaluate(section, session_id)
+          Built.new(bundle: section.bundle, name: section.name, text: text) if text
+        end
+      end
+
+      # The prompt text of +built+ (#render), nil without any.
+      # @param built [Array<Built>]
+      # @return [String, nil]
+      def self.text(built)
+        built.empty? ? nil : built.map(&:prompt_text).join("\n\n")
+      end
+
+      private
+
+      def evaluate(section, session_id)
+        key = [session_id, section.bundle, section.name]
+        value = section.block.call(section.context)
+        problem = problem_of(value)
+        if problem
+          keep_last_good(section, key, problem)
+        else
+          text = value.nil? ? nil : value.strip.freeze
+          text = nil if text && text.empty?
+          @mutex.synchronize { @last_good[key] = text }
+          text
+        end
+      rescue StandardError => e
+        keep_last_good(section, key, "#{e.class}: #{e.message}")
+      end
+
+      def problem_of(value)
+        return nil if value.nil?
+        return "returned #{value.class}, not a String or nil" unless value.is_a?(String)
+
+        "is over #{MAX} characters" if value.strip.length > MAX
+      end
+
+      # One warn per section, session and problem; the last good text, or nil.
+      def keep_last_good(section, key, problem)
+        kept = @mutex.synchronize do
+          first = @warned.add?([*key, problem])
+          [@last_good[key], first]
+        end
+        text, first = kept
+        if first
+          Log.warn(:plugins, "prompt_section_failed", bundle: section.bundle, section: section.name,
+                                                      error: problem.to_s[0, 200], kept: !text.nil?)
+        end
+        text
+      end
+    end
+  end
+end

data/lib/samagotchi/project_env.rb

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require_relative "chi_home"
+require_relative "chi_shim"
+require_relative "config"
+require_relative "log"
+require_relative "log_line"
+require_relative "log_path"
+require_relative "paths"
+
+module Samagotchi
+  # Tools follow the project: a spawned worker computes its session folder's
+  # `mise env` once, at boot (#compute), and the commands it starts for the
+  # session (execute, task_create, `!cmd`, MCP servers, context sources) get
+  # it merged into their env (#current's Overlay#env), so they see the
+  # project's Ruby, node, … whoever started the worker (a terminal on another
+  # Ruby, chi web, the macOS helper under launchd). The worker's own process
+  # never takes it: its ENV stays the spawner's, so the project can't reach
+  # chi's own settings, keys, proxies or dirs (LLM calls, HostKeys, Config,
+  # Paths, hooks, plugins). A pair turn's tools don't get it either. A
+  # mise.toml edit reaches a session at its next worker (`chi sessions
+  # restart`). The REPL modes run no worker and keep the shell's env.
+  # docs/sessions.md (Project env).
+  #
+  # And `chi` inside those tools stays the chi home's (ChiShim): the project's
+  # PATH would otherwise find the project Ruby's chi (an old one, or none).
+  module ProjectEnv
+    # What the worker computed, for `chi self` (it runs in a tool, not in
+    # the worker): "mise:<ruby realpath>" or "none:<reason>". Tools only;
+    # never a child worker's (ChildEnv).
+    MARKER_ENV = "SAMAGOTCHI_PROJECT_ENV"
+    # The mise a worker runs, and only that path when set (specs point it at
+    # a missing file: the developer's own mise is never asked).
+    MISE_CLI_ENV = "SAMAGOTCHI_MISE_CLI"
+    # In the tools' env: the worker's own value (or null for unset) of each
+    # key the overlay changes, JSON. A chi a tool runs (bin/chi, through the
+    # shim or not) takes those values back first thing (#take_orig!), so
+    # its own process (API keys, proxies) and the workers it starts (`chi
+    # send --new --dir B`) never run on project A's env. A forged one can
+    # only set what that tool could set on chi itself; #restore_env never
+    # sets a reserved key or a loader variable (RESTORE_NEVER).
+    ORIG_ENV = "SAMAGOTCHI_PROJECT_ENV_ORIG"
+    # mise's own shell-session state (and any other __MISE_*): never passed
+    # to `mise env`, never taken from its answer, unset in the tools' env
+    # (they describe the shell mise was activated in).
+    MISE_STATE = %w[__MISE_DIFF __MISE_SESSION __MISE_ORIG_PATH MISE_SHELL].freeze
+    GEM_KEYS = %w[GEM_HOME GEM_PATH].freeze
+    # Keys the tools' overlay never sets: a `chi` a tool runs (the shim's)
+    # reads its config, state and log dirs, its settings and the machine its
+    # session commands go to (CHI_REMOTE) from them, and the test-run flags.
+    # Dropped, with one warning.
+    RESERVED_KEYS = %w[HOME RACK_ENV CI CHI_REMOTE].freeze
+    RESERVED_PREFIXES = %w[XDG_ SAMAGOTCHI_].freeze
+    # Never set from an ORIG_ENV record (a tool can write it), only unset:
+    # loader and Bundler variables.
+    RESTORE_NEVER = /\A(?:DYLD_|LD_|RUBYOPT\z|RUBYLIB\z|RUBYGEMS_|BUNDLE)/
+    # Never passed to `mise env`: MISE_YES answers its trust prompt (it
+    # would trust, and remember, an untrusted repo's mise.toml); CI too.
+    MISE_UNSET = %w[MISE_YES CI].freeze
+    TIMEOUT = 5
+    # What execute and tasks set themselves (Tools::TaskRuntime's
+    # sanitized env): never taken from the project's.
+    TOOLS_DROP = %w[RUBYOPT RUBYLIB BUNDLE_GEMFILE BUNDLE_BIN_PATH BUNDLER_VERSION].freeze
+
+    # What #compute found: +env+ the tools' overlay ({key => value, or nil
+    # to unset}; frozen, with the marker and the ORIG_ENV record),
+    # +applied+ whether mise answered, +reason+ why not (a short token, the
+    # marker's and the warning's), +ruby+ the first `ruby` on the tools'
+    # PATH (realpath) or nil.
+    Overlay = Data.define(:env, :applied, :reason, :ruby) do
+      def marker = applied ? "mise:#{ruby || "no ruby"}" : "none:#{reason}"
+    end
+    # No project env: specs, the REPL modes, a worker before #install!.
+    NONE = Overlay.new(env: {}.freeze, applied: false, reason: "none", ruby: nil)
+
+    class Failed < StandardError; end
+
+    # chi home doctor's row when session.project_env is mise and no mise is found.
+    NO_MISE = "project env: no mise found (home.json's, PATH, /opt/homebrew/bin, /usr/local/bin, ~/.local/bin): " \
+              "tools run in the env of whoever starts the worker; install mise, or set session.project_env: off"
+    # How much of the debug log's end chi home doctor reads for #last_warning.
+    LOG_TAIL_BYTES = 4 * 1024 * 1024
+
+    # A worker's `project_env` warning from the debug log (#last_warning).
+    Warning = Data.define(:ts, :sid, :dir, :reason, :error) do
+      # chi home doctor's row: what failed and what to run.
+      def message
+        detail = error.to_s.start_with?("#{reason}:") ? error : [reason, error].compact.reject(&:empty?).join(": ")
+        fix = error.to_s.include?("mise trust") || error.to_s.include?("not trusted") ? "mise trust in #{dir}" : "fix that"
+        restart = sid ? "chi sessions restart #{sid}" : "chi sessions restart ID"
+        "the last worker in #{dir} (#{ts}) got no project env (#{detail}): #{fix}, then #{restart}"
+      end
+    end
+
+    @current = NONE
+
+    module_function
+
+    # The overlay this process's tools get: the worker's, set once at boot
+    # (#install!); NONE elsewhere.
+    # @return [Overlay]
+    def current = @current
+
+    # Only from SessionManager.run_session_loop, in a spawned worker.
+    def install!(overlay) = @current = overlay
+
+    # #current's env for a tool's spawn, less what every tool runs without
+    # (Tools::TaskRuntime::SANITIZED_ENV_KEYS: RUBYOPT, RUBYLIB, Bundler's).
+    # @return [Hash{String=>String, nil}]
+    def tools_env = current.env.except(*TOOLS_DROP)
+
+    # Specs: back to NONE.
+    def reset! = @current = NONE
+
+    # The tools' overlay for the session folder +dir+, from +env+ (the
+    # worker's ENV, read, never written).
+    # @param dir [String] the session's working_directory
+    # @param mode [String] session.project_env: "mise" or "off"
+    # @param home [ChiHome::Record, nil] the chi home (the shim's)
+    # @param runner [#call] (env, argv, timeout:) → stdout (+env+ is the child's whole env); raises Failed
+    # @return [Overlay]
+    def compute(dir, env: ENV, mode: configured_mode, home: ChiHome.current, cwd: Dir.pwd,
+                runner: method(:run_mise), shim_dir: ChiShim.dir(env: env), timeout: TIMEOUT)
+      base = env.to_h.dup
+      tools = base.dup
+      applied, reason = mise_overlay(dir, tools, mode: mode, cwd: cwd, runner: runner, timeout: timeout)
+      prepend_shim(tools, home: home, shim_dir: shim_dir)
+      overlay = Overlay.new(env: {}, applied: applied, reason: reason, ruby: applied ? ruby_on(tools["PATH"]) : nil)
+      changes = diff(base, tools)
+      changes[ORIG_ENV] = JSON.generate(changes.keys.to_h { |key| [key, base[key]] }) unless changes.empty?
+      changes[MARKER_ENV] = overlay.marker
+      overlay.with(env: changes.freeze)
+    end
+
+    # Applies the mise env to +tools+ (a copy of the worker's env).
+    # @return [Array(Boolean, String)] applied, reason
+    def mise_overlay(dir, tools, mode:, cwd:, runner:, timeout:)
+      return skipped("off") if mode == "off"
+      return skipped("no_dir") if dir.to_s.empty?
+      return skipped("cwd_mismatch", warn: { dir: dir, cwd: cwd }) unless same_dir?(dir, cwd)
+
+      mise = find_mise(env: tools)
+      return skipped("no_mise") unless mise
+
+      answer = parse(runner.call(mise_env(tools), [mise, "env", "-C", dir, "--json"], timeout: timeout))
+      answer = without_reserved(answer, dir)
+      before = ruby_on(tools["PATH"])
+      tools.delete_if { |key, _| mise_state?(key) }
+      tools.update(answer)
+      drop_gem_env(tools, answer, before, ruby_on(tools["PATH"]))
+      [true, nil]
+    rescue Failed => e
+      skipped(e.message.split(":", 2).first, warn: { dir: dir, error: e.message })
+    end
+
+    # {key => new value, or nil for a removed key} between +before+ and +after+.
+    def diff(before, after)
+      changed = (before.keys | after.keys).reject { |key| before[key] == after[key] }
+      changed.to_h { |key| [key, after[key]] }
+    end
+
+    # #ORIG_ENV of +env+: {key => value or nil}; {} without one (or one that
+    # isn't its shape). Reserved keys never come back; a RESTORE_NEVER key
+    # only as an unset (project A's LD_LIBRARY_PATH goes, nothing comes).
+    # @return [Hash{String=>String, nil}]
+    def restore_env(env = ENV)
+      data = JSON.parse(env[ORIG_ENV].to_s)
+      return {} unless data.is_a?(Hash)
+
+      data.select do |key, value|
+        next false unless key.is_a?(String) && !reserved?(key)
+
+        value.nil? || (value.is_a?(String) && !key.match?(RESTORE_NEVER))
+      end
+    rescue JSON::ParserError
+      {}
+    end
+
+    # bin/chi, before anything reads config: +env+ back to the worker's
+    # values (#restore_env), the record taken out. The marker stays (chi
+    # self reads it).
+    def take_orig!(env = ENV)
+      restore_env(env).each { |key, value| value.nil? ? env.delete(key) : env[key] = value }
+      env.delete(ORIG_ENV)
+    end
+
+    def reserved?(key) = RESERVED_KEYS.include?(key) || key.start_with?(*RESERVED_PREFIXES)
+
+    # +answer+ without RESERVED_KEYS/RESERVED_PREFIXES, warned once by name.
+    def without_reserved(answer, dir)
+      dropped = answer.keys.select { |key| reserved?(key) }
+      Log.warn(:worker, "project_env_reserved", dir: dir, keys: dropped.sort.join(",")) unless dropped.empty?
+      answer.except(*dropped)
+    end
+
+    # The first one found: SAMAGOTCHI_MISE_CLI when set (that path only),
+    # else home.json's mise, else PATH and the usual dirs (ChiHome.find_mise).
+    # @return [String, nil]
+    def find_mise(env: ENV)
+      cli = env[MISE_CLI_ENV].to_s
+      return (executable?(cli) ? cli : nil) unless cli.empty?
+
+      home_mise = home_json_mise(env)
+      return home_mise if home_mise && executable?(home_mise)
+
+      ChiHome.find_mise(env: env)
+    end
+
+    # The GEM_* rule: the spawner's GEM_HOME/GEM_PATH are its Ruby's; when
+    # the project env moves `ruby` to another one (or exactly one of the two
+    # is a mise shim) they are dropped, unless mise sets them itself. Neither
+    # resolving keeps them.
+    def drop_gem_env(env, answer, before, after)
+      return if before.nil? && after.nil?
+      return unless before != after || (mise_shim?(before) ^ mise_shim?(after))
+
+      GEM_KEYS.each { |key| env.delete(key) unless answer.key?(key) }
+    end
+
+    # The realpath of the first executable `ruby` on +path+, or nil.
+    def ruby_on(path)
+      path.to_s.split(File::PATH_SEPARATOR).each do |dir|
+        next if dir.empty?
+
+        file = File.join(dir, "ruby")
+        return File.realpath(file) if File.file?(file) && File.executable?(file)
+      rescue SystemCallError
+        next
+      end
+      nil
+    end
+
+    def mise_shim?(real) = !real.nil? && File.basename(real) == "mise"
+
+    # PATH with the shim's dir first (once), when there is a home to shim.
+    def prepend_shim(env, home:, shim_dir:)
+      return unless home && ChiShim.ensure!(home, dir: shim_dir)
+
+      dirs = env["PATH"].to_s.split(File::PATH_SEPARATOR).reject { |dir| dir.empty? || dir == shim_dir }
+      env["PATH"] = [shim_dir, *dirs].join(File::PATH_SEPARATOR)
+    end
+
+    # @return [Hash{String=>String}]
+    # @raise [Failed]
+    def parse(stdout)
+      data = JSON.parse(stdout.to_s)
+      raise Failed, "bad_json: not an object" unless data.is_a?(Hash)
+
+      data.select { |key, value| key.is_a?(String) && value.is_a?(String) && !mise_state?(key) }
+    rescue JSON::ParserError => e
+      raise Failed, "bad_json: #{e.message.lines.first.to_s.strip[0, 120]}"
+    end
+
+    # The whole env `mise env` runs with (nothing else inherited): the
+    # worker's, less mise's shell state (an activated shell's __MISE_DIFF
+    # would make it answer relative to that shell) and MISE_UNSET (its
+    # MISE_TRUSTED_CONFIG_PATHS stays: the user's own trust list).
+    def mise_env(env) = env.to_h.reject { |key, _| mise_state?(key) || MISE_UNSET.include?(key) }
+
+    def mise_state?(key) = key.start_with?("__MISE_") || MISE_STATE.include?(key)
+
+    # @return [String] stdout
+    # @raise [Failed]
+    def run_mise(child_env, argv, timeout:)
+      Open3.popen3(child_env, *argv, pgroup: true, unsetenv_others: true) do |stdin, out, err, wait|
+        stdin.close
+        readers = [out, err].map { |io| Thread.new { io.read }.tap { |t| t.report_on_exception = false } }
+        unless wait.join(timeout)
+          kill_group(wait.pid)
+          wait.join(1)
+          readers.each { |reader| reader.join(1) }
+          raise Failed, "mise_timeout: no answer in #{timeout} s"
+        end
+        readers.each { |reader| reader.join(1) }
+        stdout, stderr = readers.map { |reader| reader.alive? ? "" : reader.value.to_s }
+        status = wait.value
+        raise Failed, "mise_failed: exit #{status.exitstatus}: #{brief(stderr)}" unless status.success?
+
+        stdout
+      end
+    rescue SystemCallError => e
+      raise Failed, "mise_failed: #{e.message}"
+    end
+
+    def kill_group(pid)
+      Process.kill("KILL", -pid)
+    rescue SystemCallError
+      nil
+    end
+
+    # mise's stderr in one line, without its noise ("mise ERROR Config files
+    # in … are not trusted. / Trust them with `mise trust`…").
+    MISE_NOISE = /\AVersion:|--verbose|MISE_VERBOSE/
+    def brief(text)
+      text.to_s.lines.map { |line| line.strip.delete_prefix("mise ERROR ").strip }
+          .reject { |line| line.empty? || line.match?(MISE_NOISE) }.join(" / ")[0, 600]
+    end
+
+    # @return [Array(false, String)]
+    def skipped(reason, warn: nil)
+      Log.warn(:worker, "project_env", reason: reason, **warn) if warn
+      [false, reason]
+    end
+
+    def same_dir?(dir, cwd)
+      !dir.to_s.empty? && ChiHome.real(dir) == ChiHome.real(cwd)
+    end
+
+    def executable?(file) = File.file?(file) && File.executable?(file)
+
+    def home_json_mise(env)
+      ChiHome.read(path: ChiHome.path(env: env))&.mise
+    rescue ChiHome::Invalid
+      nil
+    end
+
+    # The newest worker record in the debug log for one of the folders
+    # +dirs+ (a folder and the ones above it in its project), when it is a
+    # `project_env` warning (an untrusted mise.toml, a timeout); nil when
+    # the newest is `project_env_applied`, there is none, or the log can't
+    # be read. Reads the log's last LOG_TAIL_BYTES only.
+    # @return [Warning, nil]
+    def last_warning(dirs, log_path: LogPath.resolve)
+      return nil unless log_path && File.file?(log_path)
+
+      want = Array(dirs).map { |dir| ChiHome.real(dir) }
+      newest = {}
+      each_tail_record(log_path) do |record|
+        next unless record.tag == "worker" && %w[project_env project_env_applied].include?(record.event)
+
+        dir = record.fields["dir"]
+        newest[ChiHome.real(dir)] = record if dir && want.include?(ChiHome.real(dir))
+      end
+      found = newest.values.select { |record| record.event == "project_env" }.max_by(&:ts)
+      return nil unless found
+
+      Warning.new(ts: found.ts, sid: found.sid, dir: Paths.tilde(found.fields["dir"]),
+                  reason: found.fields["reason"], error: found.fields["error"])
+    rescue SystemCallError
+      nil
+    end
+
+    def each_tail_record(log_path, &)
+      File.open(log_path, "rb") do |io|
+        size = io.size
+        io.seek([size - LOG_TAIL_BYTES, 0].max)
+        io.gets if size > LOG_TAIL_BYTES # a torn first line
+        LogLine.each_record(io, &)
+      end
+    end
+
+    def configured_mode
+      Config.get("session.project_env").to_s
+    rescue StandardError
+      "mise"
+    end
+  end
+end

data/lib/samagotchi/run_options.rb

@@ -210,6 +210,7 @@ module Samagotchi
                  chi toolkit report [--days N]   grade toolkit suggestions against the tools sessions used
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host
+                 chi home [set [--ruby PATH] | doctor]   the Ruby every chi launch boots
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME
                  chi --remote NAME <send|answer|note|context|sessions|share|review> …   those commands on that machine (or CHI_REMOTE=NAME)
                  chi --remote NAME --attach ID | --resume ID | --dir DIR [-p TEXT]   a session on that machine, in this terminal

data/lib/samagotchi/self_report.rb

@@ -24,6 +24,8 @@ require_relative "memory_bundle/index_size"
 require_relative "desktop"
 require_relative "live_versions"
 require_relative "web/lan"
+require_relative "chi_home"
+require_relative "project_env"
 
 module Samagotchi
   # `chi self`: where this chi lives and what it is configured to use.
@@ -50,6 +52,8 @@ module Samagotchi
       [
         ["version", "#{VERSION} (ruby #{RUBY_VERSION})"],
         ["source", "#{SOURCE_DIR} (#{install_kind})"],
+        ["home", home_summary(env)],
+        ["project env", project_env_summary(env)],
         ["config", with_presence(ConfigFile.global_path(env: env))],
         ["hooks dir", hooks_dir(env)],
         ["memories", Tools::MemoryRead.memories_dir("system", env: env)],
@@ -414,6 +418,35 @@ module Samagotchi
       helper.stale? ? "#{version} (chi is #{VERSION}: chi update)" : "#{version} (up to date for chi #{VERSION})"
     end
 
+    # The chi home (home.json): its ruby and newest chi, and whether this
+    # chi (the one answering) runs on it.
+    def home_summary(env)
+      home = ChiHome.read(path: ChiHome.path(env: env))
+      return "none (chi home set records one)" unless home
+
+      problem = ChiHome.problem(home)
+      return "#{home.ruby} (unusable: #{problem})" if problem
+
+      label = "#{home.ruby} (chi #{home.newest_version})"
+      return "#{label}; this chi is a source checkout" unless InstalledGem.spec
+      return label if home.running_here?
+
+      "#{label}; this chi runs on #{RbConfig.ruby}"
+    rescue ChiHome::Invalid => e
+      "(invalid: #{e.message})"
+    end
+
+    # What this session's worker took from the project (ProjectEnv's marker,
+    # exported to the tools it runs): "mise (ruby PATH)" or "none (why)".
+    def project_env_summary(env)
+      kind, detail = env[ProjectEnv::MARKER_ENV].to_s.split(":", 2)
+      case kind
+      when "mise" then "mise (ruby #{detail})"
+      when "none" then "none (#{detail})"
+      else "- (not run by a session's worker)"
+      end
+    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

data/lib/samagotchi/session_access/contract.rb

@@ -26,7 +26,7 @@ module Samagotchi
       # bin/chi subcommands that act on this machine: never sessions. chi
       # remote (this machine's list of remotes) runs here under a remote too
       # (Dispatch); the others are refused there.
-      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit remote].freeze
+      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit remote home].freeze
 
       # "command", "command sub" or either with a flag (its long name) →
       # SUPPORTED or LOCAL_ONLY. A LOCAL_ONLY command or subcommand lists