samagotchi 0.155.0 → 0.157.0

data/lib/samagotchi/engine.rb

@@ -27,6 +27,7 @@ require_relative "thinking_notices"
 require_relative "cancellation_controller"
 require_relative "context_window"
 require_relative "kernel_loop"
+require_relative "reprefill_meter"
 require_relative "tools/builtins"
 require_relative "tools/task_runtime"
 require_relative "tools/tool_index"
@@ -55,6 +56,7 @@ require_relative "context_judge"
 require_relative "objectives_audit"
 require_relative "owner_prompt"
 require_relative "side_judgments"
+require_relative "system_one/recorder"
 require_relative "toolkit_suggest"
 require_relative "turn_stages/context_judge"
 require_relative "turn_stages/objectives"
@@ -228,7 +230,9 @@ module Samagotchi
       @chat_backend_mutex = Mutex.new
       @side_judgments = SideJudgments.new
       @judgments = build_judgments
-      @host_registry = host_registry || HostRegistry.new
+      # Taken once: a running worker keeps the hosts it started with. A
+      # client (specs) goes on a registry of its own, never the shared one.
+      @host_registry = host_registry || (client ? HostRegistry.new : HostRegistry.current)
       # The turn stages over the objectives (its audit, view and proposals)
       # and the Verify/Revise anchors (TurnStages).
       @objectives_stage = build_objectives_stage
@@ -451,6 +455,9 @@ module Samagotchi
       self.guardrail_state_dir = Session.default_state_dir
       # The turn-end warm-up; the kernel asks it for a slot pin per request.
       @prompt_warmup = PromptWarmup.new
+      # One re-prefill baseline for both loops (the native kernel's and the
+      # chat loop's requests), reset by the warm-up (KernelLoop#warmed_up!).
+      @reprefill = ReprefillMeter.new
       services = KernelLoop::Services.new(
         hooks: @hooks, tools: @tools, reminder_store: @reminder_store, muted_memory_names: @muted_memory_names,
         # ask_user_question blocks on the Engine's question flow (TUI/Web answer it).
@@ -466,8 +473,8 @@ module Samagotchi
       )
       # A given kernel (specs) gets the same services as the one built here.
       @kernel = kernel || KernelLoop.new(client: @client, profile: @model_binding.given_profile,
-                                         model_name: effective_model_name, services: services)
-      @kernel.attach(services) if kernel
+                                         model_name: effective_model_name, services: services, reprefill: @reprefill)
+      @kernel.attach(services, reprefill: @reprefill) if kernel
       sync_kernel_client!
       sync_model_key!
       # What a hook can do beyond reading its event (event[:notify],
@@ -713,7 +720,10 @@ module Samagotchi
     # (its limit goes in last_turn). The end event names its turn
     # (`turn_id:`, as :turn_started does) and, for a Verify turn,
     # `verify: true` (its opening's stamp: a page watching it live offers
-    # no Revise on its answer, verdict or not, as a reload does).
+    # no Revise on its answer, verdict or not, as a reload does). When the
+    # turn keeps messages, the event also names its own range in them,
+    # `kept[kept_from...kept_to]` (display-side: Bridge::TurnDrawings
+    # reads it; no message gains a key).
     def end_turn(turn, outcome, save: false, exhausted: false)
       seconds = turn.elapsed
       turn.outcome = outcome
@@ -722,12 +732,13 @@ module Samagotchi
         event[:turn_id] = turn.id
         event[:verify] = true if turn.verify
         revises = @verify_anchors.stamp_opening(kept, turn, outcome)
+        kept_range!(event, turn, kept)
         replace_session_messages(turn.session, kept) if kept
         verdict = @verify_anchors.record_verdict(turn, outcome)
         event[:verdict] = verdict if verdict
         event[:revises] = revises.to_h if revises
         emit_working_set(turn.on_event, turn.session, turn.session.messages)
-        @objectives_stage.announce(turn.session)
+        announce_objectives(turn.session)
         turn.session.status = Session::STATUS_IDLE
         record_last_turn(turn.session, outcome, seconds, turn.origin, event, limit: exhausted ? turn.limit : nil)
         emit_event(turn.on_event, turn.tag(event))
@@ -739,6 +750,20 @@ module Samagotchi
     end
     private :end_turn
 
+    # The end event's kept_from/kept_to (#end_turn): only when the turn
+    # keeps messages and its start is known (#turn_messages ran). An ending
+    # that replaces an earlier turn's note at the history's tail
+    # (TurnNote.replace_trailing on a Continue stopped before its first step)
+    # leaves only system messages and its own note after it, so the range
+    # still starts at or before the turn's note and draws nothing else.
+    def kept_range!(event, turn, kept)
+      return unless kept && turn.history_size
+
+      event[:kept_from] = turn.history_size
+      event[:kept_to] = kept.size
+    end
+    private :kept_range!
+
     # What a notice may stand in for (hook_notify's fallback_for:).
     NOTICE_FALLBACKS = HookRoutes::NOTICE_FALLBACKS
 
@@ -801,8 +826,11 @@ module Samagotchi
     # +wall+: the wall time it started (MessageTime.now, once): the
     # :turn_started event's at and its user message's (and reminders') stamp.
     # +verify+, +revises+: a Verify turn's claim, a Revise turn's draft.
+    # +history_size+: turn.messages' size under the system head, before
+    # the reminders and the prompt (#turn_messages): where the turn's own
+    # messages start in what it keeps (the end event's kept_from).
     Turn = Struct.new(:context, :prompt, :continue, :on_event, :started_at, :messages, :ended, :prepared_settings,
-                      :limit, :resumed, :resume_from, :wall, :verify, :revises, :outcome) do
+                      :limit, :resumed, :resume_from, :wall, :verify, :revises, :outcome, :history_size) do
       # The turn's id (:turn_started's turn_id, its metrics record's id and
       # its saved prompt's), session, origin and controller: its context's.
       def id = context.id
@@ -911,7 +939,7 @@ module Samagotchi
                                 pending_input: pending_input)
         publish_used_memories(session, on_event)
         complete_turn(turn, result)
-        @turn_warmup.after(turn, result)
+        @turn_warmup.after(turn, result, next_turn_waiting: next_turn_waiting)
         result
       rescue Interrupt => e
         # After the end event (in the after_turn/session_end hooks) the
@@ -941,7 +969,7 @@ module Samagotchi
         @context_judge.show_cards_after_turn
         # Only a completed turn shows its proposal cards; any other's are
         # dropped, so the next turn does not show them either.
-        @objectives_stage.finally(turn)
+        show_objective_proposals(turn)
       end
     end
 
@@ -954,7 +982,7 @@ module Samagotchi
       # A participant's Verify fresh child: every turn is theirs (their
       # author, boundary and cap), whoever started it.
       origin = session.verify_fresh.origin_for(origin) if session.respond_to?(:verify_fresh) && session.verify_fresh
-      verify = @verify_anchors.verified(session, VerifyAnchor.from(verify))
+      verify = @verify_anchors.verified(session, VerifyAnchor.from(verify), state_dir: session_state_dir)
       # Track the active session for recap and status snapshot.
       @session = session
       # status is turn state: running now, idle again before the turn's end
@@ -1044,7 +1072,7 @@ module Samagotchi
       # On mode's ask starts here too; the turn joins it before
       # apply_toolkit! below, so its latency hides behind the probes and
       # the init wait.
-      @toolkit_suggestion.start(turn)
+      @toolkit_suggestion.start(turn, recorder: system_one_recorder)
 
       # The window and the profile probes run after run_turn's probe-cancel
       # swap, so a Stop cuts them; a failure ends the turn as turn_failed.
@@ -1081,8 +1109,8 @@ module Samagotchi
       @toolkit_suggestion.settle(turn)
       # The candidate judge: its asks run beside the turn; on mode's
       # attaches reach the model at the next between-turn delivery.
-      @context_judge.start(turn)
-      @objectives_stage.incoming(turn)
+      @context_judge.start(turn, recorder: system_one_recorder)
+      @objectives_stage.incoming(turn, recorder: system_one_recorder)
       apply_toolkit!(session, turn.on_event)
       refresh_participants!(session)
       # A Stop during the waits above: the turn ends here,
@@ -1119,6 +1147,9 @@ module Samagotchi
       # Built once per Engine (and again after a model switch) so the prompt
       # prefix, and the model server's KV cache for it, stay stable.
       turn.messages = ContextNote.with_system_head(turn.messages, { role: "system", content: system_prompt })
+      # Where the turn's own messages start (the end event's kept_from):
+      # after the head this may have added, before the reminders and prompt.
+      turn.history_size = turn.messages.size
       # Explicit --memory preloads are now known after system prompt build.
       @used_memories.add(activated_memory_names).absorb(session)
 

data/lib/samagotchi/events.rb

@@ -13,8 +13,9 @@ module Samagotchi
     # (#kept_turn?).
     TURN_KEPT = %i[turn_completed turn_canceled].freeze
     # The kinds of a running turn's parts (Bridge::TurnAccumulator), which a
-    # joining UI replays as live events.
-    PART_KINDS = %w[generation thinking text tool input steer reminder notice].freeze
+    # joining UI replays as live events (a card part only in a finished
+    # turn's drawing: a join takes its cards from CardStore).
+    PART_KINDS = %w[generation thinking text tool input steer reminder notice card].freeze
     # Types no Engine emits that a UI handles: the Bridge's stream frames
     # and the web's one synthetic replay event (a prompt merged into the
     # turn, turn_events.js snapshotEvents).

data/lib/samagotchi/extension_load.rb

@@ -49,12 +49,15 @@ module Samagotchi
     end
 
     # Load the installed bundles' plugins into +registries+; one that fails
-    # goes to +failures+, and the rest still load. The block runs after them,
-    # still loading: what it shows is held with theirs.
+    # goes to +failures+, a required one (a guardrail plugin) to the hook
+    # failures, where it denies every tool call, and the rest still load.
+    # The block runs after them, still loading: what it shows is held with
+    # theirs.
     def load_plugins(registries, failures:)
       @held_events = []
       @loading = true
-      Plugin::Loader.load_installed(registries, failures: failures, settings: bundle_settings).tap { yield if block_given? }
+      Plugin::Loader.load_installed(registries, failures: failures, guardrail_failures: @hook_failures, settings: bundle_settings)
+                    .tap { yield if block_given? }
     ensure
       @loading = false
     end

data/lib/samagotchi/guardrails/targets.rb

@@ -113,8 +113,10 @@ module Samagotchi
       # @param model_name [String, nil] the bare model name, for a rule's models:
       # @param registry [Tools::Registry, nil] the session's tools: a plugin
       #   tool's entry says what it acts on (its targets:)
-      # @param surface [Tools::ToolSurface, nil] the turn's: call_tool's
-      #   targets name what the turn reaches (nil: the Registry now)
+      # @param surface [Tools::ToolSurface, nil] the turn's: the entry is
+      #   looked up in it (.entry_of) and call_tool's targets name what it
+      #   reaches (nil: the registry's entry; call_tool's then raises
+      #   Tools::MissingSurface)
       def self.for(call, context, model_key: nil, model_name: nil, registry: nil, surface: nil)
         tool = call[:name].to_s
         base = context.cwd
@@ -143,7 +145,7 @@ module Samagotchi
           given_cwd = given[:cwd].to_s.strip
           cwd = File.expand_path(given_cwd, base) unless given_cwd.empty?
           paths.concat(given[:paths].flat_map { |path| absolutes(path, cwd) })
-          entry = registry && registry[tool]
+          entry = entry_of(tool, registry, surface)
           args = given[:args] || call[:args] if entry && !entry.core? && call[:args].is_a?(Hash)
           acts_as = given[:acts_as]
           label = given[:label]
@@ -164,9 +166,12 @@ module Samagotchi
       # logged). args: counts when it is a Hash; acts_as: is dropped (and
       # logged) when it names a core tool or another bundle's tool, so a
       # call can't pass for one and match (or reuse the approvals of) its
-      # rules. label: counts when it is one short line (.label_of).
+      # rules. label: counts when it is one short line (.label_of). A
+      # missing surface (Tools::MissingSurface) is raised, never taken as
+      # nothing: call_tool's acts_as would go missing, and with it the
+      # mcp_* rules on the call (fail-open).
       def self.plugin_targets(call, registry, surface = nil)
-        entry = registry && registry[call[:name].to_s]
+        entry = entry_of(call[:name], registry, surface)
         none = { command: nil, paths: [], cwd: nil, acts_as: nil, args: nil, label: nil }
         return none unless entry && !entry.core? && entry.targets
 
@@ -176,8 +181,10 @@ module Samagotchi
         given = given.transform_keys(&:to_sym)
         command = given[:command].to_s
         { command: command.empty? ? nil : command, paths: Array(given[:paths]).map(&:to_s), cwd: given[:cwd],
-          acts_as: acts_as_of(given[:acts_as], entry, registry), args: given[:args].is_a?(Hash) ? given[:args] : nil,
+          acts_as: acts_as_of(given[:acts_as], entry, registry, surface), args: given[:args].is_a?(Hash) ? given[:args] : nil,
           label: label_of(given[:label], entry) }
+      rescue Tools::MissingSurface
+        raise
       rescue StandardError => e
         Log.warn(:plugins, "plugin_targets_failed", tool: call[:name].to_s, error: e.class.name,
                                                     msg: "#{call[:name]} targets failed: #{e.message}")
@@ -192,24 +199,32 @@ module Samagotchi
       # name, ToolIndex#claimed), so the registry is the wrong owner test,
       # and a bundle tool sharing an MCP tool's name would otherwise take
       # call_tool calls of that tool out of its mcp_* rules.
-      def self.acts_as_of(name, entry, registry)
+      def self.acts_as_of(name, entry, registry, surface = nil)
         name = name.to_s.strip
         return nil if name.empty? || name == entry.name
 
-        other = registry[name]
+        other = entry_of(name, registry, surface)
         whose = if CORE_TOOLS.include?(name) || other&.core? then "a core tool"
                 elsif other && other.source != entry.source && entry.source != Tools::ToolIndex::SOURCE
                   "bundle #{other.source}'s tool"
                 end
         return name unless whose
 
-        if first_drop?(registry, entry.name, name)
+        if first_drop?(registry || surface, entry.name, name)
           Log.warn(:plugins, "plugin_acts_as_dropped", tool: entry.name, acts_as: name,
                                                        msg: "#{entry.name} targets: acts_as #{name} dropped: it is #{whose}")
         end
         nil
       end
 
+      # The tool +name+ names: the turn's entry (+surface+'s registered),
+      # else +registry+'s (a gate without a turn's surface); nil for none.
+      # @return [Tools::Registry::Entry, nil]
+      def self.entry_of(name, registry, surface)
+        name = name.to_s
+        surface ? surface.registered[name] : registry&.[](name)
+      end
+
       # The drops logged, per registry (a session's): each tool's acts_as
       # once, not at every call (targets run several times a call).
       DROPS_LOGGED = ObjectSpace::WeakKeyMap.new

data/lib/samagotchi/guardrails_command.rb

@@ -190,7 +190,7 @@ module Samagotchi
       threshold = threshold(options[:threshold])
       return usage_error(threshold) if threshold.is_a?(String)
 
-      client = @client || SystemOne::Client.from_config(host_registry: HostRegistry.new, mode: Config.get("guardrails.system_one.mode"), model: options[:model])
+      client = @client || SystemOne::Client.from_config(host_registry: HostRegistry.current, mode: Config.get("guardrails.system_one.mode"), model: options[:model])
       if client.nil?
         error_line("chi guardrails replay: no System 1 client — set guardrails.system_one.mode to audit or on " \
                    "and system_one.host in config.yml")

data/lib/samagotchi/host_address.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require_relative "config"
+
+module Samagotchi
+  # What a host's address says about it, without asking it: whether it is
+  # remote (a provider on the network rather than a local server), and the
+  # configured first-token limit. A leaf: HostRegistry::HostEntry and
+  # BootstrapCommand read it, it reads only Config.
+  module HostAddress
+    # Loopback, private (RFC 1918, IPv6 unique local) and link-local nets.
+    LOCAL_NETS = %w[127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 100.64.0.0/10
+                    ::1/128 fc00::/7 fe80::/10].map { |net| IPAddr.new(net) }.freeze
+
+    # Name suffixes that stay on a home or office network: mDNS, the
+    # special-use and customary private names, router defaults (fritz.box)
+    # and Tailscale's MagicDNS. Compared on whole labels.
+    LOCAL_NAME_SUFFIXES = %w[localhost local lan home home.arpa internal intranet localdomain private corp test
+                             box ts.net].freeze
+
+    # Whether an address is remote: https, an http IP address outside the
+    # local nets (LOCAL_NETS), or an http name with a dot whose suffix isn't
+    # a local one (LOCAL_NAME_SUFFIXES): `gpu.example.com` is remote, while
+    # `box`, `mac.local`, `gpu.lan` and `pc.tail1234.ts.net` are local. chi
+    # doesn't look names up; hosts.<name>.remote overrides either way.
+    def self.remote_address?(scheme, host)
+      return true if scheme.to_s == "https"
+
+      address = IPAddr.new(host.to_s.delete_prefix("[").delete_suffix("]"))
+      address = address.native if address.ipv4_mapped?
+      LOCAL_NETS.none? { |net| net.family == address.family && net.include?(address) }
+    rescue IPAddr::Error
+      remote_name?(host)
+    end
+
+    def self.remote_name?(host)
+      name = host.to_s.downcase.delete_suffix(".")
+      return false unless name.include?(".")
+
+      LOCAL_NAME_SUFFIXES.none? { |suffix| name == suffix || name.end_with?(".#{suffix}") }
+    end
+    private_class_method :remote_name?
+
+    # server.first_token_timeout, or nil when unset or unreadable.
+    def self.configured_first_token_timeout
+      Config.get("server.first_token_timeout")
+    rescue StandardError # degrade-ok: no configured limit; the host's own or the remote default applies
+      nil
+    end
+  end
+end

data/lib/samagotchi/host_config.rb

@@ -8,7 +8,7 @@ require_relative "llm/dialect"
 require_relative "reasoning_history"
 
 module Samagotchi
-  # One config.yml hosts: entry, parsed and checked (ConfigFile.hosts_config
+  # One config.yml hosts: entry, parsed and checked (HostConfig.all
   # holds them by lowercased name; HostRegistry builds its HostEntry from
   # one).
   #
@@ -28,6 +28,77 @@ module Samagotchi
       super(**members.to_h { |m| [m, nil] }, models: {}, **fields)
     end
 
+    # config.yml's hosts: by lowercased name; an entry that is disabled or
+    # invalid (warned) is left out. No entry left: "default", from
+    # server.host/port.
+    # @return [Hash{String => HostConfig}]
+    def self.all(env: ENV, path: ConfigFile.global_path(env: env))
+      data = ConfigFile.read_yaml(env: env, path: path)
+      raw_hosts = data[ConfigFile::HOSTS_KEY] if data.is_a?(Hash)
+
+      normalized = {}
+      if raw_hosts.is_a?(Hash)
+        raw_hosts.each do |raw_name, raw_cfg|
+          host = parse(raw_name, raw_cfg)
+          normalized[host.name] = host if host
+        end
+        warn_duplicate_models(normalized)
+      end
+      normalized["default"] = default_host(data, env) if normalized.empty?
+      normalized
+    rescue StandardError => e
+      Log.error(:config, "hosts_config_failed", error: e.class.name, message: e.message)
+      {}
+    end
+
+    # The names (lowercased) of the hosts entries with enabled: false, which
+    # .all leaves out, from config.yml's hosts:.
+    # @return [Array<String>]
+    def self.disabled_names(env: ENV, path: ConfigFile.global_path(env: env))
+      data = ConfigFile.read_yaml(env: env, path: path)
+      raw = data[ConfigFile::HOSTS_KEY] if data.is_a?(Hash)
+      return [] unless raw.is_a?(Hash)
+
+      raw.filter_map { |name, cfg| name.to_s.strip.downcase if cfg.is_a?(Hash) && disabled?(cfg) }
+    rescue StandardError # degrade-ok: Config↔Log: Log resolves its file and level through Config
+      []
+    end
+
+    # +raw+ parsed against config.yml's hosts (or +hosts+) and aliases.
+    # @return [ModelRef]
+    def self.model_ref(raw, env: ENV, path: ConfigFile.global_path(env: env), hosts: nil)
+      ModelRef.parse(raw, hosts: hosts || all(env: env, path: path), aliases: ConfigFile.model_aliases(env: env, path: path))
+    end
+
+    # The host chi uses when hosts: names none: server.host/port.
+    def self.default_host(data, env)
+      opts = { file_data: data, env: env, cli_overrides: Config.cli_overrides }
+      host = Config.resolve("server.host", **opts).to_s.strip
+      host = "localhost" if host.empty?
+      port = Config.resolve("server.port", **opts).to_i
+      port = 8080 if port <= 0 || port > 65_535
+      new(name: "default", host: host, port: port)
+    end
+    private_class_method :default_host
+
+    # Two hosts declaring one id under hosts.<name>.models: a bare id goes
+    # where HostRegistry#host_for_model sends it (the default host when it
+    # declares the id, else the first in hosts: order); say so once.
+    def self.warn_duplicate_models(hosts)
+      declared = Hash.new { |h, k| h[k] = [] }
+      hosts.each { |name, cfg| cfg.models.each { |down, model| declared[down] << [name, model.id] } }
+      declared.each_value do |owners|
+        next if owners.size < 2
+
+        names = owners.map(&:first)
+        id = owners.first.last
+        goes = names.include?("default") ? "default" : "#{names.first} unless the default host lists it"
+        ConfigFile.warn_once "Warning: #{names.map { |n| "hosts.#{n}.models" }.join(" and ")} #{names.size == 2 ? "both" : "all"} " \
+                             "declare #{id}; a bare #{id} goes to #{goes}"
+      end
+    end
+    private_class_method :warn_duplicate_models
+
     # A hosts: entry as written in config.yml,
     # or nil when it is disabled (enabled: false) or invalid. An invalid
     # one warns once, naming the entry, the way each reader of a setting

data/lib/samagotchi/host_model.rb

@@ -67,12 +67,8 @@ module Samagotchi
       served == "any" || served.any? { |id| id.casecmp?(name.to_s.strip) }
     end
 
-    # config.rb requires this file, so config is required here only when a
-    # warning needs it (this file loaded alone).
-    def self.warn_once(message)
-      require_relative "config"
-      ConfigFile.warn_once(message)
-    end
+    # Config comes with model_price.
+    def self.warn_once(message) = ConfigFile.warn_once(message)
     private_class_method :warn_once
 
     # One host's rows as the listings show them, declared ids first, then

data/lib/samagotchi/host_registry.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "ipaddr"
 require_relative "config"
+require_relative "host_address"
 require_relative "log"
 require_relative "model_ref"
 require_relative "client"
@@ -88,11 +88,11 @@ module Samagotchi
       def dialect_profile = LLM::Dialect.for(dialect)
 
       # A provider on the network rather than a local server: hosts.<name>.remote
-      # when set, else by its address (HostRegistry.remote_address?). An API
+      # when set, else by its address (HostAddress.remote_address?). An API
       # key doesn't decide: a llama.cpp on the LAN can have one. A remote
       # host's model list is cached longer, it gets a first-token limit, and
       # it isn't asked for llama.cpp's /props.
-      def remote? = remote.nil? ? HostRegistry.remote_address?(scheme, host) : remote
+      def remote? = remote.nil? ? HostAddress.remote_address?(scheme, host) : remote
 
       def models_ttl = remote? ? REMOTE_CACHE_TTL_SECONDS : CACHE_TTL_SECONDS
 
@@ -102,7 +102,7 @@ module Samagotchi
       # and read_timeout catches a dead one). 0 turns it off.
       def first_token_limit
         seconds = first_token_timeout
-        seconds = HostRegistry.configured_first_token_timeout if seconds.nil?
+        seconds = HostAddress.configured_first_token_timeout if seconds.nil?
         seconds = remote? ? REMOTE_FIRST_TOKEN_TIMEOUT : nil if seconds.nil?
         seconds&.positive? ? seconds : nil
       end
@@ -115,18 +115,66 @@ module Samagotchi
       def openai_base_url = entry.openai_base_url
     end
 
+    # Raised when a client override is set on the shared registry (.current):
+    # every command and chi web's routes would then send through it.
+    class Shared < StandardError
+      def initialize(msg = "HostRegistry.current is shared: set a client override on a registry of your own") = super
+    end
+
     # A client that every target uses instead of its host's own (specs inject
     # a stub this way; the Engine/TUI `client:` keyword sets it).
-    attr_accessor :client_override
+    attr_reader :client_override
+
+    # @raise [Shared] on the shared registry (.current)
+    def client_override=(client)
+      raise Shared if @shared
+
+      @client_override = client
+    end
+
+    @current_mutex = Mutex.new
+
+    # The registry this process's commands and chi web share: one per
+    # process, built again when config.yml's hosts: no longer equal the ones
+    # it was built from (HostConfig.all, compared as read: the YAML read is
+    # mtime-cached), so a host added while chi web runs is listed on the next
+    # read, and its model lists, index and adapters are kept while hosts:
+    # stay. It doesn't rebuild on server.first_token_timeout or the
+    # server.host/port fallback entry: those are read at construction. It
+    # refuses a client override (Shared). An Engine and the TerminalUI take
+    # it once, at their start: a running worker keeps the hosts it started
+    # with.
+    # For any env but the process ENV (chi self's spec envs): a fresh
+    # registry on that env, never kept.
+    # @return [HostRegistry]
+    def self.current(env: ENV)
+      return new(env: env) unless env.equal?(ENV)
+
+      @current_mutex.synchronize do
+        hosts = HostConfig.all
+        if @current.nil? || hosts != @current_hosts
+          @current = new(hosts_config: hosts, shared: true)
+          @current_hosts = hosts
+        end
+        @current
+      end
+    end
+
+    # Forget the shared registry (specs: one per example).
+    def self.reset_current!
+      @current_mutex.synchronize { @current = @current_hosts = nil }
+    end
 
     # @param clock [#call, nil] monotonic seconds (specs)
-    def initialize(hosts_config: nil, env: ENV, client_override: nil, clock: nil)
+    # @param shared [Boolean] .current's own: refuses a client override
+    def initialize(hosts_config: nil, env: ENV, client_override: nil, clock: nil, shared: false)
       @client_override = client_override
+      @shared = shared
       @env = env
       @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
       @adapters = {}
       @host_lists = {}
-      raw = hosts_config || ConfigFile.hosts_config(env: env)
+      raw = hosts_config || HostConfig.all(env: env)
       @entries = {}
       raw.each do |key, cfg|
         cfg = HostConfig.coerce(key, cfg)
@@ -155,45 +203,9 @@ module Samagotchi
 
     attr_reader :entries
 
-    # Loopback, private (RFC 1918, IPv6 unique local) and link-local nets.
-    LOCAL_NETS = %w[127.0.0.0/8 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 100.64.0.0/10
-                    ::1/128 fc00::/7 fe80::/10].map { |net| IPAddr.new(net) }.freeze
-
-    # Name suffixes that stay on a home or office network: mDNS, the
-    # special-use and customary private names, router defaults (fritz.box)
-    # and Tailscale's MagicDNS. Compared on whole labels.
-    LOCAL_NAME_SUFFIXES = %w[localhost local lan home home.arpa internal intranet localdomain private corp test
-                             box ts.net].freeze
-
-    # Whether an address is remote: https, an http IP address outside the
-    # local nets (LOCAL_NETS), or an http name with a dot whose suffix isn't
-    # a local one (LOCAL_NAME_SUFFIXES): `gpu.example.com` is remote, while
-    # `box`, `mac.local`, `gpu.lan` and `pc.tail1234.ts.net` are local. chi
-    # doesn't look names up; hosts.<name>.remote overrides either way.
-    def self.remote_address?(scheme, host)
-      return true if scheme.to_s == "https"
-
-      address = IPAddr.new(host.to_s.delete_prefix("[").delete_suffix("]"))
-      address = address.native if address.ipv4_mapped?
-      LOCAL_NETS.none? { |net| net.family == address.family && net.include?(address) }
-    rescue IPAddr::Error
-      remote_name?(host)
-    end
-
-    def self.remote_name?(host)
-      name = host.to_s.downcase.delete_suffix(".")
-      return false unless name.include?(".")
-
-      LOCAL_NAME_SUFFIXES.none? { |suffix| name == suffix || name.end_with?(".#{suffix}") }
-    end
-    private_class_method :remote_name?
-
-    # server.first_token_timeout, or nil when unset or unreadable.
-    def self.configured_first_token_timeout
-      Config.get("server.first_token_timeout")
-    rescue StandardError
-      nil
-    end
+    # The env its hosts, aliases and saved lists are read with (ENV, or chi
+    # self's): what an EffectiveModel's ModelLookup reads every layer with.
+    attr_reader :env
 
     def default_entry
       @entries["default"] || @entries.values.first