samagotchi 0.155.0 → 0.156.0

data/lib/samagotchi/model_profile.rb

@@ -176,8 +176,8 @@ module Samagotchi
     # @return [String] +model_name+
     def self.check_host!(model_name, env: ENV, hosts: nil)
       require_relative "config"
-      hosts ||= Samagotchi::ConfigFile.hosts_config(env: env)
-      parsed = Samagotchi::ConfigFile.model_ref(model_name, env: env, hosts: hosts)
+      hosts ||= Samagotchi::HostConfig.all(env: env)
+      parsed = Samagotchi::HostConfig.model_ref(model_name, env: env, hosts: hosts)
       if (other = parsed.host_conflict)
         raise UnknownHost, "alias '#{parsed.alias_name}' names host '#{other}', not '#{parsed.host_name}'; " \
                            "use #{parsed.alias_name} or #{other}:#{parsed.alias_name}"
@@ -234,9 +234,9 @@ module Samagotchi
     def self.model_warning(model_name, env: ENV, hosts: nil, lists: nil, relist: nil, now: Time.now.to_i)
       require_relative "config"
       require_relative "model_list_store"
-      hosts ||= Samagotchi::ConfigFile.hosts_config(env: env)
+      hosts ||= Samagotchi::HostConfig.all(env: env)
       lists ||= Samagotchi::ModelListStore
-      parsed = Samagotchi::ConfigFile.model_ref(model_name, env: env, hosts: hosts)
+      parsed = Samagotchi::HostConfig.model_ref(model_name, env: env, hosts: hosts)
       host = parsed.host_name
       return nil unless host
       # Declared under hosts.<name>.models: served whatever the host lists.
@@ -323,7 +323,7 @@ module Samagotchi
       prefix = prefix.strip.downcase
       return nil if hosts.keys.any? { |k| k.to_s.downcase == prefix }
 
-      Samagotchi::ConfigFile.disabled_host_names(env: env).include?(prefix) ? prefix : nil
+      Samagotchi::HostConfig.disabled_names(env: env).include?(prefix) ? prefix : nil
     end
 
     # "box/x" named host box until '/' stopped naming a host: a saved
@@ -437,7 +437,7 @@ module Samagotchi
     def self.resolve(names:, entry:, client:, bare_model:, override: nil, models: nil)
       require_relative "config"
       override ||= Samagotchi::Config.get_with_origin("model.profile")
-      models ||= Samagotchi::ConfigFile.model_settings
+      models ||= Samagotchi::ModelSettings.all
       names = Array(names).map { |n| n.to_s.strip }.reject(&:empty?).uniq
 
       value, origin = override

data/lib/samagotchi/model_settings.rb

@@ -6,7 +6,7 @@ require_relative "reasoning_history"
 
 module Samagotchi
   # One config.yml models: entry (per-model settings keyed by model id or
-  # alias), parsed and checked; ConfigFile.model_settings holds them by
+  # alias), parsed and checked; ModelSettings.all holds them by
   # downcased key. Each field is nil when unset: profile kept as written
   # (downcased; ModelProfile.resolve validates it), vision true/false,
   # sampling a request-field map, thinking a level, reasoning_history a
@@ -21,6 +21,41 @@ module Samagotchi
       super(**members.to_h { |m| [m, nil] }, **fields)
     end
 
+    # The top-level `models:` map: per-model settings keyed by model id or
+    # alias (downcased), e.g. `models: {my-alias: {profile: qwen36}}`, each a
+    # ModelSettings; an entry that is not a map is skipped.
+    # @return [Hash{String => ModelSettings}]
+    def self.all(env: ENV, path: ConfigFile.global_path(env: env))
+      data = ConfigFile.read_yaml(env: env, path: path)
+      raw = data[ConfigFile::MODELS_KEY] if data.is_a?(Hash)
+      return {} unless raw.is_a?(Hash)
+
+      raw.each_with_object({}) do |(k, v), result|
+        key = k.to_s.strip.downcase
+        settings = parse(key, v)
+        result[key] = settings if settings
+      end
+    rescue StandardError # degrade-ok: Config↔Log: Log resolves its file and level through Config
+      {}
+    end
+
+    # The first +names+ (model as typed, alias-resolved, bare, …) whose
+    # models: entry sets +field+ (a ModelSettings member; another name
+    # raises ArgumentError): a ModelSetting (key, value), or nil.
+    # VisionSupport and SamplingSettings look a model up the same way.
+    # @param models [Hash{String => ModelSettings}, nil] .all by default
+    # @return [ModelSetting, nil]
+    def self.find(names, field, models: nil)
+      raise ArgumentError, "unknown models: field #{field.inspect}" unless members.include?(field)
+
+      models ||= all
+      Array(names).map { |name| name.to_s.strip.downcase }.reject(&:empty?).uniq.each do |key|
+        value = models[key]&.public_send(field)
+        return ModelSetting.new(key: key, value: value) unless value.nil?
+      end
+      nil
+    end
+
     # A models: entry as written, or nil when it is not a map (or the key is
     # blank). A bad value warns, naming the entry, and is left unset.
     # @param key [String] the downcased model id or alias
@@ -45,7 +80,7 @@ module Samagotchi
     end
   end
 
-  # One field ConfigFile.model_setting found: the models: key that set it
+  # One field ModelSettings.find found: the models: key that set it
   # and its value.
   ModelSetting = Data.define(:key, :value)
 end

data/lib/samagotchi/note_command.rb

@@ -109,8 +109,7 @@ module Samagotchi
     def resolve(given)
       @access.resolve(given)
     rescue ArgumentError => e
-      message = e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"
-      error_line("chi note: #{message}")
+      error_line("chi note: #{e.message}")
       nil
     end
 

data/lib/samagotchi/objectives_audit.rb

@@ -40,9 +40,10 @@ module Samagotchi
     # Whether this use is on: config.yml, read at each ask.
     def self.on? = Config.get("objectives.system_one").to_s.strip.downcase == MODE
 
-    # @param client_for [#call] (judgment, session) → a recording client, nil with no host or no saving
+    # @param client_for [#call] (judgment, session) → a recording client, nil with no host or no saving;
+    #   asked only once an active objective is there
     # @param side [SideJudgments]
-    # @param state_dir [#call] → the sessions folder
+    # @param state_dir [String] the sessions folder
     def initialize(client_for:, side:, state_dir:)
       @client_for = client_for
       @side = side
@@ -82,7 +83,7 @@ module Samagotchi
     def ask(judgment, session, message)
       return if session.nil? || session.id.nil? || session.scratch || session.review?
 
-      items = Objectives.current(session.id, session.messages, state_dir: @state_dir.call).items
+      items = Objectives.current(session.id, session.messages, state_dir: @state_dir).items
                         .select { |item| item.status == Objectives::ACTIVE }.first(MAX_OBJECTIVES)
       return if items.empty?
 

data/lib/samagotchi/participants.rb

@@ -106,10 +106,10 @@ module Samagotchi
     # @return [Grants::Issued]
     # @raise [Grants::Invalid] an archived session, or bad values
     #   (Unbindable: an identity without such a public_url)
-    # @raise [ArgumentError] no such session
+    # @raise [Session::NotFound] no such session
     def invite(grants, session_id:, name:, kind: "human", ttl: nil, cap: nil, identity: nil, public_url: nil,
                mode: nil, state_dir: Session.default_state_dir)
-      raise ArgumentError, "Session not found: #{session_id}" unless File.exist?(Session.session_file(session_id, state_dir: state_dir))
+      raise Session::NotFound, session_id unless File.exist?(Session.session_file(session_id, state_dir: state_dir))
 
       identity = Grants.clean_identity(identity) unless identity.nil?
       raise Grants::Unbindable if !identity.nil? && public_url&.identity_header.nil?

data/lib/samagotchi/plugin/context.rb

@@ -182,7 +182,7 @@ module Samagotchi
       def model_key = @host.model_key&.call
 
       # The names the session's model is looked up under now, as chi's own
-      # per-model config is (models: maps, ConfigFile.model_setting): as
+      # per-model config is (models: maps, ModelSettings.find): as
       # typed (an alias), the alias's target, the resolved ref ("host:id"),
       # without the host, the bare id the host serves; deduped, first the
       # most specific. Compare them downcased, first hit, as chi does.

data/lib/samagotchi/plugin/sessions.rb

@@ -212,11 +212,8 @@ module Samagotchi
       end
 
       def resolve(id, state_dir)
-        sid = Session.resolve_id(id.to_s.strip, state_dir: state_dir)
-        raise Error, "no session #{id}" unless sid && Session.exist?(sid, state_dir: state_dir)
-
-        sid
-      rescue Session::AmbiguousId, ArgumentError => e
+        Session.resolve!(id.to_s.strip, state_dir: state_dir)
+      rescue ArgumentError => e
         raise Error, e.message
       end
 

data/lib/samagotchi/plugin/tool_spec.rb

@@ -136,19 +136,21 @@ module Samagotchi
       def [](key) = (public_send(key) if members.include?(key))
 
       # Registry#register's keywords for it: its block wrapped as a handler
-      # (typed args, the Context), preview, targets, refs.
+      # (typed args, the Context), preview, targets (in the entry's form,
+      # (call, surface): a plugin's reads the call only), refs (call only).
       def entry_fields(context)
         block = self.block
         parameters = schema[:parameters]
         preview = per_call(self.preview, parameters)
+        targets = per_call(self.targets, parameters)
         {
           schema: schema, label: label,
           handler: lambda { |call, _kctx|
             result = block.call(ToolSpec.args_of(call, parameters), context)
             ToolSpec.result_text(result)
           },
-          preview: preview && ->(call) { preview.call(call)&.to_s },
-          targets: per_call(targets, parameters),
+          preview: preview && ->(call, _surface = nil) { preview.call(call)&.to_s },
+          targets: targets && ->(call, _surface = nil) { targets.call(call) },
           refs: per_call(refs, parameters)
         }
       end

data/lib/samagotchi/project_env.rb

@@ -107,7 +107,7 @@ module Samagotchi
     # @return [Overlay]
     def current = @current
 
-    # Only from SessionManager.run_session_loop, in a spawned worker.
+    # Only from WorkerBoot.run_session_loop, in a spawned worker.
     def install!(overlay) = @current = overlay
 
     # #current's env for a tool's spawn, less what every tool runs without

data/lib/samagotchi/reasoning_history.rb

@@ -68,7 +68,7 @@ module Samagotchi
     # the default).
     # @param target [HostRegistry::ModelTarget]
     # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
-    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all (specs)
     # @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)
@@ -78,11 +78,11 @@ module Samagotchi
       return [env, ENV_NAME] if env
 
       models ||= begin
-        ConfigFile.model_settings
+        ModelSettings.all
       rescue StandardError
         {}
       end
-      setting = ConfigFile.model_setting(names, :reasoning_history, models: models)
+      setting = ModelSettings.find(names, :reasoning_history, models: models)
       return [setting.value, "models: #{setting.key}"] if setting
 
       host = target.entry&.reasoning_history

data/lib/samagotchi/reminder_carry.rb

@@ -15,7 +15,7 @@ module Samagotchi
   # restart writes one: a stop, an idle exit, a crash and a fallback restart
   # (a TERM) drop the reminders as before, and a stop or an archive removes a
   # file left behind (SessionManager.stop_session, .archive_session); a
-  # restart a stop landed on starts no successor (.run_session_loop). A file is honoured only by the same
+  # restart a stop landed on starts no successor (WorkerBoot.run_session_loop). A file is honoured only by the same
   # session, within WINDOW of its writing (a successor starts in seconds), so
   # one no successor read can't bring reminders back a day later.
   module ReminderCarry

data/lib/samagotchi/reprefill_meter.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "token_usage"
+
+module Samagotchi
+  # A request's re-prefilled tokens, for both loops: of the prompt the last
+  # request on the same model through the same client (the host) sent, what
+  # the server didn't reuse from its cache this time (that prompt less the
+  # cached count), so an LLM context edit's cache break shows, and so does
+  # anything else that rewrote the prompt's middle or lost the cache.
+  #
+  # One per Engine, given to its KernelLoop and its ChatLoop, so the
+  # baseline is the last request's whichever loop sent it: a switch to
+  # another host and back starts over on the way back. A bare loop (a spec,
+  # a bench) builds its own. Read and written on the turn's thread only
+  # (each loop's completed generation; the turn-end warm-up's #reset!).
+  class ReprefillMeter
+    # The last counted request: its model, its client, its prompt tokens.
+    Baseline = Data.define(:model, :client, :prompt)
+
+    # The tokens the server prefilled again for this request (+prompt+ and
+    # +cached+, its counts), and this request becomes the baseline. nil
+    # under TokenUsage::REPREFILL_MIN_TOKENS (a cache block's rounding), for
+    # a server that reports no cached count (or 0: a cold cache isn't told
+    # from no cache), the first request, a model switch (another bare model,
+    # or the same one on another host's +client+: SessionMetrics counts that
+    # prefill as the switch's), and the first request after #reset!.
+    # @return [Integer, nil]
+    def tokens(model, client:, prompt:, cached:)
+      previous = @baseline
+      @baseline = Baseline.new(model: model, client: client, prompt: prompt.to_i) if prompt.to_i.positive?
+      return nil unless previous && previous.model == model && previous.client.equal?(client) && cached.to_i.positive?
+
+      tokens = previous.prompt - cached.to_i
+      tokens >= TokenUsage::REPREFILL_MIN_TOKENS ? tokens : nil
+    end
+
+    # A turn-end warm-up prefilled the next prompt off the clock, so the
+    # next request's cache counts are against it, not the last request:
+    # start over (KernelLoop#warmed_up!).
+    def reset!
+      @baseline = nil
+    end
+  end
+end

data/lib/samagotchi/review_command.rb

@@ -64,7 +64,7 @@ module Samagotchi
     rescue ModelProfile::MissingModel, Toolkit::Refused => e
       refused("could not start: #{e.message}")
     rescue ArgumentError => e
-      refused(e.is_a?(Session::AmbiguousId) ? e.message : e.message.sub(/\ASession not found: /, "no session "))
+      refused(e.message)
     end
 
     private

data/lib/samagotchi/sampling_settings.rb

@@ -13,7 +13,7 @@ module Samagotchi
 
     # @param target [HostRegistry::ModelTarget]
     # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
-    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ModelSettings.all (specs)
     # @return [Hash] frozen, symbol keys; may be empty
     def self.for(target, names:, models: nil)
       resolve(target, names, models).first
@@ -39,12 +39,12 @@ module Samagotchi
 
     def self.resolve(target, names, models)
       models ||= begin
-        ConfigFile.model_settings
+        ModelSettings.all
       rescue StandardError
         {}
       end
       host = target.entry.sampling || EMPTY
-      model = ConfigFile.model_setting(names, :sampling, models: models)
+      model = ModelSettings.find(names, :sampling, models: models)
       sources = []
       sources << "hosts.#{target.entry.name}" unless host.empty?
       sources << "models: #{model.key}" if model

data/lib/samagotchi/self_report.rb

@@ -184,12 +184,12 @@ module Samagotchi
         registry = HostRegistry.new(env: env)
         target = registry.resolve(model)
         names = registry.lookup_names(model, target: target)
-        models = ConfigFile.model_settings(env: env)
+        models = ModelSettings.all(env: env)
         window = ContextWindow.setting(target, names: names, models: models)
         return nil unless window
         return [window.tokens, "hosts.#{target.entry.name}"] if window.source == :host_setting
 
-        [window.tokens, "models: #{ConfigFile.model_setting(names, :window_tokens, models: models).key}"]
+        [window.tokens, "models: #{ModelSettings.find(names, :window_tokens, models: models).key}"]
       end
     end
 
@@ -224,7 +224,7 @@ module Samagotchi
       Degrade.call(:config, "model_ref_unresolved", fallback: false) do
         return true if one == other
 
-        ConfigFile.model_ref(one, env: env).ref == ConfigFile.model_ref(other, env: env).ref
+        HostConfig.model_ref(one, env: env).ref == HostConfig.model_ref(other, env: env).ref
       end
     end
 
@@ -305,7 +305,7 @@ module Samagotchi
     # it resolves to (an alias applied, ModelRef), as `chi models` names it.
     def model_ref_name(env: ENV)
       name = model_name
-      name && ConfigFile.model_ref(name, env: env).ref
+      name && HostConfig.model_ref(name, env: env).ref
     end
 
     # Routed without model discovery, so an unqualified name may land on
@@ -383,7 +383,7 @@ module Samagotchi
       names = registry.lookup_names(model)
       override = Config.resolve_with_origin("model.profile", env: env, cli_overrides: Config.cli_overrides)
       result = ModelProfile.resolve(names: names, entry: entry, client: nil, bare_model: bare, override: override,
-                                    models: ConfigFile.model_settings(env: env))
+                                    models: ModelSettings.all(env: env))
       name = result.profile.name
       case result.source
       when :config then "#{name} (config #{result.detail})"
@@ -401,7 +401,7 @@ module Samagotchi
       target = registry.resolve(model)
       session = session_model(env) ? Thinking.session_level(env[SESSION_THINKING_ENV]) : nil
       Thinking.explain(target, names: registry.lookup_names(model, target: target),
-                               models: ConfigFile.model_settings(env: env), session: session).label
+                               models: ModelSettings.all(env: env), session: session).label
     rescue StandardError => e
       "(unknown: #{e.message})"
     end
@@ -417,7 +417,7 @@ module Samagotchi
 
       session = session_model(env) ? ReasoningHistory.session_level(env[SESSION_REASONING_HISTORY_ENV]) : nil
       level, source = ReasoningHistory.resolve(target, names: registry.lookup_names(model, target: target),
-                                                       models: ConfigFile.model_settings(env: env), session: session)
+                                                       models: ModelSettings.all(env: env), session: session)
       ReasoningHistory.label(level, source)
     rescue StandardError => e
       "(unknown: #{e.message})"

data/lib/samagotchi/session.rb

@@ -119,7 +119,7 @@ module Samagotchi
     # Started by the `delegate` tool (a fork has a parent_id too, but isn't
     # one): see #delegate?.
     attr_writer :delegate
-    # The session this one continues (SessionManager.continue_session): the
+    # The session this one continues (SessionContinue.run): the
     # previous link of a chain, "the next run of the same routine", else
     # nil. Not a parent: archiving one link leaves the next alone. The chain
     # itself is derived (SessionChain), never stored.
@@ -353,7 +353,7 @@ module Samagotchi
     attr_accessor :model_warning
 
     # The delegates a continue moved to this new link (ChildMove;
-    # SessionManager.continue_session sets it); not saved.
+    # SessionContinue.run sets it); not saved.
     attr_accessor :moved_children
 
     # The attached context a continue took to this new link
@@ -361,7 +361,7 @@ module Samagotchi
     attr_accessor :moved_context
 
     # The text web `continue →` prefills in this new link
-    # (SessionChain.opener_for; SessionManager.continue_session sets it); not
+    # (SessionChain.opener_for; SessionContinue.run sets it); not
     # saved.
     attr_accessor :opener
 
@@ -452,6 +452,20 @@ module Samagotchi
       @preloaded_memory_names.include?(DELEGATE_MEMORY)
     end
 
+    # The turn state (idle/running/…) the lists show: the saved status,
+    # except a "running" with no live +owner+ (an OwnerLock::Owner, or nil):
+    # the worker that saved it died mid-turn, so nothing runs. The one rule
+    # behind chi web's rows and pages (Web::SessionSummary.displayed_status,
+    # which prefers a live worker's snapshot) and `chi sessions list`
+    # (SessionManager.session_summaries and the plain table).
+    # @param owner [OwnerLock::Owner, nil] the session's owner now
+    # @return [String]
+    def displayed_status(owner:)
+      return status unless status == STATUS_RUNNING
+
+      owner ? status : STATUS_IDLE
+    end
+
     # The question this session waits on, as the lists show it: {id:, kind:}
     # with kind "question" (the model's), "approval", "hook" or "continue"
     # (the step-limit question, asked between turns), +relayed_to+ and
@@ -559,9 +573,12 @@ module Samagotchi
       valid_id?(session_id) && File.exist?(session_path(session_id, state_dir: state_dir))
     end
 
+    # @raise [NotFound] no such session (an id that isn't one too)
     def self.load(session_id, state_dir: default_state_dir)
+      raise NotFound, session_id unless valid_id?(session_id)
+
       path = session_path(session_id, state_dir: state_dir)
-      raise ArgumentError, "Session not found: #{session_id}" unless File.exist?(path)
+      raise NotFound, session_id unless File.exist?(path)
 
       session = from_h(JSON.parse(File.read(path)))
       session.status = STATUS_STOPPED if stopped_marker?(session.id, state_dir: state_dir)
@@ -667,8 +684,34 @@ module Samagotchi
       end
     end
 
+    # What every surface says when an id (or a prefix) names no session:
+    # this class owns the words, callers add their context around
+    # #message. +given+ is what was asked for, as given.
+    class NotFound < ArgumentError
+      attr_reader :given
+
+      def initialize(given)
+        @given = given.to_s
+        super("no session #{@given[0, 80]}")
+      end
+    end
+
+    # The full id of an existing session that +given+ (an id or a unique
+    # prefix) names: the one lookup the commands, SessionAccess::Local, chi
+    # web's routes and the tools share.
+    # @raise [NotFound] none (an id that isn't one too)
+    # @raise [AmbiguousId] a prefix of several
+    def self.resolve!(given, state_dir: default_state_dir)
+      raise NotFound, given unless valid_id?(given.to_s)
+
+      id = resolve_id(given, state_dir: state_dir)
+      raise NotFound, given unless exist?(id, state_dir: state_dir)
+
+      id
+    end
+
     # A session id or a unique prefix of one (like git's): the full id. An
-    # unknown one comes back as is, for the caller's own "not found"; one that
+    # unknown one comes back as is (resolve! raises NotFound for it); one that
     # names several sessions raises AmbiguousId, which lists them.
     def self.resolve_id(id_or_prefix, state_dir: default_state_dir)
       id = id_or_prefix.to_s
@@ -832,9 +875,9 @@ module Samagotchi
 
     # Mark a session as stopped (STOPPED_FILE); its session file stays as
     # it is.
-    # @raise [ArgumentError] when there is no such session
+    # @raise [NotFound] when there is no such session
     def self.mark_stopped(session_id, state_dir: default_state_dir)
-      raise ArgumentError, "Session not found: #{session_id}" unless exist?(session_id, state_dir: state_dir)
+      raise NotFound, session_id unless exist?(session_id, state_dir: state_dir)
 
       dir = session_dir(session_id, state_dir: state_dir)
       FileUtils.mkdir_p(dir)

data/lib/samagotchi/session_access/local.rb

@@ -33,6 +33,8 @@ module Samagotchi
   # Loaded on first use: SessionManager and its ~80 files only when a
   # command reaches it (chi context never does).
   autoload :SessionManager, File.expand_path("../session_manager", __dir__)
+  # A continue (#create with continues); it requires session_manager.
+  autoload :SessionContinue, File.expand_path("../session_continue", __dir__)
 
   module SessionAccess
     # This machine's sessions: the calls the session commands made before
@@ -63,11 +65,11 @@ module Samagotchi
       # @raise [Session::AmbiguousId]
       def resolve_id(given) = Session.resolve_id(given, **dir)
 
-      # The full id of +given+, of a session that exists.
-      # @raise [ArgumentError] no such session (Session::AmbiguousId: a
+      # The full id of +given+, of a session that exists (and loads).
+      # @raise [Session::NotFound] no such session (Session::AmbiguousId: a
       #   prefix of several)
       def resolve(given)
-        id = resolve_id(given)
+        id = Session.resolve!(given, **dir)
         show(id)
         id
       end
@@ -140,7 +142,7 @@ module Samagotchi
 
         start = spec.preview ? { prompt: spec.prompt, preview: spec.preview } : { prompt: spec.prompt }
         if spec.continues
-          return SessionManager.continue_session(spec.continues, **start, model: spec.model_name, **dir)
+          return SessionContinue.run(spec.continues, **start, model: spec.model_name, **dir)
         end
 
         SessionManager.spawn_session(**start, working_directory: spec.working_directory, model_name: spec.model_name,
@@ -269,7 +271,7 @@ module Samagotchi
       # @return [Boolean] whether the worker released the session
       def stop(id, wait:) = SessionManager.stop_session(id, wait: wait, **dir)
 
-      # @return [SessionManager::RestartResult]
+      # @return [SessionManager::Restarted]
       def restart(id) = SessionManager.restart_session(id, **dir)
 
       # @return [SessionManager::ArchiveResult]

data/lib/samagotchi/session_access/remote.rb

@@ -137,11 +137,11 @@ module Samagotchi
         end
       end
 
-      # @raise [ArgumentError] no such session (Session::AmbiguousId: a
+      # @raise [Session::NotFound] no such session (Session::AmbiguousId: a
       #   prefix of several)
       def resolve(given)
         id = resolve_id(given)
-        raise ArgumentError, "Session not found: #{given}" if id == given.to_s && !exists?(id)
+        raise Session::NotFound, given if id == given.to_s && !exists?(id)
 
         id
       end
@@ -704,6 +704,20 @@ module Samagotchi
         reply.json["detail"].to_s.start_with?("no installed bundle resolves")
       end
 
+      # chi web's 404 not_found detail for a session it doesn't have:
+      # "no session X" (Session::NotFound), or "Session not found: X" from
+      # chi web 0.155.0 and older (compat N-1: the same line either way).
+      SESSION_NOT_FOUND = /\A(?:no session |Session not found: )(.+)\z/m
+
+      # Session::NotFound for a missing session's 404, else an
+      # ArgumentError with chi web's words (another route's 404). chi web
+      # never answers Session::NONE_YET ("no session yet") as a 404
+      # not_found; were it to, the pattern would read it as NotFound("yet").
+      def not_found_error(detail)
+        given = detail[SESSION_NOT_FOUND, 1]
+        given ? Session::NotFound.new(given) : ArgumentError.new(detail)
+      end
+
       # Raises what Local's callee raises for this refusal (chi web sends
       # the fields each class is built from; see docs/architecture.md, chi
       # web's routes for the session commands), else RemoteFailed.
@@ -714,7 +728,7 @@ module Samagotchi
         sid = json["session_id"]
         reason = json["reason"]&.to_sym
         case error
-        when "not_found" then raise ArgumentError, message.to_s
+        when "not_found" then raise not_found_error(message.to_s)
         when "ambiguous_id" then raise Session::AmbiguousId.new(message, ids: Array(json["ids"]))
         when "owned_by_tui"
           raise SessionManager::ScratchSession, sid if json["scratch"] == true

data/lib/samagotchi/session_archive_command.rb

@@ -82,7 +82,7 @@ module Samagotchi
       @stdout.puts("#{short}  refused: #{e.message}")
       false
     rescue ArgumentError => e
-      error_line("chi sessions archive: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      error_line("chi sessions archive: #{e.message}")
       false
     rescue SystemCallError => e
       @stdout.puts("#{short}  failed: #{e.message}")
@@ -96,7 +96,7 @@ module Samagotchi
       @stdout.puts(result[:unarchived].empty? ? "#{short}  not archived" : "#{short}  unarchived")
       true
     rescue ArgumentError => e
-      error_line("chi sessions unarchive: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      error_line("chi sessions unarchive: #{e.message}")
       false
     rescue SystemCallError => e
       @stdout.puts("#{short}  failed: #{e.message}")

data/lib/samagotchi/session_chain.rb

@@ -15,7 +15,7 @@ module Samagotchi
   # "the next run of the same routine". The chain is derived, never stored:
   # follow +continues+ back for the earlier links, forward (the session whose
   # +continues+ names this one) for the later ones. A link is continued at
-  # most once (SessionManager.continue_session refuses a second), so the
+  # most once (SessionContinue.run refuses a second), so the
   # chain's latest link is the one nobody continues.
   module SessionChain
     # `--continues last:<id>`: the latest link of the chain <id> is in.
@@ -62,15 +62,16 @@ module Samagotchi
     # A session to continue as the CLI and the web name it: an id, a unique
     # prefix, or `last:<id or prefix>` for that chain's latest link.
     # @return [String] the full id of an existing session
-    # @raise [ArgumentError] none such (Session::AmbiguousId for a prefix of several)
+    # @raise [Session::NotFound] none such (Session::AmbiguousId for a prefix of several)
     def resolve(ref, state_dir:)
       given = ref.to_s.strip
       last = given.start_with?(LAST_PREFIX)
       given = given.delete_prefix(LAST_PREFIX) if last
-      raise ArgumentError, "no session #{ref}" unless Session.valid_id?(given)
-
-      id = Session.resolve_id(given, state_dir: state_dir)
-      raise ArgumentError, "no session #{ref}" unless Session.exist?(id, state_dir: state_dir)
+      id = begin
+        Session.resolve!(given, state_dir: state_dir)
+      rescue Session::NotFound
+        raise Session::NotFound, ref # as given, last: and all
+      end
 
       last ? latest(id, state_dir: state_dir) : id
     end