samagotchi 0.131.0 → 0.132.0

data/lib/samagotchi/desktop/macos.rb

@@ -9,6 +9,7 @@ require "rbconfig"
 require_relative "../atomic_file"
 require_relative "../version"
 require_relative "../self_report"
+require_relative "../chi_home"
 require_relative "../installed_gem"
 require_relative "../config"
 require_relative "../host_keys"
@@ -41,9 +42,16 @@ module Samagotchi
       BUILD_NAME = ".chi-helper-build"
       OLD_NAME = ".chi-helper-old"
       # Apps started by launchd get a bare env (no shell rc files), so the
-      # launch file carries what chi needs to find its gems, state and tools.
-      # Only these, and only when set: no tokens, no runtime knobs.
-      ENV_ALLOWLIST = %w[XDG_CONFIG_HOME XDG_STATE_HOME GEM_HOME GEM_PATH RUBYLIB].freeze
+      # launch file carries what chi needs to find its state and tools.
+      # Only these, and only when set: no tokens, no runtime knobs. No
+      # RUBYLIB, and GEM_HOME/GEM_PATH (GEM_ENV) only for a [ruby, chi]
+      # argv, whose wrapper may find its gem only through them (a chruby
+      # GEM_HOME): the chi home's boot sets its gem path itself, and they
+      # would reach every tool its sessions run (a project's `bundle exec`).
+      ENV_ALLOWLIST = %w[XDG_CONFIG_HOME XDG_STATE_HOME].freeze
+      GEM_ENV = %w[GEM_HOME GEM_PATH].freeze
+      # What older launch files carried and a refresh drops (#refresh_launch_file).
+      DROPPED_ENV = %w[GEM_HOME GEM_PATH RUBYLIB].freeze
       # PATH is separately filtered to absolute dirs and frozen when written,
       # so the helper's chi, workers and execute can find the shell's tools.
       # Without it Ruby reads stdin as US-ASCII and non-ASCII notes break.
@@ -131,7 +139,7 @@ module Samagotchi
       def initialize(app_dir: nil, support_dir: nil, env: ENV, runner: Runner.new,
                      source_dir: SelfReport::SOURCE_DIR, ruby: RbConfig.ruby, version: VERSION,
                      arch: nil, sources_dir: SOURCES_DIR, register: true, chi_path: nil, terminals: {},
-                     broadcast_timeout: nil)
+                     broadcast_timeout: nil, chi_home: ChiHome.current(gem_spec: InstalledGem.spec(source_dir)))
         home = env["HOME"] || Dir.home
         @app_dir = app_dir || File.join(home, "Applications")
         @support_dir = support_dir || File.join(home, "Library", "Application Support", APP_NAME)
@@ -146,6 +154,7 @@ module Samagotchi
         @register = register
         @terminals = terminals
         @broadcast_timeout = broadcast_timeout
+        @chi_home = chi_home
       end
 
       def app_path = File.join(@app_dir, "#{APP_NAME}.app")
@@ -155,10 +164,12 @@ module Samagotchi
       def executable_path = File.join(app_path, "Contents", "MacOS", EXECUTABLE)
       def installed? = File.directory?(app_path)
 
-      # What the helper runs: absolute ruby + chi (no shims, which need the
-      # shell's PATH), and the allowlisted env. chi is an installed gem's
-      # RubyGems wrapper (it activates the gem and outlives upgrades and
-      # `gem cleanup`), else this checkout's bin/chi. A section per terminal
+      # What the helper runs: the chi home's boot (ChiHome: its ruby, its gem
+      # path in the -e string, then "--" and the helper's args) when there
+      # is one; else absolute ruby + chi (no shims, which need the shell's
+      # PATH). chi is an installed gem's RubyGems wrapper (it activates the
+      # gem and outlives upgrades and `gem cleanup`), else this checkout's
+      # bin/chi. And the allowlisted env. A section per terminal
       # switched on (TERMINALS order); the broadcast timeout when given.
       # The XDG dirs go in absolute (Paths): launchd starts the app in /,
       # where a relative one would mean /<dir>. PATH is filtered to absolute,
@@ -166,16 +177,22 @@ module Samagotchi
       # it is frozen at bake time.
       def launch_config
         env = { "LANG" => LANG }
-        ENV_ALLOWLIST.each { |name| env[name] = @env[name] unless @env[name].to_s.empty? }
+        argv = launch_argv
+        names = home_boot?(argv) ? ENV_ALLOWLIST : ENV_ALLOWLIST + GEM_ENV
+        names.each { |name| env[name] = @env[name] unless @env[name].to_s.empty? }
         path = self.class.baked_path(@env)
         env["PATH"] = path if path
         env.merge!(Paths.absolute_xdg(env: env, set: :key))
-        config = { "version" => @version, "argv" => [@ruby, @chi_path], "env" => env, "sources_sha" => sources_sha }
+        config = { "version" => @version, "argv" => argv, "env" => env, "sources_sha" => sources_sha }
         TERMINALS.each { |name| config[name] = @terminals[name] if @terminals[name] }
         config["broadcast_timeout"] = @broadcast_timeout if @broadcast_timeout
         config
       end
 
+      def launch_argv
+        @chi_home ? @chi_home.boot_argv(run: ChiHome::CHI_BOOT) + ["--"] : [@ruby, @chi_path]
+      end
+
       # A digest of what a build compiles: the Swift sources and the
       # Info.plist template. The launch file records the one it was built
       # from, so a new chi rebuilds only when these changed.
@@ -209,13 +226,11 @@ module Samagotchi
 
       # Why chi update can't keep the launch file's ruby or chi: one of them
       # is gone. nil when it runs, or has no usable argv (a refresh writes
-      # this chi's then).
+      # this chi's then). Only the absolute paths in it count (a boot
+      # string, "-e" and "--" are not paths), as ChiRunner.swift checks.
       def launch_problem
         argv = usable_argv(read_launch)
-        missing = Array(argv).reject { |path| File.exist?(path) }
-        return nil if missing.empty?
-
-        "chi not found at #{missing.join(", ")}: run chi desktop install --force from the shell whose chi it should run"
+        argv && argv_problem(argv)
       end
 
       # The chi version the launch file names, nil without one.
@@ -232,7 +247,10 @@ module Samagotchi
       # Rewrite the launch file for this chi and its settings, keeping
       # its argv and the env it was installed with; a PATH only when it has
       # none (changing them takes chi desktop install --force or upgrade). A
-      # newer version stays. The app reads it at each send.
+      # newer version stays. The app reads it at each send. The kept env
+      # loses what ENV_ALLOWLIST no longer takes (DROPPED_ENV): RUBYLIB
+      # always; GEM_HOME/GEM_PATH once the argv boots the chi home (an old
+      # [ruby, wrapper] argv may find its gem only through them).
       def refresh_launch_file
         config = launch_config
         old = read_launch
@@ -240,7 +258,8 @@ module Samagotchi
         config["version"] = old["version"] unless older_version?(old["version"])
         old_env = old["env"]
         if old_env.is_a?(Hash)
-          config["env"] = old_env
+          dropped = home_boot?(config["argv"]) ? DROPPED_ENV : DROPPED_ENV - GEM_ENV
+          config["env"] = old_env.except(*dropped)
           path = self.class.baked_path(@env)
           config["env"]["PATH"] = path if config["env"]["PATH"].to_s.empty? && path
         end
@@ -466,11 +485,41 @@ module Samagotchi
         !env.is_a?(Hash) || env["PATH"].to_s.empty?
       end
 
+      # A launch file whose argv runs (#argv_problem finds nothing).
       def launch_ok?(launch)
-        argv = Array(launch["argv"])
-        !argv.empty? && argv.all? { |path| File.exist?(path) }
+        argv = usable_argv(launch)
+        !argv.nil? && argv_problem(argv).nil?
+      end
+
+      # Why a launch argv (strings) can't run chi, or nil: its ruby isn't an
+      # absolute path, an absolute path in it is gone, or it boots the chi
+      # home (home.json's ruby) and the home can't boot chi
+      # (ChiHome.problem).
+      def argv_problem(argv)
+        return "the launch file's ruby #{argv[0]} isn't an absolute path: run chi desktop install --force" unless argv[0].start_with?("/")
+
+        missing = launch_paths(argv).reject { |path| File.exist?(path) }
+        unless missing.empty?
+          return "chi not found at #{missing.join(", ")}: run chi desktop install --force from the shell whose chi it should run"
+        end
+        return nil unless home_boot?(argv)
+
+        home = begin
+          ChiHome.read
+        rescue ChiHome::Invalid
+          nil
+        end
+        why = home && ChiHome.real(home.ruby) == ChiHome.real(argv[0]) && ChiHome.problem(home)
+        why ? "the chi home it boots can't run chi (#{why}): chi home doctor" : nil
       end
 
+      # The argv entries that are paths (absolute): a boot's "-e", its
+      # string and "--" are not.
+      def launch_paths(argv) = Array(argv).select { |arg| arg.is_a?(String) && arg.start_with?("/") }
+
+      # An argv in the chi home's boot form ([ruby, "-e", boot, "--"]).
+      def home_boot?(argv) = argv.is_a?(Array) && argv[1] == "-e"
+
       def write_launch_file(config = launch_config, keep_launch: false)
         if keep_launch
           old = read_launch
@@ -478,6 +527,13 @@ module Samagotchi
           old_env = old["env"]
           old_path = old_env["PATH"] if old_env.is_a?(Hash)
           config["env"]["PATH"] = old_path unless old_path.to_s.empty?
+          # A kept [ruby, wrapper] argv keeps the GEM_* its gem was found
+          # through; a kept home boot takes none.
+          if home_boot?(config["argv"])
+            config["env"] = config["env"].except(*GEM_ENV)
+          elsif old_env.is_a?(Hash)
+            config["env"].merge!(old_env.slice(*GEM_ENV))
+          end
         end
         FileUtils.mkdir_p(@support_dir)
         AtomicFile.write(launch_path, JSON.pretty_generate(config) + "\n")

data/lib/samagotchi/engine.rb

@@ -319,6 +319,9 @@ module Samagotchi
       # The context sources the peer bundles declare as a peer agent's
       # answers (chi.peer_source); the worker's ContextAbsorber asks it.
       @peer_sources = PeerSources.new
+      # The system-prompt text plugins add (chi.prompt_section), run when
+      # the prompt is built (#build_system_prompt's sections:).
+      @prompt_sections = Plugin::PromptSections.new
       load_plugins if load
       # Registered from what the sources published while they loaded, and
       # with no plugins too: a toolkit's left-out built-ins are reachable
@@ -527,7 +530,8 @@ module Samagotchi
                        thinking: -> { turn_thinking }, model: -> { model_identity },
                        model_notes: -> { model_notes }, memories: memories,
                        muted_memory_names: @muted_memory_names, appended_files: appended_prompt_files,
-                       participants: -> { @participants_line })
+                       participants: -> { @participants_line },
+                       sections: -> { @prompt_sections ? @prompt_sections.render(@session&.id) : [] })
     end
     private :build_system_prompt
 
@@ -832,6 +836,13 @@ module Samagotchi
       @host_registry.model_ref(name).ref
     end
 
+    # The ref #switch_model! would switch +model_name+ to, checked the way it
+    # checks one (UnknownHost, MissingModel), without switching.
+    # @return [String]
+    def model_switch_ref(model_name)
+      model_ref_for(ModelProfile.check_host!(ModelProfile.required_model_name(model_name), hosts: @host_registry.entries))
+    end
+
     # Writes the effective model to +session+: the resolved ref, and the
     # name as typed when that differs (model_typed: an alias, for the
     # models: lookup after a resume).
@@ -1304,7 +1315,7 @@ module Samagotchi
     # the saved context's status: SessionModelSettings' (resolved on every
     # read); these forward.
     def saved_context_status(context, model: :current) = @model_settings.saved_context_status(context, model: model)
-    def llm_context_explained = @model_settings.llm_context_explained
+    def llm_context_explained(own: :session) = @model_settings.llm_context_explained(own: own)
     def llm_context_summary = @model_settings.llm_context_summary
     def llm_context_override = @model_settings.llm_context_override
     def chat_model? = @model_settings.chat_model?
@@ -2827,7 +2838,9 @@ module Samagotchi
         },
         toolkits: @toolkit_binding.plugin_kits,
         tool_index: @tool_index,
-        peer_sources: @peer_sources
+        peer_sources: @peer_sources,
+        prompt_sections: @prompt_sections,
+        prompt_changed: -> { prompt_changed! }
       )
       # What plugins show while they load (an MCP server that didn't
       # start) waits for the first turn, beside the load warnings: no UI
@@ -3144,8 +3157,18 @@ module Samagotchi
     # The tools changed (a plugin's chi.tools_changed!): the system prompts,
     # which declare them, are built again on the next turn.
     def tools_changed!
+      prompt_changed!
+    end
+
+    # A plugin's prompt section would give other text now
+    # (chi.prompt_changed!): the system prompts are built again at their
+    # next build (the next turn's start; a running turn keeps the prompt it
+    # started with). One cache restart: the plugin's command asked first
+    # (Plugin::Context#cache_confirm).
+    def prompt_changed!
       @prompt_builder&.reset!
     end
+    public :prompt_changed!
 
     # What a Plugin::Context reads and calls: the session now, and the
     # hook runtime's notify and ask_user.
@@ -3176,6 +3199,12 @@ module Samagotchi
         },
         model_name: -> { effective_model_ref },
         model_key: -> { @model_binding.model_key },
+        # The names a models: map looks the model up under; [] when it doesn't resolve.
+        model_names: lambda do
+          effective_model.names
+        rescue StandardError
+          []
+        end,
         state_dir: -> { session_state_dir },
         scratch: -> { @scratch },
         setup: -> { SessionSetup.of(@session) },
@@ -3186,7 +3215,9 @@ module Samagotchi
         frontend: -> { interface },
         cost: -> { @metrics.cost },
         usage: -> { @metrics.usage },
-        turn_author: -> { turn_author }
+        turn_author: -> { turn_author },
+        # A plugin's prompt section is in the stable part: a full re-read.
+        cache_confirm: ->(line, changed) { CacheConfirm.ask(line: line, cost: :full, changed: changed, engine: self) }
       )
     end
 

data/lib/samagotchi/engine_snapshots.rb

@@ -62,6 +62,8 @@ module Samagotchi
     # price_host: the effective model's host, whose hosts.<name>.models
     # prices the cost estimate names. kit_prompt: the next turn's kit
     # prompt text ({kit:, tokens:}), only when its toolkit has one.
+    # prompt_sections: the plugins' sections the built prompt holds, only
+    # when it holds some.
     # settings: the session's own settings ({"recap.enabled" => false}),
     # only when it has some.
     # @return [Hash] @metrics.snapshot, filled in
@@ -78,6 +80,9 @@ module Samagotchi
                                 price_host: model.host_name)
       kit_prompt = kit_prompt_stats
       snapshot = snapshot.merge(kit_prompt: kit_prompt) if kit_prompt
+      # The plugins' prompt sections the built prompt holds ({bundle:, name:}).
+      sections = prompt_builder.prompt_sections.map(&:to_stats)
+      snapshot = snapshot.merge(prompt_sections: sections) unless sections.empty?
       # Each participant's spend under their name (participants.json's).
       if (spend = snapshot[:spend_by_author])
         named = spend.to_h { |author, row| [author, row.merge(name: participants.name_for(author, session: session))] }

data/lib/samagotchi/gem_update.rb

@@ -6,13 +6,15 @@ require "open3"
 require "rbconfig"
 require "rubygems/package"
 require "time"
+require_relative "chi_home"
 require_relative "version"
 require_relative "redacted_inspect"
 
 module Samagotchi
   # The gem part of `chi update`: the newest samagotchi on rubygems, and a
-  # `gem install` of it through this Ruby's own gem command (the real
-  # interpreter's bindir, not a shim: the same under mise, rbenv and asdf).
+  # `gem install` of it through the chi home's gem command, else this
+  # Ruby's own (the real interpreter's bindir, not a shim: the same under
+  # mise, rbenv and asdf).
   #
   # SAMAGOTCHI_UPDATE_GEM_FILE=<path to a .gem> (hidden, for smokes) makes that
   # file the newest version and installs it instead.
@@ -32,26 +34,31 @@ module Samagotchi
     Latest = Struct.new(:version, :source, keyword_init: true)
     Release = Data.define(:version, :created_at, :prerelease)
 
-    # Runs a command without a shell; [output, success].
+    # Runs a command without a shell; [output, success]. +env+ is merged
+    # into the inherited one (nil unsets a key).
     class Runner
-      def run(argv)
-        output, status = Open3.capture2e(*argv)
+      def run(argv, env: {})
+        output, status = Open3.capture2e(env, *argv)
         [output, status.success?]
       rescue SystemCallError => e
         [e.message, false]
       end
     end
 
-    # This Ruby's own gem command (chi bootstrap installs commonmarker with
-    # it too).
-    def self.gem_bin = File.join(RbConfig::CONFIG["bindir"], "gem")
+    # The gem command an install runs: the chi home's (ChiHome.gem_bin),
+    # else this Ruby's own (chi bootstrap installs commonmarker with it too).
+    def self.gem_bin = ChiHome.gem_bin
 
     # @param fetcher [#call, nil] → the latest.json body (specs)
-    def initialize(env: ENV, fetcher: nil, runner: Runner.new, gem_bin: GemUpdate.gem_bin)
+    # @param install_env [Hash] the install child's env on top of this
+    #   process's (ChiHome.install_env: into the home's gems)
+    def initialize(env: ENV, fetcher: nil, runner: Runner.new, gem_bin: GemUpdate.gem_bin,
+                   install_env: ChiHome.install_env)
       @env = env
       @fetcher = fetcher || method(:fetch)
       @runner = runner
       @gem_bin = gem_bin
+      @install_env = install_env
     end
 
     # @return [Latest]
@@ -104,7 +111,9 @@ module Samagotchi
 
     # @return [Array(String, Boolean)] gem's output, success
     def install(latest)
-      @runner.run(install_argv(latest))
+      return @runner.run(install_argv(latest)) if @install_env.empty?
+
+      @runner.run(install_argv(latest), env: @install_env)
     end
 
     private

data/lib/samagotchi/guardrail_wiring.rb

@@ -265,12 +265,14 @@ module Samagotchi
       @protected ||= begin
         require_relative "memory_bundle/provenance"
         require_relative "context_sources"
+        require_relative "chi_home"
         Guardrails::ProtectedPaths.new(
           store_dir: File.dirname(@approvals.path),
           bundles_dir: MemoryBundle::Provenance.bundles_dir,
           config_path: Samagotchi::ConfigFile.global_path,
           hooks_dir: Hooks::Loader.hooks_dir,
-          context_dir: ContextSources.root
+          context_dir: ContextSources.root,
+          home_path: ChiHome.path
         )
       end
     end

data/lib/samagotchi/guardrails/protected_paths.rb

@@ -14,7 +14,8 @@ module Samagotchi
     #         hooks, rules, manifests) and attached context (a source's
     #         command runs later, outside the gate; chi context writes
     #         it); nothing legitimate writes there through the file tools.
-    #   ask (once / session): config.yml and the plain hooks dir. The
+    #   ask (once / session): config.yml, home.json (the chi home: the
+    #         Ruby every chi launch boots) and the plain hooks dir. The
     #         system bundle's config protocol edits config.yml with
     #         write/edit, so this keeps the user in the loop without
     #         breaking it.
@@ -29,7 +30,8 @@ module Samagotchi
       # @param config_path [String] config.yml
       # @param hooks_dir [String] the plain hooks dir
       # @param context_dir [String, nil] <state dir>/context (ContextSources.root)
-      def initialize(store_dir:, bundles_dir:, config_path:, hooks_dir:, context_dir: nil)
+      # @param home_path [String, nil] home.json (ChiHome.path)
+      def initialize(store_dir:, bundles_dir:, config_path:, hooks_dir:, context_dir: nil, home_path: nil)
         @deny = [
           ["guardrail-store", store_dir, "the approval store belongs to the user"],
           ["installed-bundles", bundles_dir, "installed bundles (hooks, rules, manifests) are changed by chi bundle install"],
@@ -37,8 +39,9 @@ module Samagotchi
         ]
         @ask = [
           ["chi-config", config_path, "changes chi's config.yml"],
+          ["chi-home", home_path, "changes the Ruby every chi launch boots"],
           ["chi-hooks", hooks_dir, "changes chi's hooks"]
-        ]
+        ].select { |_, root, _| root }
       end
 
       # Vote on +verdict+ (its targets).

data/lib/samagotchi/guardrails/verdict.rb

@@ -23,7 +23,7 @@ module Samagotchi
       # ParentPolicy's user_only); System 1 may, only if the user lists the
       # rule by name in guardrails.system_one.rules, and never for the
       # chi-answer/chi-broadcast ones (SystemOne::SelfProtect::NEVER_AUTO).
-      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd chi-broadcast prompt-memory-write
+      PROTECTED_RULES = %w[chi-config chi-home chi-hooks shell-touches-chi chi-context-cmd chi-broadcast prompt-memory-write
                            model-overlay-write chi-answer-piped chi-answer-http].freeze
       SCOPES = %w[once session repo rule].freeze
       DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."

data/lib/samagotchi/home_command.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "chi_home"
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "installed_gem"
+require_relative "paths"
+require_relative "version"
+
+module Samagotchi
+  # `chi home`: the chi home (ChiHome), the Ruby every chi launch boots.
+  # Shows it, sets it (`chi home set [--ruby PATH]`), and checks it
+  # (`chi home doctor`: for now whether its Ruby is there and has chi).
+  class HomeCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi home [set [--ruby PATH] | doctor]
+        (none)            show the chi home: its Ruby, the chi it runs, its gem home and path, mise
+        set               record this chi's Ruby and gem path as the home (a chruby shell's
+                          GEM_HOME/GEM_PATH are part of it)
+        set --ruby PATH   record that Ruby (its own gem dirs) as the home; it must have samagotchi
+                          (gem install samagotchi with it first)
+        doctor            check the home: its Ruby is there and has samagotchi
+        Every chi launch (workers, chi web's restart and Update, the macOS helper's next
+        chi desktop install or upgrade) boots the home's Ruby with the home's gems. Saved in
+        #{Paths.tilde(ChiHome.path)}.
+    TEXT
+
+    SUBCOMMANDS = %w[set doctor].freeze
+    FLAGS = {
+      nil => CLI::Flags.new(help: HELP_WORDS, args: false),
+      "set" => CLI::Flags.new(help: HELP_WORDS, args: false) { |f| f.value "--ruby" },
+      "doctor" => CLI::Flags.new(help: HELP_WORDS, args: false)
+    }.freeze
+
+    # @param path [String] home.json
+    # @param probe [#call] (ruby) → ChiHome::Record or nil (ChiHome.probe)
+    def initialize(argv, stdout: $stdout, stderr: $stderr, path: ChiHome.path, gem_spec: InstalledGem.spec,
+                   env: ENV, probe: nil)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @path = path
+      @gem_spec = gem_spec
+      @env = env
+      @probe = probe || ->(ruby) { ChiHome.probe(ruby, env: env) }
+    end
+
+    # @return [Integer] 0, 1 (no usable home, a refusal), 2 usage
+    def run
+      @sub = SUBCOMMANDS.include?(@argv.first) ? @argv.first : nil
+      parsed = parse_flags(FLAGS.fetch(@sub), @sub ? @argv[1..] : @argv)
+      return parsed if parsed.is_a?(Integer)
+
+      case @sub
+      when "set" then run_set(parsed.options)
+      when "doctor" then run_doctor
+      else run_show
+      end
+    rescue ChiHome::Invalid => e
+      error_line("#{command_name}: #{e.message} (chi home set rewrites it)")
+      CLI::Exit::FAILED
+    end
+
+    private
+
+    def command_name = @sub ? "chi home #{@sub}" : "chi home"
+    def usage_on_error = nil
+
+    def run_show
+      home = ChiHome.read(path: @path)
+      unless home
+        @stdout.puts("no chi home: chi launches on the Ruby that starts it (chi home set records this one, #{running_ruby})")
+        return CLI::Exit::OK
+      end
+
+      rows(home).each { |label, value| @stdout.puts("#{label.ljust(9)} #{value}") }
+      problem = ChiHome.problem(home)
+      @stdout.puts("problem   #{problem} (chi home doctor)") if problem
+      problem ? CLI::Exit::FAILED : CLI::Exit::OK
+    end
+
+    def rows(home)
+      list = [["ruby", home.ruby], ["chi", home.newest_version&.to_s || "none"], ["gem home", home.gem_home],
+              ["gem path", home.gem_path], ["mise", home.mise || "none"],
+              ["set", "#{home.set_at} by chi #{home.set_by_version}"]]
+      list << ["running", "chi #{VERSION} on #{running_ruby}"] unless running_home?(home)
+      list
+    end
+
+    def running_home?(home) = @gem_spec && home.running_here? && home.newest_version.to_s == VERSION
+
+    def running_ruby = "#{RbConfig.ruby}#{" (a checkout)" unless @gem_spec}"
+
+    def run_set(options)
+      home = options[:ruby] ? probed(options[:ruby]) : ChiHome.from_running(env: @env)
+      return CLI::Exit::FAILED unless home
+
+      if (problem = ChiHome.problem(home))
+        error_line("#{command_name}: #{problem}: gem install samagotchi with #{home.ruby} first")
+        return CLI::Exit::FAILED
+      end
+
+      ChiHome.write!(home, path: @path)
+      @stdout.puts("chi home set to #{home.ruby} (chi #{home.newest_version}); new workers and launches boot it")
+      CLI::Exit::OK
+    rescue SystemCallError => e
+      error_line("#{command_name}: couldn't write #{Paths.tilde(@path)}: #{e.message}")
+      CLI::Exit::FAILED
+    end
+
+    # The home a --ruby names: this one's (with this shell's gem path) when
+    # it is the running Ruby, else asked of it.
+    def probed(ruby)
+      path = File.expand_path(ruby)
+      unless File.file?(path) && File.executable?(path)
+        error_line("#{command_name}: no Ruby at #{ruby}")
+        return nil
+      end
+      return ChiHome.from_running(env: @env) if ChiHome.real(path) == ChiHome.real(RbConfig.ruby)
+
+      home = @probe.call(path)
+      error_line("#{command_name}: #{ruby} didn't answer as a Ruby") unless home
+      home
+    end
+
+    # P2c adds rows (running chi vs the home, the helper's argv, sessions,
+    # the project env); for now the home's own.
+    def run_doctor
+      home = ChiHome.read(path: @path)
+      unless home
+        @stdout.puts("ok    no chi home: each launch uses the Ruby that starts it (chi home set to record one)")
+        return CLI::Exit::OK
+      end
+
+      if (problem = ChiHome.problem(home))
+        @stdout.puts("fail  #{problem}: after a Ruby upgrade, gem install samagotchi with the new Ruby, then " \
+                     "chi home set from it (chi home set --ruby PATH); until then launches use the Ruby that starts them")
+        return CLI::Exit::FAILED
+      end
+
+      @stdout.puts("ok    chi home #{home.ruby} runs chi #{home.newest_version}")
+      CLI::Exit::OK
+    end
+  end
+end

data/lib/samagotchi/installed_versions.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "chi_home"
 require_relative "installed_gem"
 require_relative "version"
 require_relative "redacted_inspect"
@@ -8,8 +9,9 @@ module Samagotchi
   # The newest chi on this machine, which a long-lived process (chi web, an
   # attaching TUI) compares with its own VERSION to say "chi X is installed;
   # restart". Run from an installed gem: the highest samagotchi-<v>.gemspec
-  # in RubyGems' specification dirs, matching the `>= 0.a` a new worker
-  # activates (prereleases count). Run from a source checkout: the VERSION
+  # in RubyGems' specification dirs (the chi home's when there is one,
+  # ChiHome), matching the `>= 0.a` a new worker activates (prereleases
+  # count). Run from a source checkout: the VERSION
   # in lib/samagotchi/version.rb on disk now (a `git pull` moves it).
   #
   # Cheap enough to poll: each dir is listed again only when its mtime
@@ -30,7 +32,7 @@ module Samagotchi
     #   runs from (nil: a source checkout)
     # @param dirs [#call] → the specification dirs to list
     # @param version_file [String] a checkout's version.rb
-    def initialize(env: ENV, gem_spec: InstalledGem.spec, dirs: -> { Gem::Specification.dirs },
+    def initialize(env: ENV, gem_spec: InstalledGem.spec, dirs: -> { ChiHome.spec_dirs(gem_spec: gem_spec) },
                    version_file: File.join(InstalledGem::ROOT, "lib", "samagotchi", "version.rb"))
       @env = env
       @gem_spec = gem_spec