samagotchi 0.121.1 → 0.122.0

data/lib/samagotchi/engine.rb

@@ -41,6 +41,8 @@ require_relative "llm/openai_chat"
 require_relative "llm/turn_settings"
 require_relative "session"
 require_relative "toolkit_binding"
+require_relative "participant_mode"
+require_relative "toolkit_suggest"
 require_relative "tool_loads"
 require_relative "answer_tail"
 require_relative "archive_store"
@@ -156,6 +158,7 @@ module Samagotchi
       @no_interrupt = no_interrupt
       @chat_backend = nil
       @chat_backend_mutex = Mutex.new
+      @toolkit_audit_thread = nil
       @host_registry = host_registry || HostRegistry.new
       # A model given here (a worker's session model) is the one it runs,
       # so its host is checked; the config default is only checked once it
@@ -1082,6 +1085,10 @@ module Samagotchi
 
     # How long #shutdown waits for the running anytime commands, in all.
     SHUTDOWN_JOIN_SECONDS = 3.0
+    # How long #shutdown waits for a running toolkit audit ask (a one-shot
+    # -p --non-interactive exits right after its turn); a slower ask goes
+    # unlogged.
+    TOOLKIT_AUDIT_JOIN_SECONDS = 1.0
 
     # The REPL or the session's worker is leaving (/exit, an idle exit, a
     # crash, TERM): stop the idle jobs, give the running anytime commands
@@ -1107,6 +1114,7 @@ module Samagotchi
 
         thread.join([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max)
       end
+      @toolkit_audit_thread&.join(TOOLKIT_AUDIT_JOIN_SECONDS)
       left = threads.count(&:alive?)
       Log.warn(:plugins, "anytime_commands_left", count: left) if left.positive?
       @plugin_tasks.kill_leftovers
@@ -1516,6 +1524,13 @@ module Samagotchi
       Steer.author_fields(author, @participants.name_for(author, session: session))
     end
 
+    # A participant's opening message keeps the rules it was delivered under
+    # (ParticipantMode), stamped before any request carries it, so its header
+    # never changes when the session's mode does.
+    def participant_mode_fields(author, session: @session)
+      Steer.participant_author?(author) ? { participant_mode: ParticipantMode.of(session).to_s } : {}
+    end
+
     # Why a turn stopped (TurnEndings#stop_facts).
     def stop_facts(event) = @turn_endings.stop_facts(event)
     private :stop_facts
@@ -2128,6 +2143,8 @@ module Samagotchi
       emit_event(turn.on_event, turn.tag(turn_started))
       raise image_error if image_error
 
+      start_toolkit_suggestion_audit(turn)
+
       # 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.
       # The cache itself was dropped at the previous turn's end, so this
@@ -2289,7 +2306,7 @@ module Samagotchi
 
       unless turn.continue
         user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author),
-                         MessageTime::KEY => turn.at }
+                         **participant_mode_fields(turn.origin.author, session: session), MessageTime::KEY => turn.at }
         user_message[:images] = image_refs unless image_refs.empty?
         turn.messages << user_message
         session.last_prompt = turn.prompt
@@ -2712,6 +2729,95 @@ module Samagotchi
     def apply_toolkit!(session, on_event = nil) = @toolkit_binding.apply!(session, on_event)
     private :apply_toolkit!
 
+    # Start an audit-only classifier after :turn_started. All session and
+    # tool-registry reads happen here; the thread receives only this snapshot.
+    def start_toolkit_suggestion_audit(turn)
+      mode = Config.get("toolkit.suggest.mode").to_s
+      return if mode == "off"
+
+      session = turn.session
+      default = Toolkit.of(session.toolkit)
+      path = ToolkitSuggest.log_path(session_state_dir)
+      log = SystemOne::Log.new(dir: File.dirname(path), file: File.basename(path),
+                               warn: lambda { |reason|
+                                 Log.warn(:toolkit, "toolkit_suggest_log_failed",
+                                          echo: "[samagotchi:toolkit] #{reason}")
+                               })
+      # The predicate checks the session first; the kits (memory kits are
+      # read from disk) and the log (read whole) only when it gets there.
+      kits = nil
+      candidates = nil
+      return unless ToolkitSuggest.eligible?(
+        session: session, prompt: turn.prompt, author: turn.origin.author,
+        candidate_count: lambda {
+          kits = @toolkit_binding.kits
+          candidates = ToolkitSuggest.candidates(kits, default_name: default.name)
+          candidates.size
+        },
+        last_suggestion: -> { ToolkitSuggest.last_suggestion(log, session.id) },
+        defer_turns: Config.get("toolkit.suggest.defer_turns"),
+        defer_tokens: Config.get("toolkit.suggest.defer_tokens")
+      )
+
+      # One ask at a time: an eligible turn while the last one still runs
+      # goes unasked, and says so.
+      if @toolkit_audit_thread&.alive?
+        Log.info(:toolkit, "toolkit_suggest_in_flight_skipped", session_id: session.id)
+        return
+      end
+
+      client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
+      return unless client
+
+      if toolkit_judge_shares_local_host?(client.host)
+        Log.info(:toolkit, "toolkit_suggest_shared_host_skipped", session_id: session.id, host: client.host)
+        return
+      end
+
+      # Rules, not tool lists: this runs before await_init_tasks and
+      # apply_staged_tools!, so a first turn's plugin/MCP tools aren't
+      # registered yet; the report expands the rules (ToolkitSuggest.rules).
+      snapshots = candidates.map do |kit|
+        ToolkitSuggest::Candidate.new(name: kit.name.dup.freeze, description: kit.description.dup.freeze,
+                                      rules: ToolkitSuggest.rules(Toolkit.resolve_kit(kit.name, kits)))
+      end.freeze
+      default_snapshot = ToolkitSuggest::Candidate.new(name: default.name.dup.freeze, description: nil,
+                                                       rules: ToolkitSuggest.rules(default.resolve(kits)))
+      core_tools = @tools.entries(toolkit: nil).select(&:core?).map { |entry| entry.name.dup.freeze }.freeze
+      state = ToolkitSuggest.question(
+        default: default, kits: kits, project: File.basename(session.project_root.to_s),
+        prompt: turn.prompt
+      ).last
+      snapshot = ToolkitSuggest::Snapshot.new(
+        session_id: session.id.dup.freeze, turn_number: ToolkitSuggest.turn_number(session.messages),
+        default: default_snapshot, candidates: snapshots, core_tools: core_tools,
+        state: { project: state[:project].dup.freeze, prompt: state[:prompt].dup.freeze }.freeze
+      )
+      threshold = Config.get("toolkit.suggest.threshold")
+      @toolkit_audit_thread = Thread.new do
+        ToolkitSuggest.ask(client: client, log: log, snapshot: snapshot, threshold: threshold)
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+      end
+    rescue StandardError => e
+      ToolkitSuggest.warn(e)
+      nil
+    end
+    private :start_toolkit_suggestion_audit
+
+    # D7: System 1's host is the session's model server, and a local one
+    # (a single-slot Splash or llama.cpp): the same name, or two hosts:
+    # entries for one server root (scheme, host, port).
+    def toolkit_judge_shares_local_host?(judge_name)
+      model_host, = @host_registry.host_for_model(effective_model_name)
+      return false if model_host.nil? || model_host.remote?
+      return true if judge_name.to_s.strip.casecmp?(model_host.name.to_s)
+
+      judge = @host_registry.find_entry(judge_name)
+      !judge.nil? && judge.root_url.downcase == model_host.root_url.downcase
+    end
+    private :toolkit_judge_shares_local_host?
+
     # The session's toolkit (see #initialize for when).
     def build_toolkit_binding
       ToolkitBinding.new(

data/lib/samagotchi/event_fanout.rb

@@ -56,7 +56,6 @@ module Samagotchi
       @announce_or_hold = announce_or_hold
       @working_set_emitted = nil
     end
-    # rubocop:enable Metrics/ParameterLists
 
     # Always return a handler so raw kernel loop events reach the persistent
     # SessionObserver (and thus the analytics collector) even when there is no

data/lib/samagotchi/guardrail_wiring.rb

@@ -15,6 +15,7 @@ require_relative "edit_preview"
 require_relative "system_one"
 require_relative "tool_activity"
 require_relative "turn_origin"
+require_relative "participant_mode"
 
 module Samagotchi
   # An Engine's tool guardrails: who can approve (the interface), the YAML
@@ -126,12 +127,12 @@ module Samagotchi
     # The gate's core checks, in order. A delegate child's boundary comes
     # before the rules, so its ask keeps the child-boundary rule id (and
     # its once/session scopes) when a strict rule asks too. The review
-    # boundary comes before both: a participant's turn is denied what it
-    # may not do, never asked about it (deny is sticky, so no later vote
-    # can turn it into a question).
+    # boundary comes before both: a participant's review turn is denied
+    # what it may not do, never asked about it.
     def checks
       rules = self.rules
-      [@failures, review_boundary, rules.hook_asks, protected_paths,
+      boundary = ParticipantMode.of(@session_lookup.call) == :review ? review_boundary : nil
+      [@failures, boundary, rules.hook_asks, protected_paths,
        (@scratch_writes ||= Guardrails::ScratchWrites.new if @scratch), child_boundary, rules].compact
     end
 

data/lib/samagotchi/log_line.rb

@@ -16,7 +16,7 @@ module Samagotchi
   # (debug dumps) are indented by four spaces and belong to the record above.
   module LogLine
     LEVELS = %w[DEBUG INFO WARN ERROR].freeze
-    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model context broadcast].freeze
+    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model context broadcast toolkit].freeze
     INDENT = "    "
 
     Record = Struct.new(:ts, :level, :tag, :pid, :sid, :event, :fields, :payload, keyword_init: true)

data/lib/samagotchi/memory_orphans.rb

@@ -51,6 +51,17 @@ module Samagotchi
       found && text(found)
     end
 
+    # A model-facing hint: report the name collision without giving the model
+    # a command that could move another live clone's memories.
+    def model_message(env: ENV, cwd: Dir.pwd)
+      found = find(env: env, cwd: cwd)
+      return unless found
+
+      name = File.basename(found.computed).sub(/_\h{8}\z/, "")
+      "a folder with the same project name (#{name}) exists with another path's hash; ask the user whether its " \
+        "memories belong to this project before using them."
+    end
+
     def text(found)
       computed = found.computed
       lead = "no project memories in #{computed}"

data/lib/samagotchi/participant_mode.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The rules for a participant's turn. P0 keeps every participant in review
+  # mode; this is the single resolver for the later mode split.
+  module ParticipantMode
+    module_function
+
+    def of(_session) = :review
+  end
+end

data/lib/samagotchi/plugin/api.rb

@@ -312,17 +312,20 @@ module Samagotchi
       # a bundle has) with +add+ declared and +remove+ left out, and
       # +prompt+: text the sessions on it get in their system prompt (nil:
       #   its base's, "" none; at most Toolkit::PROMPT_MAX characters);
-      #   +groups+: MCP source group names/globs (nil inherits its base).
+      #   +groups+: MCP source group names/globs (nil inherits its base);
+      #   +description+: optional classifier text, not included in prompts
+      #   (at most Toolkit::DESCRIPTION_MAX characters).
       #   A
       # name chi (full, lean, child) or another bundle has is a load error,
       # and so is a prompt that isn't text or is too long; a base that
       # doesn't resolve leaves the sessions on it with every tool
       # (Toolkit#resolve).
-      def toolkit(name, base:, add: [], remove: [], prompt: nil, groups: nil)
+      def toolkit(name, base:, add: [], remove: [], prompt: nil, groups: nil, description: nil)
         name = name.to_s
         raise ArgumentError, "toolkit name #{name.inspect} must be a-z, 0-9, _ and -" unless name.match?(TOOLKIT_NAME)
 
-        problem = Toolkit.prompt_error(prompt) || (Toolkit.groups_error(groups) unless groups == :all)
+        problem = Toolkit.prompt_error(prompt) || Toolkit.description_error(description) ||
+                  (Toolkit.groups_error(groups) unless groups == :all)
         raise ArgumentError, "toolkit #{name}: #{problem}" if problem
         raise ArgumentError, "this chi has no toolkits (plugins: false)" unless @registries.toolkits
         if Toolkit::BUILTIN_KITS.key?(name)
@@ -333,7 +336,7 @@ module Samagotchi
         raise ArgumentError, "toolkit #{name} is declared twice" if @toolkits.any? { |kit| kit.name == name }
 
         @toolkits << Toolkit::Kit.new(name: name, base: base, add: add, remove: remove, prompt: prompt,
-                                      groups: groups, source: @bundle)
+                                      groups: groups, source: @bundle, description: description)
         nil
       end
 

data/lib/samagotchi/process_group.rb

@@ -87,6 +87,19 @@ module Samagotchi
       nil
     end
 
+    # Whether +pid+ is stopped (SIGSTOP, Ctrl-Z; t: under a tracer): ps's
+    # state starts with T or t on macOS and Linux alike. Such a process
+    # takes no signal but KILL and answers no socket until it is continued.
+    # false when it isn't running or ps can't say.
+    def stopped?(pid)
+      return false unless signalable?(pid)
+
+      out, status = Open3.capture2("ps", "-o", "state=", "-p", pid.to_s, err: File::NULL)
+      status.success? && out.lstrip.start_with?("T", "t")
+    rescue SystemCallError, IOError
+      false
+    end
+
     # Field 22 (starttime); the command name (field 2) may hold spaces and
     # parentheses, so the fields are counted after its last ")".
     def proc_start_time(stat) = stat[/\A.*\)\s(.*)\z/m, 1]&.split&.[](19)

data/lib/samagotchi/review_start.rb

@@ -7,6 +7,7 @@ require_relative "session_chain"
 require_relative "recap_store"
 require_relative "guardrails/context"
 require_relative "guardrails/review_paths"
+require_relative "participant_mode"
 
 module Samagotchi
   autoload :SessionManager, File.expand_path("session_manager", __dir__)
@@ -75,6 +76,7 @@ module Samagotchi
       subjects = check_subjects(subjects, dir: dir)
       raise Refused, NO_SUBJECTS if subjects.empty?
 
+      setup = setup.with(toolkit_origin: "chosen")
       SessionManager.spawn_session(prompt: nil, preview: preview(subjects), working_directory: dir, model_name: model,
                                    setup: setup, review: SessionReview.new(subjects: subjects),
                                    note: note(subjects: subjects), note_source: NOTE_SOURCE, state_dir: state_dir)
@@ -103,7 +105,8 @@ module Samagotchi
       recap = RecapStore.read(Session.session_dir(source.id, state_dir: sd))
       session = SessionManager.spawn_session(
         prompt: nil, preview: preview(subjects, source: source), working_directory: dir, model_name: choice.model,
-        setup: SessionSetup.of(source), review: SessionReview.new(subjects: subjects, from: source.id),
+        setup: SessionSetup.of(source).with(toolkit_origin: "chosen"),
+        review: SessionReview.new(subjects: subjects, from: source.id),
         note: note(subjects: subjects, source: source, recap: recap, seed: seed), note_source: NOTE_SOURCE, state_dir: sd
       )
       warnings = [choice.warning, session.model_warning].compact
@@ -145,10 +148,11 @@ module Samagotchi
     # @param session [Session]
     # @return [String, nil]
     def share_warning(session)
+      mode = ParticipantMode.of(session)
       return nil if session.review?
 
       count = session.tool_output_count
-      "#{session.id[0, 8]} is a working session, not a review session: a participant's review turn can quote what " \
+      "#{session.id[0, 8]} is a working session, not a review session: a participant's #{mode} turn can quote what " \
         "its history holds (#{count} tool output#{"s" unless count == 1} so far). A review session starts from its recap instead."
     end
 

data/lib/samagotchi/run_options.rb

@@ -166,6 +166,7 @@ module Samagotchi
                  chi memory <ls|rm> [--scope project|system]   the memories; rm moves one to the bundle trash
                  chi bundle <install|upgrade|uninstall|status|diff|list|build|trash|new|test|check|try>
                  chi guardrails replay [--dry-run] [--threshold T] [--model M]   seed System 1's record from answered approvals
+                 chi toolkit report [--days N]   grade toolkit suggestions against the tools sessions used
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME

data/lib/samagotchi/session.rb

@@ -32,6 +32,7 @@ module Samagotchi
     STATUS_RUNNING = "running"
     STATUS_ERROR = "error"
     STATUS_STOPPED = "stopped"
+    TOOLKIT_ORIGINS = %w[chosen default inherited suggested].freeze
 
     # A stopped session's marker, <session dir>/stopped: a stop (chi
     # sessions stop, from another process) creates it instead of rewriting
@@ -222,6 +223,15 @@ module Samagotchi
       @toolkit = value.is_a?(Toolkit) ? value : Toolkit.from_file(value)
     end
 
+    # Why this session is on its toolkit. Files from before the field read
+    # as chosen, so an old default session is never newly suggested.
+    attr_reader :toolkit_origin
+
+    def toolkit_origin=(value)
+      origin = value.to_s
+      @toolkit_origin = TOOLKIT_ORIGINS.include?(origin) ? origin : "chosen"
+    end
+
     # The session's own settings (chi --set), a SessionConfig::Settings:
     # empty for none and for a session from before them. Its core part
     # ({key => value}: recap.enabled) is the file's config_settings, its
@@ -322,7 +332,7 @@ module Samagotchi
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
                    continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
-                   toolkit: nil, settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil,
+                   toolkit: nil, toolkit_origin: "chosen", settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil,
                    working_set_pins: [], review: nil)
       @id = id
       @metadata_version = metadata_version
@@ -355,6 +365,7 @@ module Samagotchi
       self.reasoning_history = reasoning_history
       self.appended_prompt_files = appended_prompt_files
       self.toolkit = toolkit
+      self.toolkit_origin = toolkit_origin
       self.settings = settings
       self.parent_answers = parent_answers
       self.working_set_pins = working_set_pins
@@ -464,6 +475,7 @@ module Samagotchi
         reasoning_history: setup.reasoning_history,
         appended_prompt_files: setup.appended_prompt_files,
         toolkit: setup.toolkit,
+        toolkit_origin: setup.toolkit_origin || "chosen",
         settings: setup.settings,
         parent_answers: setup.parent_answers,
         working_set_pins: setup.working_set_pins,
@@ -534,6 +546,7 @@ module Samagotchi
       "reasoning_history" => nil,
       "appended_prompt_files" => [],
       "toolkit" => nil,
+      "toolkit_origin" => "chosen",
       "bundle_settings" => {},
       "config_settings" => {},
       "interrupted_turn" => nil,

data/lib/samagotchi/session_access/contract.rb

@@ -26,7 +26,7 @@ module Samagotchi
       # bin/chi subcommands that act on this machine: never sessions. chi
       # remote (this machine's list of remotes) runs here under a remote too
       # (Dispatch); the others are refused there.
-      MACHINE = %w[bootstrap update models desktop memory bundle guardrails remote].freeze
+      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit remote].freeze
 
       # "command", "command sub" or either with a flag (its long name) →
       # SUPPORTED or LOCAL_ONLY. A LOCAL_ONLY command or subcommand lists

data/lib/samagotchi/session_access/remote.rb

@@ -193,7 +193,7 @@ module Samagotchi
           return true if owner(id)&.worker?
           return false if monotonic >= deadline
 
-          sleep(WORKER_POLL)
+          @sleeper.call(WORKER_POLL)
         end
       end
 
@@ -310,7 +310,10 @@ module Samagotchi
         reply = request(:post, "#{session_path(id)}/notes", body: { text: text, source: source })
         json = reply.json.is_a?(Hash) ? reply.json : {}
         case reply.status
-        when 200 then NoteDelivery::Result.new(id: id, status: json["status"].to_sym, queued: json["queued"].to_i)
+        when 200
+          raise_refusal(reply) unless json["status"].is_a?(String)
+
+          NoteDelivery::Result.new(id: id, status: json["status"].to_sym, queued: json["queued"].to_i)
         when 409
           return NoteDelivery::Result.new(id: id, status: :refused, queued: 0) if json["error"] == "owned_by_tui"
 
@@ -470,14 +473,13 @@ module Samagotchi
       def context_add_url(target, url, why:, hint:, added_by:)
         reply = request(:post, "#{session_path(target.session_id)}/context",
                         body: { url: url, why: why, hint: hint, added_by: added_by }.compact)
-        if reply.status == 422
+        if reply.status == 422 && no_provider?(reply)
           require_relative "../context_providers"
-          detail = if reply.error == "no_provider" && reply.json["detail"].to_s.start_with?("no installed bundle resolves")
-                     "no installed bundle on #{name} resolves #{url} (chi bundle install github-pr there for GitHub PRs)"
-                   else
-                     "#{reply.json["detail"]} (on #{name})"
-                   end
+          detail = "no installed bundle on #{name} resolves #{url} (chi bundle install github-pr there for GitHub PRs)"
           raise ContextProviders::Invalid, detail
+        elsif reply.status == 422
+          require_relative "../context_providers"
+          raise ContextProviders::Invalid, "#{reply.json["detail"]} (on #{name})"
         end
         context_added(reply)
         reply.json.fetch("name")
@@ -492,7 +494,7 @@ module Samagotchi
         case reply.status
         when 200 then ContextPush.new(status: :pushed, before: reply.json["before"], revision: reply.json["revision"])
         when 404
-          return ContextPush.new(status: :missing) if reply.error == "not_found"
+          return ContextPush.new(status: :missing) if context_missing?(reply)
 
           raise_refusal(reply)
         when 409 then ContextPush.new(status: :not_push)
@@ -513,7 +515,7 @@ module Samagotchi
       def context_entry(target, name)
         ContextSources.check_name!(name)
         reply = request(:get, "#{session_path(target.session_id)}/context/#{name}", query: { full: 1 })
-        return nil if reply.status == 404 && reply.error == "not_found" && reply.json["detail"].to_s.start_with?("no source")
+        return nil if context_missing?(reply)
 
         raise_refusal(reply) unless reply.status == 200
 
@@ -527,7 +529,7 @@ module Samagotchi
         case reply.status
         when 200 then :removed
         when 409 then reply.error == "project_source" ? :project : raise_refusal(reply)
-        when 404 then reply.json["detail"].to_s.start_with?("no source") ? :missing : raise_refusal(reply)
+        when 404 then context_missing?(reply) ? :missing : raise_refusal(reply)
         else raise_refusal(reply)
         end
       end
@@ -655,6 +657,21 @@ module Samagotchi
         reply.status == 404 && reply.error == "not_found" && reply.json["detail"].to_s.start_with?("not found: /")
       end
 
+      def context_missing?(reply)
+        return false unless reply.status == 404
+        return true if reply.error == "context_missing"
+
+        # Older chi web used not_found for a missing context source.
+        reply.error == "not_found" && reply.json["detail"].to_s.start_with?("no source")
+      end
+
+      def no_provider?(reply)
+        return true if reply.error == "no_provider"
+
+        # Older chi web didn't give this refusal its own error code.
+        reply.json["detail"].to_s.start_with?("no installed bundle resolves")
+      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.
@@ -674,7 +691,10 @@ module Samagotchi
         when "continued", "open_children", "folder_gone"
           raise SessionContinue::Refused.new(sid, reason, ids: Array(json["ids"]))
         when "held", "not_running", "unsupported", "failed"
-          raise SessionManager::RestartRefused.new(sid, reason, version: json["version"]) if reason
+          if reason
+            raise SessionManager::RestartRefused.new(sid, reason, version: json["version"], holds: json["holds"],
+                                                     pid: json["pid"], via: invocation)
+          end
         when "parent_answers_refused", "parent_continue_refused", "no_vision"
           raise Refused.new(message.to_s, code: error)
         # No model configured there, or --model's host unknown there: what

data/lib/samagotchi/session_access/web_bridge_client.rb

@@ -67,7 +67,14 @@ module Samagotchi
           end
         end
 
-        def stream(sock, status, headers) = BridgeClient::StreamOpen.classify(sock, status, headers)
+        def stream(sock, status, headers, session_id:, remote:)
+          outcome = BridgeClient::StreamOpen.classify(sock, status, headers)
+          return outcome unless status.to_i == 503 && outcome.is_a?(BridgeClient::StreamOpen::Unreachable)
+
+          expected = [WorkerLink.unanswered(session_id), WorkerLink.not_live(session_id)]
+          detail = expected.include?(outcome.detail) ? outcome.detail : WorkerLink.not_live(session_id)
+          BridgeClient::StreamOpen::Unreachable.new(attempts: outcome.attempts, detail: "#{detail} on #{remote}")
+        end
 
         def bridge(status, **body) = BridgeClient::Response.new(status: status, body: JSON.generate(body.compact))
       end
@@ -223,7 +230,7 @@ module Samagotchi
         end
         return refused("chunked_unsupported", sock) if headers["transfer-encoding"].to_s.downcase.include?("chunked")
 
-        Mapping.stream(sock, status, headers)
+        Mapping.stream(sock, status, headers, session_id: @session_id, remote: @remote.name)
       rescue SystemCallError, SocketError, IOError
         sock&.close rescue nil
         BridgeClient::StreamOpen::Unreachable.new(attempts: 1)

data/lib/samagotchi/session_manager.rb

@@ -23,10 +23,12 @@ require_relative "host_registry"
 require_relative "utf8_default"
 require_relative "turn_note"
 require_relative "owner_lock"
+require_relative "process_group"
 require_relative "bridge_client"
 require_relative "worker_sidecar"
 require_relative "worker_link"
 require_relative "worker_signals"
+require_relative "chi_invocation"
 require_relative "log"
 require_relative "log_path"
 require_relative "paths"
@@ -194,6 +196,7 @@ module Samagotchi
         review: review
       )
       session.toolkit = Toolkit.configured(delegate: delegate) if session.toolkit.nil?
+      session.toolkit_origin = setup.toolkit_origin || "default"
       session.model_warning = model_warning
       # With no prompt there is no first turn to run (an attaching UI sends
       # the prompts), so the session starts idle.
@@ -629,16 +632,18 @@ module Samagotchi
     # worker from before restarts, running +version+: stop it instead), a
     # WorkerIdleExit#hold_for_restart hold (:turn_running, :reminders, ...),
     # :fallback_held (disk-visible work blocks an unresponsive-worker restart),
-    # or :failed (the worker answered something else or didn't release).
+    # :stopped (its worker, +pid+, is SIGSTOPped: neither the ask nor a TERM
+    # reaches it until it is continued), or :failed (the worker answered something else or didn't release).
     class RestartRefused < StandardError
-      attr_reader :session_id, :reason, :version, :holds
+      attr_reader :session_id, :reason, :version, :holds, :pid
 
-      def initialize(session_id, reason, version: nil, holds: [])
+      def initialize(session_id, reason, version: nil, holds: [], pid: nil, via: ChiInvocation::HERE)
         @session_id = session_id
         @reason = reason.to_sym
         @version = version
         @holds = Array(holds).map(&:to_sym).freeze
-        super(RestartRefused.words(session_id, @reason, version, @holds))
+        @pid = pid
+        super(RestartRefused.words(session_id, @reason, version, @holds, pid: pid, via: via))
       end
 
       HOLDS = {
@@ -654,17 +659,22 @@ module Samagotchi
       }.freeze
 
       # What the CLI and the web say.
-      def self.words(session_id, reason, version = nil, holds = [])
+      def self.words(session_id, reason, version = nil, holds = [], pid: nil, via: ChiInvocation::HERE)
+        stop = via.command("sessions stop #{session_id}")
         case reason
+        when :stopped
+          where = via.remote? ? " on #{via.remote}" : ""
+          "session #{session_id}'s worker#{" (pid #{pid})" if pid} is stopped (SIGSTOP or Ctrl-Z) and can't take " \
+            "a restart: continue it#{" with `kill -CONT #{pid}`" if pid}#{where}, then restart again"
         when :not_running
           "session #{session_id} has no running worker; the next prompt starts one on the newest chi"
         when :unsupported
           "session #{session_id}'s worker runs chi #{version || "(older)"}, which can't restart: " \
-            "chi sessions stop #{session_id}, then any prompt starts it on the newest chi"
+            "#{stop}, then any prompt starts it on the newest chi"
         when :fallback_held
           why = holds.map { |hold| HOLDS.fetch(hold, hold.to_s.tr("_", " ")) }.join("; ")
           "session #{session_id} has disk-visible work that a restart might lose#{": #{why}" unless why.empty?}; " \
-            "run `chi sessions stop #{session_id}`, then any prompt starts it on the newest chi"
+            "run `#{stop}`, then any prompt starts it on the newest chi"
         when :failed then "session #{session_id}'s worker didn't take the restart"
         else "not now: #{HOLDS.fetch(reason, reason.to_s.tr("_", " "))}"
         end
@@ -692,6 +702,10 @@ module Samagotchi
       sd = state_dir || Session.default_state_dir
       Session.load(session_id, state_dir: sd) # ArgumentError for none
       owner = refuse_tui!(session_id, state_dir: sd)
+      # A stopped worker answers neither the ask (READ_TIMEOUT) nor the
+      # fallback's TERM (FALLBACK_STOP_WAIT): say so now, not after ~70 s.
+      raise RestartRefused.new(session_id, :stopped, pid: owner.pid) if owner&.worker? && ProcessGroup.stopped?(owner.pid)
+
       dir = Session.session_dir(session_id, state_dir: sd)
       link = WorkerLink.resolve(dir, unlink: false, owner: owner)
       if link.is_a?(WorkerLink::Skew)