samagotchi 0.131.0 → 0.132.0

data/docs/plugins.md

@@ -150,6 +150,34 @@ chi.command "/hello-slow", "greet after 2 s, even mid-turn", anytime: true do |a
 end
 ```
 
+#### Commands that ask: `ctx.cache_confirm`
+
+A command whose change restarts the model server's prompt cache (one that changes the text of a
+[prompt section](#chiprompt_sectionname--ctx---and-chiprompt_changed)) asks first, as `/thinking` and `/toolkit` do:
+`ctx.cache_confirm(line, changed:)` returns nil when it may apply now, or a confirm to return with the command's
+text, `[text, confirm]`, changing nothing. `line` is the command line that applies it (without `--yes`), `changed:`
+whether your text would change. chi decides the rest: it asks only a person at a web tab or a TUI (never `chi send`,
+a delegate or `chi -p`), only once the session has a model reply, never for a line with `--yes` (or `-y`), and
+writes the confirm's text (the conversation's size to read again; on an `api: anthropic` host, that preserved
+thinking is dropped). The TUI prefills `line --yes`, the web shows an Apply button that sends it, and the command
+then runs again with `--yes` in `args` (drop it from your words). Outside a command (a hook, an init task, your
+own thread) it is always nil. A plain String or nil return is unchanged.
+
+A command that asks must not be `anytime: true`: the REPL shows only an anytime command's text, so its Apply would
+be lost. Needs chi 0.132.0.
+
+```ruby
+chi.command "/tone", "show or set this session's tone" do |args, ctx|
+  word = (args.split - %w[--yes -y]).join(" ")
+  ask = ctx.cache_confirm("/tone #{word}", changed: word != current_tone)
+  next ["Switching to #{word} restarts the prompt cache.", ask] if ask
+
+  save_tone(word)
+  @chi.prompt_changed!
+  "tone: #{word} from the next turn"
+end
+```
+
 #### `/help`
 
 `/help` (itself an anytime command) lists every command the session knows:
@@ -607,6 +635,38 @@ chi.toolkit "coding", base: "child", prompt: "- Be concise in your responses"
 chi.toolkit "web", base: "lean", groups: %w[chrome db*]
 ```
 
+### `chi.prompt_section(name) { |ctx| … }` and `chi.prompt_changed!`
+
+Text the session's system prompt carries, from a plugin: the block gets the Context and returns a String (at most
+2000 characters, stripped) or nil for no section. Each goes into the prompt's stable part right after the
+toolkit's prompt text and before the memory indexes, as `From <bundle> (<name>):` and the text, sorted by
+(bundle, name). With no section (every block nil, or no plugin uses it) the prompt is exactly what it was without.
+`name` is `a-z`, `0-9`, `_` and `-` (at most 32), once per bundle.
+
+The block runs when the prompt is built: a session's first turn, after `/model` (so `ctx.model` and
+`ctx.model_key` are the new model's), after `chi.prompt_changed!` or a tools change. Never per request, and on
+whatever thread builds, so keep it quick and thread-safe (no I/O beyond reading a small file). **Same inputs, same
+text**: anything that differs (a time, a random pick, a count) breaks the model server's prompt cache at the next
+build. A block that raises, returns something other than a String or nil, or text over the limit keeps that
+section's last good text for the session (one warn in the debug log, `prompt_section_failed`); with none yet the
+section is left out. A deliberate nil removes it.
+
+`chi.prompt_changed!` says your section would give other text now (the user picked another setting): the prompt is
+built again at its next build, the next turn's start (a running turn keeps the prompt it started with). That
+restarts the prompt cache for the whole conversation, so a command that changes it asks first
+([Commands that ask](#commands-that-ask-ctxcache_confirm)) and calls `chi.prompt_changed!` only once it applies.
+Keep `chi` from `register` for that (`@chi = chi`). `/stats` names the sections the prompt holds
+(`prompt sections: tone (tone)`). The test kit runs them as a build does (`bundle.prompt_text`,
+`bundle.prompt_sections`) and counts `chi.prompt_changed!` (`bundle.prompt_changes`). Needs chi
+0.132.0: a bundle using it sets `requires_chi`.
+
+```ruby
+def register(chi)
+  @chi = chi
+  chi.prompt_section("tone") { |ctx| preset_text(ctx.model_key) }   # nil: no section
+end
+```
+
 ### `chi.tool_source(call:, acts_as:, label:, wait:, prefix:)`
 
 Tools the model reaches through a search instead of declaring them one by
@@ -764,6 +824,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.fork?` | whether the session is a fork (`ctx.sessions.fork`): it has a parent but isn't a delegate child, and started from a conversation, so its first prompt isn't its first user message |
 | `ctx.model` | the model the session runs on now: its resolved ref (`host:id`), right after `/model` too |
 | `ctx.model_key` | that model's memory overlay key (`<name>.<key>.md`, what `memory_write current_model_only` writes) |
+| `ctx.model_names` | the names chi's own per-model config looks that model up under (a `models:` map in config.yml): as typed (an alias), the alias's target, the resolved ref, without the host, the bare id; deduped, most specific first, frozen (`[]` when it doesn't resolve). Match a map of yours over them downcased, first hit, as chi does. Needs chi 0.132.0 |
 | `ctx.cost` | the session's spend so far, read now, as a frozen value: `total` (USD, reported + estimated, side requests included; 0.0 before any), `reported` (by providers, `usage.cost`), `estimated` (from `hosts.<name>.models` prices; a generation is one or the other, never both), `side` (recap, `/btw`, `ask_model`: their share of `total`) and `known?` (false while generations or side requests ran but none was reported or priced, so a limit on it can't be enforced; a session with some priced generations reads known, the unpriced ones counting 0). It includes the running turn's finished generations and what earlier workers of the session spent. Use its methods, not its class. Needs chi 0.83.0 |
 | `ctx.usage` | the session's work so far, read now, as a frozen value: `turns` (finished ones and the running one), `tool_calls` and `tool_calls_by_tool` (every call, running ones included; canonical names: an alias counts under its tool, a `call_tool` call under the inner tool), `steps` (the loop rounds that dispatched tools, `/stats`' iterations) and `active_ms` (`active_minutes` too): work time, the generations' time plus the finished tool calls' time, never the waits between them (a question, an approval, the user's answer to `ask_user_question`), with `tool_ms_by_tool` its tool part by tool, so a waiting tool's time (`task_wait`) can be left out. Its counts are the ones `/stats` and `chi sessions stats` show, earlier workers' included. Use its methods, not its class. Needs chi 0.100.0 (guard it with `ctx.respond_to?(:usage)`) |
 | `ctx.turn_author` | who wrote the running turn when it isn't the session's owner: a participant's `"p:<id>"` (`chi share`); nil for the owner's turns and between turns. Every hook event of such a turn carries the same as `author:`. The handler runs with the owner's power whatever the author ([hooks](hooks.md#participants-turns)). Needs chi 0.105.0 (guard it with `ctx.respond_to?(:turn_author)`) |
@@ -788,6 +849,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.use_toolkit(name)` | put the session on toolkit `name` (yours from `chi.toolkit`, or chi's): saved, applied at the next turn's start and announced (`toolkit> toolkit: NAME from the next turn's start`, the web's tools chip follows). Only before the session's first model reply and outside a turn (the declared tools start every request, and a plugin doesn't ask first); otherwise it returns false and changes nothing: tell the user to run `/toolkit NAME`. An unknown name raises ArgumentError. Needs chi 0.66.0 |
 | `ctx.load_tools(names)` | load tools the session reaches but doesn't declare, so the model calls them by name: built-ins (`"delegate"`, `"chi/delegate"`), MCP tools (`"mcp_fs_read"`, `"fs/read"`). Returns the names it staged (the wire names); a declared tool, one loaded before, a removed or unknown one is skipped (an unknown one logged), so calling it every turn is fine. From a `before_turn` hook it loads for that turn; anywhere else (mid-turn too) from the next turn's start. Call it from a hook: before the session's first turn its toolkit isn't applied yet and nothing resolves. **A hint, not access**: the tools keep their guardrails and approvals, and only a host that takes tool changes (`api: anthropic`, not Fireworks) gets one, as a system message after the user's (`[tools loaded: delegate (your-bundle)]` in the session, a notice line live); elsewhere nothing is sent or saved, and the tools stay reachable with `call_tool`. A hook may switch the model after you call it, so the return value can't promise delivery. Raises ArgumentError for anything but an Array. Needs chi 0.99.0 |
 | `ctx.context` | attach outside text to this session and list it: see [Attached context](#attached-context-ctxcontext) |
+| `ctx.cache_confirm(line, changed:)` | inside a command: nil to apply a prompt-cache-restarting change now, or a confirm to return as `[text, confirm]`: see [Commands that ask](#commands-that-ask-ctxcache_confirm). Needs chi 0.132.0 |
 
 The Engine itself is never handed to a plugin.
 
@@ -1211,6 +1273,10 @@ bundle.fire(:after_turn, status: "completed")            # → the event, after
 bundle.question_asked("Fix JIRA-1?", question: { question: "Go?" })   # → the refs, as chi's seams fire it
 event = bundle.before_tool_call_event({ name: "read", path: "a.txt" }, params: "read a.txt")
 bundle.command("/mine stop")                             # → what the command returned
+bundle.command("/tone x", confirm: true)                 # sent from a web tab or a TUI: ctx.cache_confirm may ask
+bundle.set(history: true, context_tokens: 900)           # a model reply to restart (ctx.cache_confirm), its size
+bundle.set(model_names: %w[tiny box:gemma gemma])       # ctx.model_names (default: model_name and its id)
+bundle.prompt_text                                       # the prompt sections' text, as a build runs them
 bundle.tool("my_tool", path: "a.txt")                    # → the text the model reads
 verdict = bundle.tool_call({ name: "execute", content: "rm -rf /" })
 verdict.deny?                                            # a real Guardrails::Verdict (votes: verdict.votes)
@@ -2510,11 +2576,12 @@ gem.
 `chi bundle install model-notes` (or the `dev` profile) installs reviewed
 [model notes](memory.md#model-notes) into the system scope: working habits
 for one model family, loaded into the prompt only for the models a note's
-`models:` line names. It has no plugin or hook. It ships one note:
+`models:` line names. It has no plugin or hook. It ships two notes:
 
 | note | models | for |
 |---|---|---|
 | `model_notes_deepseek` | `*deepseek-v4*` | DeepSeek V4 / V4.1: explore briefly then act, commit one item at a time, stop digging, `memory_read` for memories, file tools rather than heredocs that guardrail rules ask about |
+| `model_notes_tone` | `*` | every model: answer first, in plain words; no preambles, restated questions or closing offers; lists only for steps or parallel items |
 
 - **Reviewed before it ships.** A note is generic (no repo or machine facts),
   says nothing the harness already does (a tool's description, an alias),

data/lib/samagotchi/bootstrap_command.rb

@@ -5,7 +5,9 @@ require_relative "config"
 require_relative "model_profile"
 require_relative "host_registry"
 require_relative "host_keys"
+require_relative "chi_home"
 require_relative "gem_update"
+require_relative "installed_gem"
 require_relative "bootstrap/probe"
 require_relative "bootstrap/config_writer"
 require_relative "bootstrap/bundles"
@@ -87,8 +89,10 @@ module Samagotchi
     #   the process ENV points, not +env+)
     # @param gem_runner [#run] runs `gem install commonmarker` (GemUpdate::Runner)
     # @param gem_present [#call, nil] → whether commonmarker is installed
+    # @param home [#current, #record_first!] the chi home (ChiHome)
     def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, env: ENV, probe: nil, config_path: nil,
-                   platform: RbConfig::CONFIG["host_os"], bundles: nil, gem_runner: GemUpdate::Runner.new, gem_present: nil)
+                   platform: RbConfig::CONFIG["host_os"], bundles: nil, gem_runner: GemUpdate::Runner.new, gem_present: nil,
+                   gem_spec: InstalledGem.spec, home: ChiHome)
       @argv = argv.dup
       @stdin = stdin
       @stdout = stdout
@@ -99,8 +103,14 @@ module Samagotchi
       @platform = platform
       @bundles = bundles || Bootstrap::Bundles.new
       @gem_runner = gem_runner
-      # Installed, without loading its native extension into this process.
-      @gem_present = gem_present || -> { Gem::Specification.find_all_by_name(MARKDOWN_GEM).any? }
+      @gem_spec = gem_spec
+      @home = home
+      # Installed (in the chi home's gems when there is one: chi web runs
+      # there), without loading its native extension into this process.
+      @gem_present = gem_present || lambda {
+        home = @home.current(gem_spec: @gem_spec)
+        home ? home.gem?(MARKDOWN_GEM) : Gem::Specification.find_all_by_name(MARKDOWN_GEM).any?
+      }
     end
 
     # @return [Integer] 0 written (or already there), 1 failed (a failed
@@ -371,6 +381,7 @@ module Samagotchi
     # each. Then Markdown in chi web (#offer_markdown). 1 when a bundle
     # failed; the Markdown step never changes it.
     def install_bundles(dry_run: false)
+      record_home unless dry_run
       ok = system_bundle_line(@bundles.sync_system(dry_run: dry_run), dry_run)
       ok = install_profile(CORE, dry_run) && ok
       unless dry_run || !tty? || (members = dev_to_install).empty?
@@ -409,13 +420,31 @@ module Samagotchi
       false
     end
 
-    # true when commonmarker is there or `gem install` (this Ruby's own gem
-    # command) put it there; else one line with gem's last word on it.
+    # The first chi home (ChiHome.record_first!: the helper's Ruby, else
+    # this one), one line; nothing when one is recorded already.
+    def record_home
+      recorded = @home.record_first!(gem_spec: @gem_spec, launch_path: helper_launch_path)
+      @stdout.puts("chi home: #{recorded.ruby} (chi home set to change)") if recorded
+    end
+
+    def helper_launch_path
+      return nil unless @platform.to_s.include?("darwin")
+
+      require_relative "desktop/macos"
+      Desktop::MacOS.new(env: @env, register: false).launch_path
+    end
+
+    # true when commonmarker is there or `gem install` (the chi home's gem
+    # command, else this Ruby's own) put it there; else one line with gem's
+    # last word on it.
     def install_markdown_gem
       return true if @gem_present.call
 
       @stdout.puts("#{MARKDOWN_GEM}: installing…")
-      output, ok = @gem_runner.run([GemUpdate.gem_bin, "install", MARKDOWN_GEM, "--no-document"])
+      home = @home.current(gem_spec: @gem_spec)
+      argv = [ChiHome.gem_bin(home), "install", MARKDOWN_GEM, "--no-document"]
+      env = ChiHome.install_env(home, env: @env)
+      output, ok = env.empty? ? @gem_runner.run(argv) : @gem_runner.run(argv, env: env)
       return true if ok
 
       last = output.to_s.lines.map(&:strip).reject(&:empty?).last || "no output"

data/lib/samagotchi/bundles/model-notes/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: model-notes
-version: 0.1.0
+version: 0.2.0
 scope: system
 description: "Reviewed model notes: working habits a model family needs, loaded into the prompt only for the models each note's models: line names"
 trust_level: reviewed
@@ -9,3 +9,6 @@ files:
   model_notes_deepseek.md:
     sha256: sha256:0b07e40edc1a3d4a3ad6bea08d9b338913f78cab19a5809bcf4593f459f9bc5e
     description: "DeepSeek V4 working habits: explore briefly then act, commit per item, stop digging, memory_read for memories, file tools over heredocs"
+  model_notes_tone.md:
+    sha256: sha256:e47a93dc3b3cb78a9bd3eb7f04ef1c4d2a30b4a7c0110a66e1e3a26e363827ca
+    description: "Concise answers for every model (models: *): answer first, no preambles or closing offers"

data/lib/samagotchi/bundles/model-notes/model_notes_tone.md

@@ -0,0 +1,3 @@
+models: *
+How to write answers:
+- Answer first, in plain words. Skip preambles, restating the question and closing offers. Use a list only for steps or several parallel items.

data/lib/samagotchi/bundles/model-notes/notes/README.md

@@ -35,3 +35,17 @@ bundle itself.
   The dates and tasks differ, so this is a hint, not an A/B: an A/B is the same kind of task with the note on and
   muted (`chi send --new --mute model_notes_deepseek`). The shipped text is shorter than the one measured (795
   characters against 1,519) and keeps its habits.
+
+## model_notes_tone
+
+- **models:** `*`: every model. It stacks on a family's note (`spec/model_ids.yml` `expected_overlaps`).
+- **Origin, 2026-10-29:** chi's prompt has no style guidance, so each model talks in its own voice and answers run
+  long. A `/tone` bundle (presets, a session command) was built and parked; the user chose the lighter way, a model
+  note, with the gentlest text: only the anti-padding part of the concise preset ("leave out what went as expected"
+  was dropped: it can hide useful confirmations).
+- **Approved:** the text as shipped, by the user, 2026-10-29 (after the check below); ships in model-notes (the `dev`
+  profile) first, `core` later only after more evidence (other model families, a week of the user's own use).
+- **Evidence:** a with/without check on the local Qwen3.8 Flash Next (Splash), 5 tasks (4 questions about this repo,
+  1 small code edit), one run each, `chi --non-interactive` with isolated state: answers 12.5k → 10.1k characters
+  (−19%), 4 of 5 shorter; openings more direct, closing summaries gone; nothing a task needed was lost (dropped: one
+  worked glob example, one aside about the model's own fixed mistake). N=1 per task: a direction, not a measurement.

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.131.0
+version: 0.132.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/cache_confirm.rb

@@ -12,6 +12,9 @@ module Samagotchi
     # The costs worth asking about (Thinking.cache_cost,
     # ReasoningHistory.cache_cost); :tail and nil are not.
     COSTLY = %i[full provider history].freeze
+    # Thread.current key: whether the plugin command running on this
+    # thread may ask (#asking).
+    ASKING = :samagotchi_cache_confirm_asking
 
     # The line that applies a change, and the question the reply ends with.
     Confirm = Data.define(:line, :text) do
@@ -42,6 +45,21 @@ module Samagotchi
       changed && history && COSTLY.include?(cost)
     end
 
+    # Run +block+ as a plugin command whose sender can answer a confirm
+    # (+flag+: SessionCommands#run's confirm, false once the line has
+    # --yes): Plugin::Context#cache_confirm asks only inside it, on this
+    # thread. Nests; threads the block starts don't inherit it.
+    def asking(flag)
+      previous = Thread.current[ASKING]
+      Thread.current[ASKING] = flag ? true : false
+      yield
+    ensure
+      Thread.current[ASKING] = previous
+    end
+
+    # Whether the plugin command on this thread may ask (#asking).
+    def asking? = Thread.current[ASKING] == true
+
     # Whether a cache-changing command should ask, and its reply line.
     # Kept independent of any UI so commands and plugins can share it.
     # @param line [String] the full command line without --yes

data/lib/samagotchi/chi_home.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "rbconfig"
+require "time"
+require_relative "atomic_file"
+require_relative "installed_gem"
+require_relative "log"
+require_relative "paths"
+require_relative "version"
+
+module Samagotchi
+  # The chi home: the one Ruby (and its gem path) every chi launch boots,
+  # whoever launches it (a terminal on another Ruby, chi web, the macOS
+  # helper under launchd). Recorded in home.json under the config dir
+  # ($XDG_CONFIG_HOME/samagotchi/home.json) by `chi home set`, or once, the
+  # first time, by chi bootstrap or chi update (#record_first!); never
+  # overwritten implicitly.
+  #
+  # One mechanism (docs/architecture.md, "How chi launches itself"):
+  # Record#boot_argv puts `Gem.paths = {…}` at the front of a `ruby -e`
+  # boot string, so no GEM_HOME/GEM_PATH ever goes into an environment
+  # (the tools a worker runs keep the spawner's, or the project's). Every
+  # launch site asks #current at launch time and keeps its own argv when
+  # there is no usable home.
+  module ChiHome
+    FILE = "home.json"
+    # What a launch outside a worker boots: the newest chi in the home,
+    # run as its own `chi` executable (ARGV after the "--").
+    CHI_BOOT = "gem 'samagotchi', '>= 0.a'; load Gem.bin_path('samagotchi', 'chi')"
+    # Where `mise` usually is when PATH doesn't have it (launchd's bare PATH).
+    MISE_DIRS = ["/opt/homebrew/bin", "/usr/local/bin", File.join(Dir.home, ".local", "bin")].freeze
+    # What a probe of another Ruby must not inherit: they would move it off
+    # its own gems.
+    PROBE_UNSET = %w[GEM_HOME GEM_PATH RUBYOPT RUBYLIB BUNDLE_GEMFILE BUNDLE_BIN_PATH].freeze
+    PROBE = "require 'json'; print JSON.generate('ruby' => RbConfig.ruby, 'gem_home' => Gem.dir, " \
+            "'gem_path' => Gem.path.join(File::PATH_SEPARATOR))"
+    GEMSPEC = /\Asamagotchi-(#{Gem::Version::VERSION_PATTERN})\.gemspec\z/
+
+    class Invalid < StandardError
+    end
+
+    # home.json's fields. +gem_path+ is what `Gem.paths=` takes (dirs joined
+    # by File::PATH_SEPARATOR); +mise+ an absolute path or nil.
+    Record = Data.define(:ruby, :gem_home, :gem_path, :mise, :set_at, :set_by_version) do
+      # home.json's (or a probe's) fields, checked: ruby, gem_home and every
+      # gem_path entry absolute paths, mise an absolute path or nil.
+      # @raise [Invalid]
+      def self.from_h(hash)
+        fields = members.to_h { |key| [key, hash[key.to_s]] }
+        %i[ruby gem_home gem_path].each do |key|
+          value = fields[key]
+          raise Invalid, "#{key} is missing" unless value.is_a?(String) && !value.empty?
+        end
+        raise Invalid, "ruby is not an absolute path" unless fields[:ruby].start_with?("/")
+        raise Invalid, "gem_home is not an absolute path" unless fields[:gem_home].start_with?("/")
+
+        dirs = fields[:gem_path].split(File::PATH_SEPARATOR)
+        raise Invalid, "gem_path has a relative entry" unless dirs.all? { |dir| dir.start_with?("/") }
+
+        mise = fields[:mise]
+        raise Invalid, "mise is not an absolute path" unless mise.nil? || (mise.is_a?(String) && mise.start_with?("/"))
+
+        new(**fields)
+      end
+
+      def to_h = members.to_h { |key| [key.to_s, public_send(key)] }
+      def gem_dirs = gem_path.split(File::PATH_SEPARATOR).reject(&:empty?)
+      def spec_dirs = gem_dirs.map { |dir| File.join(dir, "specifications") }
+      # The home Ruby's own gem command (its bindir, not a shim).
+      def gem_bin = File.join(File.dirname(ruby), "gem")
+      def ruby_ok? = File.file?(ruby) && File.executable?(ruby)
+
+      # The samagotchi versions installed in the home, newest last.
+      # @return [Array<Gem::Version>]
+      def versions
+        spec_dirs.flat_map do |dir|
+          Dir.children(dir).filter_map { |name| GEMSPEC.match(name)&.[](1) }
+        rescue SystemCallError
+          []
+        end.select { |v| Gem::Version.correct?(v) }.map { |v| Gem::Version.new(v) }.uniq.sort
+      end
+
+      def newest_version = versions.last
+
+      # Whether a gem named +name+ is installed in the home.
+      def gem?(name)
+        spec_dirs.any? { |dir| !Dir.glob(File.join(dir, "#{name}-*.gemspec")).empty? }
+      end
+
+      # The `Gem.paths =` line every boot starts with: string literals only
+      # (String#inspect escapes `#{`), no env read.
+      def prelude = "Gem.paths = {'GEM_HOME' => #{gem_home.inspect}, 'GEM_PATH' => #{gem_path.inspect}}"
+
+      # [ruby, "-e", "<prelude>; <run>"]: a site appends "--" and its args
+      # when +run+ runs chi's executable (CHI_BOOT).
+      def boot_argv(run:) = [ruby, "-e", "#{prelude}; #{run}"]
+
+      # Whether this process runs on the home: its Ruby and its gem dir.
+      def running_here?(ruby: RbConfig.ruby, gem_dir: Gem.dir)
+        ChiHome.real(ruby) == ChiHome.real(self.ruby) && ChiHome.real(gem_dir) == ChiHome.real(gem_home)
+      end
+    end
+
+    @warned = {}
+    @warn_mutex = Mutex.new
+
+    module_function
+
+    # @return [String] $XDG_CONFIG_HOME/samagotchi/home.json
+    def path(env: ENV) = File.join(Paths.config_home(env: env), Paths::APP_DIR, FILE)
+
+    # The record as home.json has it, usable or not (chi home shows it);
+    # nil without one.
+    # @raise [Invalid] a file that isn't home.json's shape
+    def read(path: self.path)
+      return nil unless File.file?(path)
+
+      data = JSON.parse(File.read(path))
+      raise Invalid, "#{Paths.tilde(path)} is not a JSON object" unless data.is_a?(Hash)
+
+      Record.from_h(data)
+    rescue JSON::ParserError, SystemCallError => e
+      raise Invalid, "#{Paths.tilde(path)}: #{e.message.lines.first.to_s.strip}"
+    rescue Invalid => e
+      raise if e.message.start_with?(Paths.tilde(path))
+
+      raise Invalid, "#{Paths.tilde(path)}: #{e.message}"
+    end
+
+    # The home every launch boots, or nil, where each site keeps its own
+    # argv: no home.json; one that isn't its shape (warned once); its ruby
+    # gone (a Ruby upgrade); no samagotchi in its gem path; or this chi
+    # runs from a source checkout (a worktree's bin/chi spawns its own code).
+    # @param gem_spec [Gem::Specification, nil] the installed gem this runs from
+    # @return [Record, nil]
+    def current(path: self.path, gem_spec: InstalledGem.spec)
+      return nil unless gem_spec
+
+      home = read(path: path)
+      return nil unless home
+
+      why = problem(home)
+      why ? warn_once(:unusable, path: path, problem: why) : home
+    rescue Invalid => e
+      warn_once(:invalid, path: path, error: e.message)
+    end
+
+    # Why a recorded home can't boot chi, or nil.
+    # @return [String, nil]
+    def problem(home)
+      return "home ruby missing: #{home.ruby}" unless home.ruby_ok?
+      return "no samagotchi in the home's gems (#{home.gem_path})" if home.versions.empty?
+
+      nil
+    end
+
+    # The home's boot, or nil without a usable home (#current).
+    # @return [Array<String>, nil]
+    def boot_argv(run:, home: current) = home&.boot_argv(run: run)
+
+    # Where a gem install lands: the home's gem dir, else this process's
+    # (UpdateCheck's writability).
+    def gem_dir(gem_spec: InstalledGem.spec) = current(gem_spec: gem_spec)&.gem_home || Gem.dir
+
+    # The specification dirs new workers activate chi from: the home's,
+    # else this process's (InstalledVersions' "installed; restart").
+    def spec_dirs(gem_spec: InstalledGem.spec) = current(gem_spec: gem_spec)&.spec_dirs || Gem::Specification.dirs
+
+    # The gem command a gem install runs: the home's, else this Ruby's own.
+    def gem_bin(home = current) = home ? home.gem_bin : File.join(RbConfig::CONFIG["bindir"], "gem")
+
+    # The env for a gem install child (chi update, chi bootstrap's
+    # commonmarker): into the home's gems whatever the spawner's
+    # GEM_HOME/GEM_PATH say (a chruby shell, an old helper's launch file),
+    # and with mise's dir on PATH (mise's rubygems plugin runs `mise
+    # reshim` after an install). {} without a home: the env as today.
+    # @return [Hash{String=>String}]
+    def install_env(home = current, env: ENV)
+      return {} unless home
+
+      result = { "GEM_HOME" => home.gem_home, "GEM_PATH" => home.gem_path }
+      if home.mise
+        dirs = env["PATH"].to_s.split(File::PATH_SEPARATOR)
+        mise_dir = File.dirname(home.mise)
+        result["PATH"] = (dirs + [mise_dir]).uniq.join(File::PATH_SEPARATOR) unless dirs.include?(mise_dir)
+      end
+      result
+    end
+
+    # The fallback pin for a worker's `>= 0.a` (a broken newest install):
+    # the spawner's own version when the home has it, else the home's
+    # newest.
+    # @return [String, nil]
+    def fallback_version(home, gem_spec)
+      versions = home.versions
+      own = gem_spec && Gem::Version.new(gem_spec.version.to_s)
+      (own && versions.include?(own) ? own : versions.last)&.to_s
+    end
+
+    # This process's Ruby and gem path as a record (chi home set without
+    # --ruby, a first record from the running chi).
+    def from_running(env: ENV)
+      Record.new(ruby: real(RbConfig.ruby), gem_home: Gem.dir, gem_path: Gem.path.join(File::PATH_SEPARATOR),
+                 mise: find_mise(env: env), set_at: Time.now.utc.iso8601, set_by_version: VERSION)
+    end
+
+    # Another Ruby's own gem dirs, asked of it (its GEM_*/RUBYOPT unset
+    # unless +gem_env+ gives the GEM_HOME/GEM_PATH its chi lived under).
+    # @param runner [#call] (env, argv) → [output, success]
+    # @return [Record, nil] nil when it doesn't run or answer
+    def probe(ruby, gem_env: {}, env: ENV, runner: method(:capture))
+      child_env = PROBE_UNSET.to_h { |key| [key, nil] }.merge(gem_env.slice("GEM_HOME", "GEM_PATH").compact)
+      output, ok = runner.call(child_env, [ruby, "-e", PROBE])
+      return nil unless ok
+
+      data = JSON.parse(output.to_s.lines.last.to_s)
+      return nil unless data.is_a?(Hash)
+
+      Record.from_h(data.merge("ruby" => data["ruby"].is_a?(String) ? real(data["ruby"]) : data["ruby"],
+                               "mise" => find_mise(env: env), "set_at" => Time.now.utc.iso8601,
+                               "set_by_version" => VERSION))
+    rescue JSON::ParserError, TypeError, Invalid
+      nil
+    end
+
+    # @raise [SystemCallError]
+    def write!(home, path: self.path)
+      FileUtils.mkdir_p(File.dirname(path))
+      AtomicFile.write(path, "#{JSON.pretty_generate(home.to_h)}\n", perm: 0o644)
+      home
+    end
+
+    # The first record, once, from an installed chi (chi bootstrap, chi
+    # update): of the macOS helper's ruby (when its launch file names one
+    # whose newest chi is at least this one: the Ruby it already runs) and
+    # this chi's, the one with the newest chi; the helper's on a tie.
+    # Never over an existing home.json, never from a checkout or under
+    # Bundler, never a Ruby without samagotchi.
+    # @param launch_path [String, nil] the helper's launch.json
+    # @param bundler [Boolean, nil] running under Bundler (nil: found out)
+    # @return [Record, nil] the home written, nil when none was
+    def record_first!(gem_spec: InstalledGem.spec, launch_path: nil, path: self.path, env: ENV,
+                      runner: method(:capture), bundler: nil)
+      return nil unless gem_spec
+      return nil if bundler.nil? ? under_bundler?(env) : bundler
+      return nil if File.exist?(path)
+
+      own = Gem::Version.new(VERSION)
+      helper = helper_home(launch_path, env: env, runner: runner)
+      helper = nil if helper && (helper.newest_version.nil? || helper.newest_version < own)
+      home = [helper, from_running(env: env)].compact.select { |candidate| problem(candidate).nil? }
+                                             .max_by(&:newest_version)
+      home && write!(home, path: path)
+    rescue SystemCallError => e
+      Log.warn(:config, "home_record_failed", error: e.class.name, msg: e.message)
+      nil
+    end
+
+    # The helper's launch.json ruby (argv[0]) probed with the GEM_* it was
+    # installed with; nil without one.
+    def helper_home(launch_path, env:, runner:)
+      return nil unless launch_path && File.file?(launch_path)
+
+      launch = JSON.parse(File.read(launch_path))
+      ruby = Array(launch["argv"]).first if launch.is_a?(Hash)
+      return nil unless ruby.is_a?(String) && ruby.start_with?("/") && File.executable?(ruby)
+
+      gem_env = launch["env"].is_a?(Hash) ? launch["env"] : {}
+      probe(ruby, gem_env: gem_env, env: env, runner: runner)
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    # The test UpdateCommand's @bundler makes: a first record from a
+    # `bundle exec` would name the bundle's gems.
+    def under_bundler?(env = ENV) = !!(defined?(::Bundler) || !env["BUNDLE_GEMFILE"].to_s.empty?)
+
+    # mise's absolute path: on +env+'s PATH, else in MISE_DIRS; nil without.
+    def find_mise(env: ENV)
+      dirs = env["PATH"].to_s.split(File::PATH_SEPARATOR).select { |dir| dir.start_with?("/") } + MISE_DIRS
+      dirs.map { |dir| File.join(dir, "mise") }.find { |file| File.file?(file) && File.executable?(file) }
+    end
+
+    def real(path)
+      File.realpath(path)
+    rescue SystemCallError, TypeError
+      path.to_s
+    end
+
+    def capture(env, argv)
+      output, status = Open3.capture2e(env, *argv)
+      [output, status.success?]
+    rescue SystemCallError => e
+      [e.message, false]
+    end
+
+    # Logs a home that can't be used, once per process and reason; nil.
+    def warn_once(event, **fields)
+      key = [event, fields]
+      first = @warn_mutex.synchronize { @warned[key] ? false : (@warned[key] = true) }
+      Log.warn(:config, "home_#{event}", **fields) if first
+      nil
+    end
+
+    # Specs: forget what was warned.
+    def reset_warnings! = @warn_mutex.synchronize { @warned.clear }
+  end
+end