samagotchi 0.132.0 → 0.133.0

data/lib/samagotchi/chi_shim.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "shellwords"
+require_relative "atomic_file"
+require_relative "chi_home"
+require_relative "log"
+require_relative "paths"
+
+module Samagotchi
+  # The `chi` a worker's tools run: $XDG_STATE_HOME/samagotchi/bin/chi, a
+  # shell script that execs the chi home's Ruby with its boot
+  # (ChiHome::Record#boot_argv, CHI_BOOT). ProjectEnv puts its dir first on
+  # the worker's PATH, so after the project env (whose PATH would find the
+  # project Ruby's chi, an old one or none) an agent's `chi send`, `chi self`
+  # or `chi answer` still runs the home's chi. The dir holds `chi` only: the
+  # project's ruby, gem and bundle stay the project's; bin/chi, a checkout
+  # path or `bundle exec chi` stay themselves.
+  module ChiShim
+    NAME = "chi"
+    HEADER = "# chi's own chi for its tools (ChiShim): rewritten at each worker start from the chi home.\n"
+    # A project's RUBYOPT/RUBYLIB/RUBYGEMS_GEMDEPS/GEMRC/BUNDLE_* (a `bundle
+    # exec` the tool runs under, a mise [env]) would load the project's gems
+    # or settings into the home's chi, its LD_*/DYLD_* libraries into its
+    # ruby: unset before the exec.
+    UNSET = "unset RUBYOPT RUBYLIB RUBYGEMS_GEMDEPS GEMRC LD_PRELOAD LD_LIBRARY_PATH DYLD_INSERT_LIBRARIES " \
+            "DYLD_LIBRARY_PATH\n" \
+            "for v in $(/usr/bin/env | /usr/bin/sed -n 's/^\\(BUNDLE[A-Za-z0-9_]*\\)=.*/\\1/p'); do unset \"$v\"; done\n"
+
+    module_function
+
+    # @return [String] $XDG_STATE_HOME/samagotchi/bin
+    def dir(env: ENV) = File.join(Paths.state_dir(env: env), "bin")
+
+    def path(dir: self.dir) = File.join(dir, NAME)
+
+    # The script for +home+.
+    # @param home [ChiHome::Record]
+    def content(home)
+      argv = home.boot_argv(run: ChiHome::CHI_BOOT) + ["--"]
+      "#!/bin/sh\n#{HEADER}#{UNSET}exec #{argv.map { |arg| Shellwords.escape(arg) }.join(" ")} \"$@\"\n"
+    end
+
+    # Writes the shim for +home+ unless it is already that (atomically: a
+    # tool running `chi` meanwhile gets the old one or the new one).
+    # @return [Boolean] whether the shim is there and current
+    def ensure!(home, dir: self.dir)
+      file = path(dir: dir)
+      want = content(home)
+      return true if current?(file, want)
+
+      FileUtils.mkdir_p(dir)
+      AtomicFile.write(file, want, perm: 0o755)
+      true
+    rescue SystemCallError => e
+      Log.warn(:worker, "chi_shim_failed", path: file, error: e.class.name, msg: e.message)
+      false
+    end
+
+    # Why the shim isn't +home+'s (chi home doctor), or nil: nil too
+    # without one (the first worker start writes it).
+    # @return [String, nil]
+    def problem(home, dir: self.dir)
+      file = path(dir: dir)
+      return nil if !File.exist?(file) || current?(file, content(home))
+
+      "the chi script tools run (#{Paths.tilde(file)}) boots another chi than the home: " \
+        "the next worker start rewrites it (chi sessions restart ID for a running session)"
+    end
+
+    def current?(file, want)
+      File.file?(file) && File.executable?(file) && File.read(file) == want
+    rescue SystemCallError
+      false
+    end
+  end
+end

data/lib/samagotchi/child_env.rb

@@ -2,6 +2,7 @@
 
 require_relative "installed_gem"
 require_relative "installed_versions"
+require_relative "project_env"
 
 module Samagotchi
   # What a chi process another chi starts must not take from its spawner's
@@ -23,11 +24,12 @@ module Samagotchi
     module_function
 
     # The keys of +env+ a child chi must not inherit: the guardrails
-    # settings, the session markers and a smoke's fake "newest installed"
-    # (InstalledVersions::ENV_KEY, for the spawner's notices only).
+    # settings, the session markers, a smoke's fake "newest installed"
+    # (InstalledVersions::ENV_KEY, for the spawner's notices only) and the
+    # worker's project env marker and record (a child worker applies its own).
     # @return [Array<String>]
     def spawner_keys(env = ENV)
-      env.each_key.select { |key| key.start_with?(GUARDRAILS_PREFIX) } + SESSION_MARKERS + [InstalledVersions::ENV_KEY]
+      env.each_key.select { |key| key.start_with?(GUARDRAILS_PREFIX) } + SESSION_MARKERS + [InstalledVersions::ENV_KEY, ProjectEnv::MARKER_ENV, ProjectEnv::ORIG_ENV]
     end
 
     # #spawner_keys mapped to nil: Process.spawn unsets a key mapped to nil.

data/lib/samagotchi/config.rb

@@ -138,6 +138,8 @@ module Samagotchi
       Entry.new(key: "session.keep_status",           yaml_path: %w[session keep_status],           type: :string, default: "", expose: %i[env config cli], lifecycle: :next_retention_sweep),
       Entry.new(key: "session.sweep_interval_hours",  yaml_path: %w[session sweep_interval_hours],  type: :integer, default: 24,   expose: %i[env config cli], lifecycle: :next_retention_sweep),
       Entry.new(key: "session.idle_exit_minutes",     yaml_path: %w[session idle_exit_minutes],     type: :float,   default: 30.0, expose: %i[env config cli], lifecycle: :worker_start),
+      # Tools follow the project: a worker applies its folder's `mise env` at start (ProjectEnv); off keeps the spawner's env.
+      Entry.new(key: "session.project_env",           yaml_path: %w[session project_env],           type: :enum,    default: "mise", expose: %i[env config], enum_values: %w[mise off], lifecycle: :worker_start),
       # Plain `chi` runs like `chi --shared` (bin/chi, LaunchMode); false, or --no-shared per run, keeps the plain REPL. No CLI flag: that would duplicate --shared.
       Entry.new(key: "session.shared",                yaml_path: %w[session shared],                type: :bool,    default: true,  expose: %i[env config], lifecycle: :next_invocation),
       # false: a session nothing happened in is deleted when it is left (SessionManager.discardable?).

data/lib/samagotchi/context_fetch.rb

@@ -5,6 +5,7 @@ require_relative "context_sources"
 require_relative "context_providers"
 require_relative "log"
 require_relative "process_group"
+require_relative "project_env"
 
 module Samagotchi
   # Runs an attached context source's command once and records the result
@@ -108,8 +109,9 @@ module Samagotchi
 
     def env_for(location, name)
       previous = location.snapshot_path(name)
-      { "SAMAGOTCHI_CONTEXT_NAME" => name,
-        "SAMAGOTCHI_CONTEXT_PREVIOUS" => File.exist?(previous) ? previous : nil }
+      # The session's project env (ProjectEnv) under the source's own keys.
+      ProjectEnv.tools_env.merge("SAMAGOTCHI_CONTEXT_NAME" => name,
+                                 "SAMAGOTCHI_CONTEXT_PREVIOUS" => File.exist?(previous) ? previous : nil)
     end
 
     # @return [Run]

data/lib/samagotchi/desktop/macos.rb

@@ -233,6 +233,32 @@ module Samagotchi
         argv && argv_problem(argv)
       end
 
+      # Why the launch file doesn't boot +home+ (chi home doctor), or nil:
+      # it runs [ruby, chi] (installed before the home), boots another Ruby
+      # or gem path (the home was set since), or bakes GEM_HOME/GEM_PATH
+      # under the home's boot. Each fixed by chi desktop upgrade. nil without
+      # a launch file.
+      # @param home [ChiHome::Record]
+      # @return [String, nil]
+      def home_problem(home)
+        launch = read_launch
+        argv = usable_argv(launch)
+        return nil unless argv
+
+        unless home_boot?(argv)
+          return "the desktop helper runs #{argv.first(2).join(" ")}, not the chi home's boot: chi desktop upgrade"
+        end
+        unless ChiHome.real(argv[0]) == ChiHome.real(home.ruby) && argv[2].to_s.start_with?("#{home.prelude};")
+          return "the desktop helper boots the chi home as it was (#{argv[0]}), not as it is now: chi desktop upgrade"
+        end
+
+        env = launch["env"]
+        baked = env.is_a?(Hash) ? GEM_ENV.select { |key| env.key?(key) } : []
+        return nil if baked.empty?
+
+        "the desktop helper's launch file sets #{baked.join(", ")} for its sessions' tools: chi desktop upgrade"
+      end
+
       # The chi version the launch file names, nil without one.
       def launch_version = read_launch["version"]
 

data/lib/samagotchi/guardrails/pair_boundary.rb

@@ -79,6 +79,10 @@ module Samagotchi
              "approves it"
       GIT_CONFIG = "a participant's turn can't change git's global config or set what makes git run a command " \
                    "(core.hooksPath, core.fsmonitor, core.sshCommand, core.pager, core.editor, ! aliases)"
+      ENV_LOADER = "a participant's turn runs mise or direnv: they load the project's env files (a mise.local.toml, " \
+                   "an .envrc), which may hold the owner's secrets, so the owner approves it"
+      MISE_CONFIG = "a participant's turn changes mise's config: the owner's next worker start runs it (its [env] " \
+                    "can run commands), so the owner approves it"
       GIT_HOOKS = "a participant's turn can't write git's hooks (.git/hooks): git runs them in the owner's name"
       # chi web on loopback asks the owner's token too (Web::App#token_gate,
       # LAN mode); this text check stays as defense in depth: a loopback-only
@@ -127,7 +131,8 @@ module Samagotchi
         ParentApprovals::CHI_TEXT,
         %r{\.local/state/samagotchi|web-grants|grants\.json|web-token},
         %r{(?:\A|[\s/'"=])\.(?:ssh|gnupg|aws|kube|docker)(?![\w.-])},
-        %r{(?:\A|[\s/'"=])(?:\.env(?:\.[\w.-]*)?|[._]netrc|\.npmrc|\.pypirc|\.git-credentials)(?![\w-])},
+        %r{(?:\A|[\s/'"=])(?:\.env(?:\.[\w.-]*)?|\.envrc|\.?mise(?:\.[\w-]+)?\.local\.toml|(?:\.config/mise|\.?mise)/config(?:\.[\w-]+)?\.local\.toml|[._]netrc|\.npmrc|\.pypirc|
+           \.git-credentials)(?![\w-])}x,
         /\bid_(?:rsa|dsa|ecdsa|ed25519)\b|credentials|\.(?:pem|p12|pfx|tfstate)\b/
       )
 
@@ -187,16 +192,30 @@ module Samagotchi
       end
 
       # Why the owner is asked (fresh, once): a command that makes a link
-      # (LINK), a write that may land outside the project (OUTSIDE_WRITE, or
+      # (LINK), one that runs mise or direnv (ENV_LOADER), a write to mise's
+      # config (MISE_CONFIG), a write that may land outside the project (OUTSIDE_WRITE, or
       # NO_PROJECT without one); nil when nothing asks.
       def ask_reason(verdict)
         targets = verdict.targets
         return LINK if targets&.command && command(targets, nil).links?
+        return ENV_LOADER if targets&.command && command(targets, nil).loads_env?
+        return MISE_CONFIG if mise_config_write?(verdict)
         return nil unless outside_write?(verdict)
 
         project_root ? OUTSIDE_WRITE : NO_PROJECT
       end
 
+      # A write or edit of a mise config file (PairCommand.mise_config?), or a
+      # command that writes or names one (PairCommand#mise_config_write?).
+      def mise_config_write?(verdict)
+        targets = verdict.targets
+        return false unless targets
+        return command(targets, nil).mise_config_write? if targets.command
+        return false unless WRITE_TOOLS.include?(verdict.call&.dig(:name).to_s)
+
+        targets.paths.to_a.compact.any? { |path| PairCommand.mise_config?(File.expand_path(path, targets.cwd || Dir.pwd)) }
+      end
+
       # A write or edit whose path may land outside the project root, or a
       # command that may write there (PairCommand#outside_writes?); a tmp
       # dir the project isn't in aside (PairCommand.writable?).

data/lib/samagotchi/guardrails/pair_command.rb

@@ -52,6 +52,9 @@ module Samagotchi
       ENV_READERS = %w[printenv security op].freeze
       # Commands that print a stored credential (a token, a password, a
       # key), by the program and the words that say so in its arguments.
+      # Programs that load a project's env files (PairBoundary::ENV_LOADER).
+      ENV_LOADERS = %w[mise direnv].freeze
+      ENV_LOADER_TEXT = %r{(?<![\w./-])(?:mise|direnv)(?![\w./-])}
       CREDENTIAL_PRINTERS = {
         "gh" => [%w[auth token]],
         "git" => [%w[credential], %w[credential-osxkeychain], %w[credential-store], %w[credential-cache],
@@ -139,6 +142,20 @@ module Samagotchi
         Outside.inside?(path, root: root) || Outside.tmp_write?(path, root: root)
       end
 
+      # mise's config files (mise.toml, .mise.toml, mise.<env>.toml, .config/mise.toml,
+      # anything under .config/mise/, mise/ or .mise/ config*.toml): mise runs
+      # their [env] at the next worker start (ProjectEnv).
+      MISE_CONFIG_PATH = %r{(?:\A|/)(?:\.?mise(?:\.[^/]+)?\.toml|\.config/mise\.toml|\.config/mise/.+|
+                             \.?mise/config[^/]*\.toml)\z}x
+      MISE_CONFIG_TEXT = %r{(?<![\w-])(?:\.?mise(?:\.[\w.-]+)?\.toml|\.config/mise|\.?mise/config[\w.-]*\.toml)}
+
+      # Whether +path+ is one of mise's config files (MISE_CONFIG_PATH), as
+      # given or as it resolves.
+      def self.mise_config?(path)
+        path.to_s.match?(MISE_CONFIG_PATH) ||
+          (path.to_s.start_with?("/") && PathResolve.reals(path).any? { |real| real.match?(MISE_CONFIG_PATH) })
+      end
+
       # Whether +path+ is in a .git/hooks folder, as given or as it resolves
       # (ShellPaths::HOOKS_PART): git runs what is there.
       def self.git_hook?(path)
@@ -193,6 +210,7 @@ module Samagotchi
 
         @refusal = read
       rescue StandardError
+        @mise_config = true
         @refusal = PairBoundary::UNREADABLE
       end
 
@@ -210,6 +228,28 @@ module Samagotchi
         @links = true
       end
 
+      # Whether it runs mise or direnv (ENV_LOADERS): they load the
+      # project's env files (a mise.local.toml, an .envrc), which hold the
+      # owner's secrets, into what the command prints; the owner approves
+      # it. True for one it can't read.
+      def loads_env?
+        return @loads_env if defined?(@loads_env)
+
+        @loads_env = @depth > MAX_DEPTH || ShellLex.simple_commands(ShellLex.lex(@text)).any? do |words|
+          words.is_a?(Array) && env_loader_command?(words)
+        end
+      rescue StandardError
+        @loads_env = true
+      end
+
+      # Whether it writes (or, not only reading, names) a mise config file
+      # (.mise_config?), a script it hands on included: the owner approves
+      # it. True for one it can't read.
+      def mise_config_write?
+        refusal
+        @mise_config ||= false
+      end
+
       # Whether it may write outside the project (asked about, never
       # denied); true for one it can't read.
       def outside_writes?
@@ -313,8 +353,10 @@ module Samagotchi
         program = File.basename(words[at])
         scripts(words, at).each do |script|
           reason = if SHELLS.include?(program) || program == "eval"
-                     nested(script).refusal
+                     inner = nested(script)
+                     inner.refusal.tap { @mise_config = true if inner.mise_config_write? }
                    elsif INTERPRETERS.include?(program)
+                     @mise_config = true if script.match?(MISE_CONFIG_TEXT)
                      script_text_refusal(script)
                    end
           return reason if reason
@@ -448,6 +490,8 @@ module Samagotchi
         resolved.each do |word, path|
           return PairBoundary::GIT_HOOKS if !@read_only && PairCommand.git_hook?(path || word)
 
+          @mise_config = true if !@read_only && PairCommand.mise_config?(path || word)
+
           if path
             return PairBoundary::SECRET if @paths.secret_refusal([path])
             return PairBoundary::HOME_SWEEP if SWEEPERS.include?(program_word) && above_denied?(path)
@@ -512,6 +556,18 @@ module Samagotchi
         end
       end
 
+      def env_loader_command?(words)
+        at = program_at(words)
+        return true if at && ENV_LOADERS.include?(File.basename(words[at]))
+        return true if words.each_cons(2).any? { |option, word| CODE_OPTIONS.include?(option) && ENV_LOADERS.include?(File.basename(word)) }
+
+        runner = (0..(at || (words.size - 1))).find { |i| runner?(words[i]) } or return false
+        name = File.basename(words[runner])
+        scripts(words, runner).any? do |script|
+          SHELLS.include?(name) || name == "eval" ? nested(script).loads_env? : script.match?(ENV_LOADER_TEXT)
+        end
+      end
+
       def nested(script) = PairCommand.new(script, cwd: @cwd, paths: @paths, home: @home, root: @root,
                                                    depth: @depth + 1, web: @web)
 

data/lib/samagotchi/guardrails/review_paths.rb

@@ -30,13 +30,16 @@ module Samagotchi
                              .netrc .npmrc .pypirc .claude.json .zsh_history .bash_history .history .python_history
                              .node_repl_history .psql_history .mysql_history .irb_history .lesshst
                              .local/share/fish/fish_history].freeze
-      # Project files that hold secrets, by a path part's name: .env*,
-      # netrc, keys and certificates, anything named credentials, package
+      # Project files that hold secrets, by a path part's name: .env* (.envrc
+      # too), mise's local files (mise.local.toml, .mise.dev.local.toml), netrc, keys and certificates, anything named credentials, package
       # registry tokens (.npmrc, .pypirc), ssh keys, terraform state, a
       # secrets file; and a git config (.git/config, a submodule's
       # .git/modules/x/config), checked apart.
-      SECRET_FILE = /\A(?:\.env.*|[._]netrc|.*\.(?:pem|key|p12|pfx|tfstate(?:\.backup)?)|.*credentials.*|
+      SECRET_FILE = /\A(?:\.env.*|\.?mise(?:\.[\w-]+)?\.local\.toml|[._]netrc|.*\.(?:pem|key|p12|pfx|tfstate(?:\.backup)?)|.*credentials.*|
                        \.npmrc|\.pypirc|\.git-credentials|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|secrets?\.(?:ya?ml|json))\z/xi
+      # mise's local config in its config dirs (.config/mise/config.local.toml,
+      # config.<env>.local.toml; mise/ and .mise/ too): by the path's end.
+      SECRET_PATH = %r{(?:\A|/)(?:\.config/mise|\.?mise)/config(?:\.[\w-]+)?\.local\.toml\z}i
       # The .docker/config.json kind: a dot dir's config holding tokens.
       SECRET_DIR_FILES = { ".docker" => "config.json", ".kube" => "config" }.freeze
       GIT_DIR = ".git"
@@ -124,7 +127,7 @@ module Samagotchi
         return true if denied_roots.any? { |root| PathResolve.under?(path, root) }
 
         parts = path.split(File::SEPARATOR)
-        return true if parts.any? { |part| SECRET_FILE.match?(part) }
+        return true if parts.any? { |part| SECRET_FILE.match?(part) } || path.match?(SECRET_PATH)
         return true if parts.each_cons(2).any? { |dir, file| SECRET_DIR_FILES[dir.downcase] == file.downcase }
 
         git_config?(parts)

data/lib/samagotchi/home_command.rb

@@ -2,6 +2,7 @@
 
 require "rbconfig"
 require_relative "chi_home"
+require_relative "home_doctor"
 require_relative "cli/command"
 require_relative "cli/exit"
 require_relative "cli/flags"
@@ -12,7 +13,7 @@ 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).
+  # (`chi home doctor`, HomeDoctor's rows).
   class HomeCommand
     include CLI::Command
 
@@ -23,7 +24,9 @@ module Samagotchi
                           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
+        doctor            check the home (its Ruby is there and has samagotchi) and what should
+                          follow it: this chi, the desktop helper, sessions, the tools' chi script,
+                          this project's Gemfile.lock, mise and the last worker's project env
         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)}.
@@ -38,8 +41,9 @@ module Samagotchi
 
     # @param path [String] home.json
     # @param probe [#call] (ruby) → ChiHome::Record or nil (ChiHome.probe)
+    # @param doctor [#call] (home) → HomeDoctor
     def initialize(argv, stdout: $stdout, stderr: $stderr, path: ChiHome.path, gem_spec: InstalledGem.spec,
-                   env: ENV, probe: nil)
+                   env: ENV, probe: nil, doctor: nil)
       @argv = argv.dup
       @stdout = stdout
       @stderr = stderr
@@ -47,6 +51,9 @@ module Samagotchi
       @gem_spec = gem_spec
       @env = env
       @probe = probe || ->(ruby) { ChiHome.probe(ruby, env: env) }
+      @doctor = doctor || lambda { |home|
+        HomeDoctor.new(home: home, env: env, gem_spec: gem_spec, helper: HomeDoctor.default_helper(env: env))
+      }
     end
 
     # @return [Integer] 0, 1 (no usable home, a refusal), 2 usage
@@ -127,23 +134,12 @@ module Samagotchi
       home
     end
 
-    # P2c adds rows (running chi vs the home, the helper's argv, sessions,
-    # the project env); for now the home's own.
+    # The home's rows and what should follow it (HomeDoctor); exit 1 when
+    # one fails.
     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
+      rows = @doctor.call(ChiHome.read(path: @path)).rows
+      rows.each { |row| @stdout.puts(row.to_s) }
+      rows.any? { |row| row.status == :fail } ? CLI::Exit::FAILED : CLI::Exit::OK
     end
   end
 end

data/lib/samagotchi/home_doctor.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "chi_home"
+require_relative "chi_shim"
+require_relative "config"
+require_relative "desktop"
+require_relative "home_notice"
+require_relative "installed_gem"
+require_relative "log_path"
+require_relative "paths"
+require_relative "project_env"
+require_relative "session"
+require_relative "version"
+
+module Samagotchi
+  # `chi home doctor`'s rows: the chi home (ChiHome) and what should follow
+  # it, each one line with a status and what to run. One check each; the
+  # text is the condition owner's (ChiHome, HomeNotice, Desktop::MacOS,
+  # ChiShim, ProjectEnv) where another surface says the same.
+  class HomeDoctor
+    # +status+ :ok, :warn (works, not as intended) or :fail (a launch can't
+    # boot what it should).
+    Row = Data.define(:status, :text) do
+      def to_s = "#{status.to_s.ljust(5)} #{text}"
+    end
+
+    # What a Gemfile.lock that bundles chi has (a GEM or PATH spec line).
+    LOCKED_CHI = /^ {4}samagotchi \(/
+
+    # @param home [ChiHome::Record, nil] home.json's record
+    # @param helper [Desktop::MacOS, nil] the desktop helper (nil off macOS)
+    # @param sessions [#call] () → [Session] this machine's sessions
+    def initialize(home:, env: ENV, cwd: Dir.pwd, gem_spec: InstalledGem.spec, helper: nil,
+                   sessions: -> { Session.list(state_dir: Session.default_state_dir(env: env)) },
+                   shim_dir: ChiShim.dir(env: env), log_path: LogPath.resolve(env: env),
+                   ruby: RbConfig.ruby, gem_dir: Gem.dir)
+      @home = home
+      @env = env
+      @cwd = cwd
+      @gem_spec = gem_spec
+      @helper = helper
+      @sessions = sessions
+      @shim_dir = shim_dir
+      @log_path = log_path
+      @ruby = ruby
+      @gem_dir = gem_dir
+    end
+
+    # @return [Array<Row>]
+    def rows
+      list = [home_row]
+      if @home && !ChiHome.problem(@home)
+        list.concat([running_row, helper_row, sessions_row, shim_row].compact)
+      end
+      list.concat([gemfile_row, mise_row, project_env_row].compact)
+    end
+
+    # The desktop helper chi home doctor checks: this machine's, when it
+    # is installed.
+    def self.default_helper(env: ENV)
+      return nil unless Desktop.supported?
+
+      helper = Desktop::MacOS.new(env: env, register: false)
+      File.file?(helper.launch_path) ? helper : nil
+    end
+
+    private
+
+    def ok_row(text) = Row.new(status: :ok, text: text)
+    def warn_row(text) = Row.new(status: :warn, text: text)
+    def fail_row(text) = Row.new(status: :fail, text: text)
+
+    def home_row
+      return ok_row("no chi home: each launch uses the Ruby that starts it (chi home set to record one)") unless @home
+
+      if (problem = ChiHome.problem(@home))
+        return fail_row("#{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")
+      end
+
+      ok_row("chi home #{@home.ruby} runs chi #{@home.newest_version}")
+    end
+
+    def running_row
+      return ok_row("this chi runs from a source checkout: it starts its own code, not the home") unless @gem_spec
+
+      text = HomeNotice.mismatch(@home, ruby: @ruby, gem_dir: @gem_dir)
+      text && warn_row("#{text}: launches boot the home; chi home set makes this chi the home")
+    end
+
+    def helper_row
+      return nil unless @helper
+
+      if (problem = @helper.launch_problem)
+        fail_row(problem)
+      elsif (problem = @helper.home_problem(@home))
+        warn_row(problem)
+      end
+    end
+
+    # Sessions last saved by a newer chi than the home's: their workers
+    # (the home's chi) run them without what that chi added.
+    def sessions_row
+      newest = @home.newest_version
+      newer = @sessions.call.filter_map do |session|
+        version = session.written_by
+        Gem::Version.new(version) if version.is_a?(String) && Gem::Version.correct?(version)
+      end.select { |version| version > newest }
+      return nil if newer.empty?
+
+      count = newer.size == 1 ? "1 session was" : "#{newer.size} sessions were"
+      warn_row("#{count} last saved by a newer chi (#{newer.max}) than the home's #{newest}: " \
+           "their workers run without what it added; chi update brings the home up to date")
+    end
+
+    def shim_row
+      problem = ChiShim.problem(@home, dir: @shim_dir)
+      problem && warn_row(problem)
+    end
+
+    # The cwd's project bundling chi (a Gemfile.lock with samagotchi):
+    # `bundle exec chi` there runs the bundle's chi, off the home.
+    def gemfile_row
+      lock = project_lockfile
+      return nil unless lock && File.read(lock).match?(LOCKED_CHI)
+
+      warn_row("#{Paths.tilde(lock)} bundles samagotchi: chi under the project's bundle (bundle exec chi) isn't " \
+           "supported; run chi itself, and bundle remove samagotchi there")
+    rescue SystemCallError
+      nil
+    end
+
+    # The nearest Gemfile.lock from the cwd up to its git root; nil for
+    # chi's own source tree (its gemspec is next to it).
+    def project_lockfile
+      dir = project_dirs.find { |candidate| File.file?(File.join(candidate, "Gemfile.lock")) }
+      return nil if dir.nil? || File.file?(File.join(dir, "samagotchi.gemspec"))
+
+      File.join(dir, "Gemfile.lock")
+    end
+
+    # The cwd and the folders above it up to its git root (the cwd alone
+    # outside git).
+    def project_dirs
+      @project_dirs ||= begin
+        dirs = []
+        dir = File.expand_path(@cwd)
+        loop do
+          dirs << dir
+          break if File.exist?(File.join(dir, ".git"))
+
+          parent = File.dirname(dir)
+          break dirs = [dirs.first] if parent == dir
+
+          dir = parent
+        end
+        dirs
+      end
+    end
+
+    def mise_row
+      mode, origin = Config.get_with_origin("session.project_env")
+      return ok_row("project env off (session.project_env: off): tools keep the env of whoever starts the worker") if mode.to_s == "off"
+
+      mise = ProjectEnv.find_mise(env: @env)
+      return ok_row("project env: mise (#{mise})") if mise
+
+      origin == :default ? ok_row(ProjectEnv::NO_MISE) : warn_row(ProjectEnv::NO_MISE)
+    end
+
+    def project_env_row
+      warning = ProjectEnv.last_warning(project_dirs, log_path: @log_path)
+      warning && warn_row(warning.message)
+    end
+  end
+end