samagotchi 0.156.0 → 0.158.0

data/lib/samagotchi/plugin/loader.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "digest"
 require_relative "api"
 require_relative "context"
 require_relative "../hooks"
@@ -10,6 +11,11 @@ require_relative "../memory_bundle/manifest"
 require_relative "../memory_bundle/provenance"
 
 module Samagotchi
+  # Where installed bundles' plugin code is evaluated: one module per
+  # bundle (Plugin::Loader.namespace_for), so two bundles defining the same
+  # class name can't collide on a top-level constant.
+  module Bundles; end
+
   module Plugin
     # What a plugin registers into: an Engine's own registries.
     # +context_for+ is (bundle_name, settings, label) → the Plugin::Context
@@ -25,7 +31,8 @@ module Samagotchi
     # +prompt_changed+ rebuilds its system prompts (chi.prompt_changed!),
     # +judgments+ the Engine's SystemOne::Judgments (chi.judgment),
     # +hook_failed+ is (label, "Class: message") when a chi.on handler
-    # raises (HookRoutes#plugin_hook_failed).
+    # raises, with effect: :deny for a fail-closed one
+    # (HookRoutes#plugin_hook_failed).
     Registries = Struct.new(:commands, :tools, :hooks, :context_for, :tools_changed, :services, :stage_tools, :init,
                             :toolkits, :tool_index, :peer_sources, :prompt_sections, :prompt_changed, :judgments,
                             :hook_failed, keyword_init: true)
@@ -35,14 +42,19 @@ module Samagotchi
     #
     # For each bundle, by name: the file must match the sha256 recorded at
     # install and chi must meet the bundle's requires_chi. The file is
-    # module_eval'd into the bundle's namespace (as its hooks are), the
+    # module_eval'd into the bundle's namespace (#namespace_for), the
     # class named like the file (plugin.rb → Plugin) is built with the
     # bundle's settings, and its #register gets a Plugin::Api. What it
     # registered takes effect only when #register returns: a plugin that
     # fails adds nothing.
     #
     # A failure is logged and added to +failures+ (not required: tool calls
-    # still run), which the Engine announces once. Not fail-closed.
+    # still run), which the Engine announces once. A guardrail plugin's
+    # (the manifest's plugin: required: true, read from the kept manifest:
+    # InstalledManifest#plugin_required) goes to +guardrail_failures+ as
+    # required instead: every tool call is denied, as for a fail-closed
+    # config hook. Its chi.on(..., on_error: :fail_closed) hooks deny the
+    # call they raise on (Api#on).
     module Loader
       TAG = :plugins
 
@@ -50,12 +62,16 @@ module Samagotchi
 
       # @param registries [Registries]
       # @param failures [Guardrails::LoadFailures, nil]
+      # @param guardrail_failures [Guardrails::LoadFailures, nil] where a
+      #   required plugin's failure goes (the Engine's guardrail failures);
+      #   nil: +failures+, still required
       # @param settings [Hash{String => Hash}] config.yml `bundles:`
       # @return [Array<String>] the bundles whose plugin loaded
-      def load_installed(registries, failures: nil, settings: {})
+      def load_installed(registries, failures: nil, guardrail_failures: nil, settings: {})
         loaded = []
         MemoryBundle::Provenance.each_installed(holding: :plugin) do |bundle_name, bundle|
-          ok = load_bundle(bundle_name, bundle, registries, failures: failures, settings: settings[bundle_name.to_s] || {})
+          ok = load_bundle(bundle_name, bundle, registries, failures: failures, guardrail_failures: guardrail_failures,
+                                                            settings: settings[bundle_name.to_s] || {})
           loaded << bundle_name if ok
         end
         loaded
@@ -66,22 +82,35 @@ module Samagotchi
       end
 
       # @return [Boolean] whether the plugin loaded
-      def load_bundle(bundle_name, bundle, registries, failures: nil, settings: {})
+      def load_bundle(bundle_name, bundle, registries, failures: nil, guardrail_failures: nil, settings: {})
         file = MemoryBundle::Provenance.new(name: bundle_name).plugin_path(bundle) unless bundle.error?
         basename = file ? File.basename(file) : "plugin"
+        # Known before it registers anything: a guardrail that fails to load
+        # (its sha, requires_chi, a raise) denies every tool call.
+        required = !bundle.error? && bundle.manifest.plugin_required
+        into = required ? guardrail_failures || failures : failures
         reason = bundle.error || unloadable_reason(file, bundle)
-        return failed(bundle_name, basename, reason, failures) if reason
+        return failed(bundle_name, basename, reason, into, required: required) if reason
 
         api = register_file(bundle_name, file, registries, settings: settings)
+        warn_unrequired(bundle_name, basename) if api.fail_closed? && !required
         Log.info(TAG, "plugin_loaded", bundle: bundle_name, file: basename, **api.counts)
         true
       rescue Exception => e # rubocop:disable Lint/RescueException -- a plugin's SyntaxError or exit must not stop chi
         raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
 
-        failed(bundle_name, basename, "#{e.class}: #{e.message}", failures,
+        failed(bundle_name, basename, "#{e.class}: #{e.message}", into || failures, required: required == true,
                location: file && Guardrails::LoadFailures.location(e, File.dirname(file)))
       end
 
+      # A fail-closed hook from a plugin its manifest doesn't call required:
+      # it denies the call it raises on, but a load failure would not deny.
+      def warn_unrequired(bundle_name, basename)
+        text = "#{label(bundle_name, basename)} has a fail-closed hook but its manifest's plugin: has no required: true, " \
+               "so a failure to load it would not deny tool calls"
+        Log.warn(TAG, "plugin_fail_closed_unrequired", bundle: bundle_name, file: basename, msg: text)
+      end
+
       # Build +file+'s plugin with +settings+ and commit what its #register
       # staged into +registries+ (no sha or requires_chi check: #load_bundle
       # makes them; the test kit loads a bundle's source this way).
@@ -117,14 +146,45 @@ module Samagotchi
         return failure if failure
         return "the file is missing" unless file && File.file?(file)
 
-        Hooks::BundleLoader.sha_mismatch(file, bundle.plugin.sha256, required: true)
+        sha_mismatch(file, bundle.plugin.sha256)
+      end
+
+      # Why +file+ doesn't match the sha256 recorded at install (+recorded+,
+      # "sha256:<hex>" or bare hex), or nil. None recorded is a mismatch;
+      # Provenance.unchecked? (a dev install) is none.
+      def sha_mismatch(file, recorded)
+        return nil if MemoryBundle::Provenance.unchecked?(recorded)
+
+        expected = MemoryBundle::Provenance.recorded_sha(recorded)
+        return "no sha256 recorded for it (reinstall the bundle)" if expected.empty?
+
+        actual = MemoryBundle::Provenance.file_sha(file)
+        return nil if actual == expected
+
+        "its sha256 #{actual[0, 12]}… differs from the installed #{expected[0, 12]}… (edited after install? reinstall the bundle)"
+      end
+
+      # The (lazily created) namespace module for a bundle, under
+      # Samagotchi::Bundles. The name is sanitized and made injective by a
+      # short digest, so `my-bundle` and `my_bundle` don't collide.
+      def namespace_for(bundle_name)
+        raw = bundle_name.to_s
+        base = raw.gsub(/[^A-Za-z0-9_]/, "_")
+        base = "B_#{base}" unless base.match?(/\A[A-Z]/)
+        ns_name = :"#{base}_#{Digest::MD5.hexdigest(raw)[0, 4]}"
+        if Samagotchi::Bundles.const_defined?(ns_name, false)
+          Samagotchi::Bundles.const_get(ns_name)
+        else
+          Samagotchi::Bundles.const_set(ns_name, Module.new)
+        end
       end
 
       # module_eval the file into a fresh module in the bundle's namespace
       # (Samagotchi::Bundles::<bundle>::PluginLoad<n>: each load gets new
       # classes, not the last load's reopened) and build its class
-      # (plugin.rb → Plugin; my_plugin.rb → MyPlugin) as hooks are built:
-      # an initialize that takes an argument gets the settings.
+      # (plugin.rb → Plugin; my_plugin.rb → MyPlugin) as config hooks are
+      # built (Hooks.build_plugin): an initialize that takes an argument
+      # gets the settings.
       def instantiate(bundle_name, file, settings, namespace: nil)
         namespace ||= fresh_namespace(bundle_name)
         namespace.module_eval(File.read(file), file, 1)
@@ -140,14 +200,14 @@ module Samagotchi
       def fresh_namespace(bundle_name)
         LOADS.synchronize do
           @loads = (@loads || 0) + 1
-          Hooks::BundleLoader.namespace_for(bundle_name).const_set(:"PluginLoad#{@loads}", Module.new)
+          namespace_for(bundle_name).const_set(:"PluginLoad#{@loads}", Module.new)
         end
       end
 
-      def failed(bundle_name, basename, reason, failures, location: nil)
+      def failed(bundle_name, basename, reason, failures, required: false, location: nil)
         Log.warn(TAG, "plugin_not_loaded", echo: "[samagotchi:plugins] bundle '#{bundle_name}' plugin '#{basename}' not loaded: #{reason}",
-                                           bundle: bundle_name, file: basename)
-        failures&.add("plugin #{basename} (bundle #{bundle_name})", reason, required: false, location: location)
+                                           bundle: bundle_name, file: basename, required: required)
+        failures&.add("plugin #{basename} (bundle #{bundle_name})", reason, required: required, location: location)
         false
       end
     end

data/lib/samagotchi/plugin/sessions.rb

@@ -223,7 +223,7 @@ module Samagotchi
         return if running.size < max
 
         raise Error, "#{running.size} child sessions of this session are running (the most is #{max}, " \
-                     "#{Tools::Delegate::MAX_CHILDREN_KEY}): #{running.map { |s| s[:short_id] }.join(", ")}"
+                     "#{Tools::Delegate::MAX_CHILDREN_KEY}): #{running.map(&:short_id).join(", ")}"
       end
 
       def live_snapshot(sid, state_dir)

data/lib/samagotchi/project_command.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "guardrails/path_resolve"
+require_relative "memory_paths"
+require_relative "paths"
+require_relative "project_init"
+
+module Samagotchi
+  # `chi project`: which project this folder is in (MemoryPaths.lookup: a
+  # git repository, a folder marked with `.chi/project.yml`, or none) and
+  # its project memories folder; `chi project init [DIR]` marks a folder in
+  # no git repository as a project. Git wins: a repository is already the
+  # project, so init writes nothing there. Machine-local
+  # (SessionAccess::Contract::MACHINE).
+  class ProjectCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi project [init [DIR]]
+        (none)       this folder's project: how it was found (git, marker or none), its root, its
+                     top and its project memories folder
+        init [DIR]   make DIR (default: this folder; created when missing) a chi project: writes
+                     DIR/#{MemoryPaths::MARKER}, so DIR and every subfolder share one project memories
+                     folder and group their sessions. Not in a git repository (it already is the
+                     project), nor $HOME or a folder above it
+    TEXT
+
+    SUBCOMMANDS = %w[init].freeze
+    FLAGS = {
+      nil => CLI::Flags.new(help: HELP_WORDS, args: false),
+      "init" => CLI::Flags.new(help: HELP_WORDS)
+    }.freeze
+
+    # @param cwd [String] the folder asked about (Dir.pwd)
+    # @param home [String, nil] $HOME (markers at or above it are ignored)
+    # @param sessions [#call, nil] () → this machine's SessionRows (for
+    #   init's restart note; SessionManager.session_rows by default)
+    def initialize(argv, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd, env: ENV, home: MemoryPaths.default_home,
+                   sessions: nil)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @cwd = cwd
+      @env = env
+      @home = home
+      @sessions = sessions || lambda {
+        require_relative "session_manager"
+        SessionManager.session_rows
+      }
+    end
+
+    # @return [Integer] 0, 1 (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)
+
+      return run_show unless @sub
+      return usage_error("init takes one folder") if parsed.args.size > 1
+
+      run_init(parsed.args.first || @cwd)
+    end
+
+    private
+
+    def command_name = @sub ? "chi project #{@sub}" : "chi project"
+    def usage_on_error = nil
+
+    def lookup(dir) = MemoryPaths.lookup(dir, home: @home)
+
+    def run_show
+      found = lookup(@cwd)
+      row("kind", found.kind.to_s)
+      if found.project?
+        row("root", found.root)
+        row("top", found.top)
+      end
+      row("memories", memories_line(found.root))
+      notes(found).each { |note| row("note", note) }
+      CLI::Exit::OK
+    end
+
+    def row(label, value) = @stdout.puts("#{label.ljust(9)}#{value}")
+
+    def memories_line(root)
+      dir = File.join(MemoryPaths.projects_dir(env: @env), MemoryPaths.key_for_root(root))
+      count = memory_count(dir)
+      "#{Paths.tilde(dir)}#{" (#{count} #{count == 1 ? "memory" : "memories"})" if count.positive?}"
+    end
+
+    def memory_count(dir)
+      return 0 unless File.directory?(dir)
+
+      Dir.children(dir).count { |name| name.end_with?(".md") && name != "index.md" }
+    end
+
+    def notes(found)
+      case found.kind
+      when :git
+        list = []
+        list << "#{Paths.tilde(found.top)} is $HOME, a git repository: every folder under it is in that repository" if home_repo?(found)
+        marker = MemoryPaths.nearest_marker(@cwd, home: @home)
+        list << "#{Paths.tilde(File.join(marker, MemoryPaths::MARKER))} is ignored: the git repository is the project" if marker
+        list
+      when :none then ["no git repository or chi project marker here: chi project init makes this folder a project"]
+      else []
+      end
+    end
+
+    def home_repo?(found)
+      !@home.to_s.empty? && Guardrails::PathResolve.real(found.top) == Guardrails::PathResolve.real(@home)
+    end
+
+    def run_init(dir)
+      dir = File.expand_path(dir, @cwd)
+      outcome = ProjectInit.call(dir, home: @home)
+      case outcome.kind
+      when :git
+        found = MemoryPaths::ProjectLookup.new(kind: :git, root: outcome.root, top: outcome.top)
+        note = home_repo?(found) ? " ($HOME is a git repository: every folder under it is in it)" : ""
+        @stdout.puts("#{outcome.message}#{note}")
+        CLI::Exit::OK
+      when :refused
+        error_line("#{command_name}: #{outcome.message}")
+        CLI::Exit::FAILED
+      when :already_marked
+        @stdout.puts(outcome.message)
+        CLI::Exit::OK
+      when :created
+        report_init(outcome.root, nested_in: outcome.nested_in)
+        CLI::Exit::OK
+      end
+    rescue SystemCallError => e
+      error_line("#{command_name}: couldn't write #{Paths.tilde(File.join(dir, MemoryPaths::MARKER))}: #{e.message}")
+      CLI::Exit::FAILED
+    end
+
+    def report_init(root, nested_in:)
+      nested = nested_in ? ", its own project nested in #{Paths.tilde(nested_in)}" : ""
+      @stdout.puts("#{Paths.tilde(root)} is now a chi project#{nested} (#{Paths.tilde(File.join(root, MemoryPaths::MARKER))})")
+      row("memories", memories_line(root))
+      sessions_note(root)
+    end
+
+    # Sessions in the new project (not one under DIR that a nested
+    # repository or marked folder keeps): a running one keeps its old project in its
+    # prompt (the memories folder line, the AGENTS.md chain) until it
+    # restarts; a running chi web groups the older ones after its restart
+    # (SessionHub looked their project up once).
+    def sessions_note(root)
+      rows = @sessions.call.select { |r| !r.cwd.to_s.empty? && lookup(r.cwd.to_s).root == root }
+      return if rows.empty?
+
+      live = rows.select(&:live)
+      unless live.empty?
+        @stdout.puts("running sessions in it keep the old project in their prompt until restarted " \
+                     "(chi sessions restart ID): #{live.map { |r| r.id[0, 8] }.join(", ")}")
+      end
+      @stdout.puts("#{rows.size} saved session(s) in it join the project in a running chi web after its restart")
+    rescue StandardError => e
+      error_line("#{command_name}: couldn't list this machine's sessions (#{e.message})")
+    end
+  end
+end

data/lib/samagotchi/project_init.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "guardrails/path_resolve"
+require_relative "memory_paths"
+require_relative "paths"
+
+module Samagotchi
+  # The shared decisions for `chi project init` and chi web's project picker.
+  module ProjectInit
+    Outcome = Data.define(:kind, :reason, :root, :top, :nested_in, :message)
+
+    MARKER_TEXT = "# chi project marker: this folder is a chi project (docs/memory.md)\n"
+
+    module_function
+
+    def call(dir, home:)
+      dir = File.expand_path(dir.to_s)
+      found = MemoryPaths.lookup(dir, home: home)
+      if found.git?
+        message = "#{Paths.tilde(dir)} is in the git repository #{Paths.tilde(found.top)}: the repository already is " \
+                  "the project, nothing written"
+        return Outcome.new(kind: :git, reason: nil, root: found.root, top: found.top, nested_in: nil, message: message)
+      end
+      if MemoryPaths.above_home?(dir, home: home)
+        message = "#{Paths.tilde(dir)} is $HOME, a folder above it or /: it can't be a chi project " \
+                  "(every folder under it would be one); mark a folder inside it"
+        return Outcome.new(kind: :refused, reason: :above_home, root: found.root, top: found.top, nested_in: nil,
+                           message: message)
+      end
+
+      # The marked project this folder sits in, if any: the folder itself (already marked) or its parent project.
+      enclosing = found.marker? ? found.root : nil
+      if enclosing == Guardrails::PathResolve.real(dir)
+        return Outcome.new(kind: :already_marked, reason: nil, root: enclosing, top: found.top, nested_in: nil,
+                           message: "#{Paths.tilde(enclosing)} is already a chi project")
+      end
+
+      write_marker(dir)
+      root = File.realpath(dir)
+      # No message: each surface words its own success (the CLI's report, the web's navigation).
+      Outcome.new(kind: :created, reason: nil, root: root, top: root, nested_in: enclosing, message: nil)
+    rescue SystemCallError => e
+      marker = File.join(dir, MemoryPaths::MARKER)
+      write_failed("couldn't write #{Paths.tilde(marker)}: #{e.message}")
+    end
+
+    # chi web opens a folder in a git repository without marking it, so the folder has to exist.
+    # @return [Outcome, nil] a refused (:write_failed) outcome when it can't be made, else nil
+    def ensure_folder(dir)
+      FileUtils.mkdir_p(dir) unless File.directory?(dir)
+      nil
+    rescue SystemCallError => e
+      write_failed("couldn't create #{Paths.tilde(dir)}: #{e.message}")
+    end
+
+    def write_failed(message)
+      Outcome.new(kind: :refused, reason: :write_failed, root: nil, top: nil, nested_in: nil, message: message)
+    end
+    private_class_method :write_failed
+
+    def write_marker(dir)
+      marker = File.join(dir, MemoryPaths::MARKER)
+      FileUtils.mkdir_p(File.dirname(marker))
+      File.write(marker, MARKER_TEXT)
+    end
+    private_class_method :write_marker
+  end
+end

data/lib/samagotchi/project_scope.rb

@@ -4,9 +4,10 @@ require_relative "memory_paths"
 
 module Samagotchi
   # Which project a folder belongs to, for scoping session lists (web and
-  # terminal alike): the project root memories use (MemoryPaths.project_root),
-  # so every worktree and subfolder of one repository is one project. A
-  # folder in no git repository has no project (nil): its scope is "all".
+  # terminal alike): the project root memories use (MemoryPaths.lookup), so
+  # every worktree and subfolder of one repository, or every subfolder of a
+  # folder marked by `chi project init`, is one project. A folder in neither
+  # has no project (nil): its scope is "all".
   module ProjectScope
     module_function
 
@@ -17,7 +18,8 @@ module Samagotchi
       return nil if dir.empty?
       return cache[dir] if cache&.key?(dir)
 
-      root = MemoryPaths.in_repo?(dir) ? MemoryPaths.project_root(File.expand_path(dir)) : nil
+      found = MemoryPaths.lookup(File.expand_path(dir))
+      root = found.project? ? found.root : nil
       cache[dir] = root if cache
       root
     end

data/lib/samagotchi/prompt_files.rb

@@ -19,9 +19,10 @@ module Samagotchi
     module_function
 
     # The AGENTS.md files a session in +cwd+ loads, as absolute paths,
-    # outermost first: inside a git work tree every one from its top (a
-    # linked worktree's own checkout) down to the cwd; outside a repository
-    # only the cwd's ([] with none).
+    # outermost first: inside a project every one from its top
+    # (MemoryPaths.project_top: a git work tree's, a linked worktree's own
+    # checkout, or a folder marked by `chi project init`) down to the cwd;
+    # outside a project only the cwd's ([] with none).
     # @param cwd [String] where the prompt is built (Dir.pwd, not the
     #   session's working directory: /tmp vs /private/tmp would change the
     #   prompt bytes)
@@ -33,10 +34,10 @@ module Samagotchi
     # The sections of the AGENTS.md chain (#agents_paths) with text: the
     # first keeps the plain header (a one-file session's prompt is as it
     # always was), each further one names its directory relative to the
-    # work tree top ("Project specific description for pkg/:").
+    # project's top ("Project specific description for pkg/:").
     # @return [Array<Section>]
     def agents_sections(cwd)
-      top = MemoryPaths.work_tree_root(cwd)
+      top = MemoryPaths.project_top(cwd)
       sections = []
       agents_paths(cwd).each do |path|
         dir = File.dirname(path)
@@ -47,10 +48,12 @@ module Samagotchi
       sections
     end
 
-    # The directories whose AGENTS.md a session in +cwd+ reads, outermost first.
+    # The directories whose AGENTS.md a session in +cwd+ reads, outermost
+    # first: from its project's top (the work tree's, or the marked root)
+    # down to +cwd+.
     def chain_dirs(cwd)
       cwd = File.expand_path(cwd)
-      top = MemoryPaths.work_tree_root(cwd)
+      top = MemoryPaths.project_top(cwd)
       return [cwd] unless top
 
       rel = relative_dir(cwd, top)

data/lib/samagotchi/reasoning_history.rb

@@ -63,38 +63,31 @@ module Samagotchi
       nil
     end
 
-    # The level for +target+ and where it came from ("session",
+    # The level for +lookup+'s model and where it came from ("session",
     # "SAMAGOTCHI_REASONING_HISTORY", "models: qwen", "hosts.work"; nil for
     # the default).
-    # @param target [HostRegistry::ModelTarget]
-    # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
-    # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all (specs)
+    # @param lookup [ModelLookup] the model's layers (EffectiveModel#lookup)
     # @param session [Symbol, nil] the session's own level (Session#reasoning_history)
     # @return [Array(Symbol, String|nil)]
-    def resolve(target, names:, models: nil, session: nil)
+    def resolve(lookup, session: nil)
       return [session, SESSION_SOURCE] if session
 
-      env = env_level
+      env = env_level(lookup)
       return [env, ENV_NAME] if env
 
-      models ||= begin
-        ModelSettings.all
-      rescue StandardError
-        {}
-      end
-      setting = ModelSettings.find(names, :reasoning_history, models: models)
+      setting = lookup.model(:reasoning_history)
       return [setting.value, "models: #{setting.key}"] if setting
 
-      host = target.entry&.reasoning_history
-      return [host, "hosts.#{target.entry.name}"] if host
+      host = lookup.host(:reasoning_history)
+      return [host, "hosts.#{lookup.host_name}"] if host
 
-      [API_DEFAULTS.fetch(target.entry&.api&.to_sym, DEFAULT), nil]
+      [API_DEFAULTS.fetch(lookup.entry&.api&.to_sym, DEFAULT), nil]
     end
 
     # #resolve, as a SettingExplained with the session's own level beside it.
     # @return [SettingExplained]
-    def explain(target, names:, models: nil, session: nil)
-      level, source = resolve(target, names: names, models: models, session: session)
+    def explain(lookup, session: nil)
+      level, source = resolve(lookup, session: session)
       SettingExplained.new(level: level, source: source, own: session)
     end
 
@@ -150,9 +143,10 @@ module Samagotchi
     # "drop (models: qwen)", "turn (default)".
     def label(level, source) = "#{level} (#{source || "default"})"
 
-    # SAMAGOTCHI_REASONING_HISTORY as a level, nil when unset or unknown.
-    def env_level
-      raw, origin = Config.get_with_origin(KEY)
+    # SAMAGOTCHI_REASONING_HISTORY (read with +lookup+'s env) as a level,
+    # nil when unset or unknown.
+    def env_level(lookup)
+      raw, origin = lookup.global(KEY)
       origin == :env ? level(raw, ENV_NAME) : nil
     rescue StandardError
       nil

data/lib/samagotchi/recap_place.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "steer"
+
+module Samagotchi
+  # Where a saved recap sits among the turns a page draws: after the last
+  # turn opening it covers (Steer.turn_opening?, the rule its turns_since
+  # count goes by). Its stamp is that opening's id, as a card's is
+  # (Steer.opening_stamp: a prompt's turn_id, a wake note's, a /continue no
+  # reason line's opening_id), so the page finds the bubble by
+  # id, not by counting back (a rollback or a check-in could make the count
+  # land a turn off). Read at read time from recap.json's `covered`: the file
+  # is unchanged, an old one gets a stamp too. Pure.
+  module RecapPlace
+    module_function
+
+    # @param messages [Array<Hash>] the session's messages (symbol or string keys)
+    # @param covered [Integer] how many of them the recap covers
+    # @return [String, nil] the id of the last opening in the covered
+    #   messages; nil for none, or one with no id (a line an older chi wrote)
+    def opening_id(messages, covered)
+      opening = Array(messages).first([covered.to_i, 0].max).reverse_each.find { |message| Steer.turn_opening?(message) }
+      opening && Steer.opening_stamp(opening)
+    end
+  end
+end

data/lib/samagotchi/reply_wait/liveness.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../worker_link"
+
+module Samagotchi
+  module ReplyWait
+    # Who runs the session, as one look of a wait reads it: one owner lock
+    # read and one WorkerLink resolve on it. Two readers on purpose:
+    # #owner? (any kind, a one-turn chi run's too: its turn is alive) for
+    # whether the worker is gone, #worker_owned? (a worker's lock) for
+    # whether a question waits for an answer (a one-turn run's is answered
+    # there; a dead worker's waits for no one).
+    class Liveness
+      def initialize(id, state_dir:)
+        @id = id
+        @state_dir = state_dir
+      end
+
+      # The lock's holder (SessionManager.session_owner).
+      # @return [OwnerLock::Owner, nil]
+      def owner
+        return @owner if defined?(@owner)
+
+        @owner = SessionManager.session_owner(@id, state_dir: @state_dir)
+      end
+
+      def owner? = !owner.nil?
+
+      def worker_owned?
+        return @worker_owned if defined?(@worker_owned)
+
+        @worker_owned = WorkerLink.resolve(Session.session_dir(@id, state_dir: @state_dir), unlink: false,
+                                                           owner: owner).worker_owned?
+      end
+    end
+  end
+end