samagotchi 0.121.0 → 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
 
@@ -271,7 +272,14 @@ module Samagotchi
       # System 1: the ask is judged before the user sees it, and in `on` mode
       # one that passes every gate is allowed once without reaching them
       # (docs/guardrails.md, "System 1").
-      judgment = system_one_judge(payload)
+      judgment = begin
+        system_one_judge(payload)
+      rescue LLM::RequestCancelled
+        return turn_stopped(verdict)
+      end
+      # A turn stopped while the judge was asked opens no card.
+      return turn_stopped(verdict) if @cancelled_lookup.call
+
       if judgment && judgment[:auto]
         verdict.judgment = { id: judgment[:id], p: judgment[:p] }
         verdict.settle!(:allow, decided_by: "system one")
@@ -286,6 +294,12 @@ module Samagotchi
 
     private
 
+    # The deny for a call whose turn was stopped before its ask reached the
+    # user (as Guardrails::Gate words one stopped before the vote).
+    def turn_stopped(verdict)
+      verdict.settle!(:deny, decided_by: "core", note: "The turn was stopped before the user was asked.")
+    end
+
     # The judgments log (SystemOne::Log), beside the approvals store; nil
     # while there is no store dir.
     def system_one_log
@@ -319,6 +333,8 @@ module Samagotchi
                                                             entries: entries),
                    questions: { SystemOne::ApprovalQuestion::ID => SystemOne::ApprovalQuestion.question },
                    cancel_controller: @cancel_controller.call)
+      rescue LLM::RequestCancelled
+        raise
       rescue StandardError => e
         # The client already turns every failure it knows into a nil; this is
         # the unexpected one. Either way the ask goes to the user.
@@ -338,6 +354,8 @@ module Samagotchi
                         latency_ms: latency_ms, decision: decision, origin: "live")
       # A judgment the log cannot hold is no judgment: the user is asked.
       { id: id, p: p, auto: auto && !id.nil? }
+    rescue LLM::RequestCancelled
+      raise
     rescue StandardError => e
       # The approval never fails because of System 1.
       Samagotchi::Log.warn(:guardrails, "system_one_judgment_failed", error: "#{e.class}: #{e.message}")
@@ -408,7 +426,7 @@ module Samagotchi
                   "deny"
                 end
       end
-      system_one_log.label(id, label)
+      system_one_log.label(id, label, question_id: (answer.id if answer.is_a?(Samagotchi::QuestionAnswer)))
     rescue StandardError => e
       Samagotchi::Log.warn(:guardrails, "system_one_label_failed", error: "#{e.class}: #{e.message}")
       nil

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -69,6 +69,15 @@ module Samagotchi
         # memory-remove rule's ask, which a parent may answer.
         return false if fetch(facts, :rule).to_s == MEMORY_REMOVE_RULE
 
+        chi_files?(facts)
+      end
+
+      # Whether an approval's paths or command name chi's own dirs (#chi_dirs)
+      # or CHI_TEXT, whatever its rule: the part of #protected_facts? that
+      # System 1's SystemOne::SelfProtect shares.
+      def chi_files?(facts)
+        return false unless facts.is_a?(Hash)
+
         dirs = chi_dirs
         paths = Array(fetch(facts, :paths)).map(&:to_s).reject(&:empty?)
         return true if paths.any? { |path| dirs.any? { |dir| ProtectedPaths.within?(ProtectedPaths.real(path), dir) } }

data/lib/samagotchi/guardrails_command.rb

@@ -61,6 +61,7 @@ module Samagotchi
     # uses.
     SKIP_WORDS = {
       already_replayed: "already replayed",
+      judged_live: "already judged live",
       answered_by_parent: "answered by a parent agent",
       parent_cannot_allow: "answered by a parent that could not allow",
       unanswered: "unanswered",
@@ -73,6 +74,36 @@ module Samagotchi
     # and when the user was asked.
     Ask = Data.define(:question_id, :session_id, :approval, :label, :asked_at)
 
+    # What the judgments log already holds, so no ask is judged twice: the
+    # question ids its judgments name, with their origin (a replay's own, a
+    # live one's through its label), and, for live judgments with none (an ask that was
+    # cancelled, or a line older than the id), how many each (session, call
+    # digest) has. A card with no id match takes one of those (#take_live).
+    Judged = Data.define(:question_ids, :live_calls) do
+      # @param entries [Array<Hash>] SystemOne::Log#entries
+      def self.of(entries)
+        ids = entries.filter_map { |entry| [entry["question_id"], entry["origin"]] if entry["question_id"] }.to_h
+        live = Hash.new(0)
+        entries.each do |entry|
+          next unless entry["origin"] == "live" && entry["question_id"].nil?
+
+          live[[entry["session_id"], entry["call_digest"]]] += 1
+        end
+        new(question_ids: ids, live_calls: live)
+      end
+
+      # Whether a live judgment without a question id is this card's: true
+      # (and that judgment counted off) while one with its session and call
+      # digest is left.
+      def take_live(session_id, approval)
+        key = [session_id, SystemOne::ApprovalQuestion.call_fields(approval)["call_digest"]]
+        return false unless live_calls[key].positive?
+
+        live_calls[key] -= 1
+        true
+      end
+    end
+
     # @param argv [Array<String>] the arguments after "guardrails"
     # @param client [SystemOne::Client, nil] the judgment client; nil: the
     #   one config.yml describes (the seam the specs pass a fake through)
@@ -122,7 +153,7 @@ module Samagotchi
 
       sessions_dir = @sessions_dir || Session.default_state_dir
       log = @log || SystemOne::Log.new(dir: Guardrails::Approvals.dir_for(sessions_dir))
-      replayed = File.exist?(log.path) ? log.entries.filter_map { |entry| entry["question_id"] if entry["origin"] == "replay" }.to_set : Set.new
+      judged = Judged.of(File.exist?(log.path) ? log.entries : [])
       @dry_run = options[:dry_run] ? true : false
 
       asks = []
@@ -140,7 +171,7 @@ module Samagotchi
           end
 
           entries.each do |entry|
-            ask = ask_of(entry, name, replayed, sessions_dir)
+            ask = ask_of(entry, name, judged, sessions_dir)
             next if ask.nil?
 
             ask.is_a?(Symbol) ? skipped[ask] += 1 : asks << ask
@@ -168,9 +199,10 @@ module Samagotchi
     end
 
     # One card entry as an ask to judge: an Ask, a skip reason (:already_replayed,
-    # :answered_by_parent, :parent_cannot_allow, :unanswered, :no_approval,
-    # :no_question_id), or nil for an entry that is not a question at all.
-    def ask_of(entry, session_id, replayed, sessions_dir)
+    # :judged_live, :answered_by_parent, :parent_cannot_allow, :unanswered,
+    # :no_approval, :no_question_id), or nil for an entry that is not a
+    # question at all.
+    def ask_of(entry, session_id, judged, sessions_dir)
       return nil unless entry.is_a?(Hash) && entry[:type] == "question"
 
       pending = entry[:pending_question]
@@ -178,7 +210,10 @@ module Samagotchi
 
       question_id = pending[:id].to_s
       return :no_question_id if question_id.empty?
-      return :already_replayed if replayed.include?(question_id)
+
+      origin = judged.question_ids[question_id]
+      return origin == "replay" ? :already_replayed : :judged_live if origin
+      return :judged_live if judged.take_live(session_id, pending[:approval])
 
       answer = entry[:answer]
       label = if entry[:cancelled]

data/lib/samagotchi/image_store.rb

@@ -201,6 +201,9 @@ module Samagotchi
   # a request is sent.
   module ImageStore
     class Error < StandardError
+      # A ref to a file this session doesn't hold as an image: one wording
+      # for a turn's refs (#check_refs) and a web upload's (#ref_for).
+      def self.unknown_image(file) = new("unknown image #{file.to_s[0, 80]}")
     end
 
     DIR = "images"
@@ -278,7 +281,7 @@ module Samagotchi
 
         ref = symbolize(image)
         return "images are refs to uploaded files, not paths" if ref.key?(:path)
-        return "unknown image #{ref[:file].to_s[0, 80]}" unless valid_ref?(session_dir, ref)
+        return Error.unknown_image(ref[:file]).message unless valid_ref?(session_dir, ref)
 
         { file: ref[:file].to_s, name: File.basename(ref[:name].to_s)[0, 120] }
       end
@@ -321,11 +324,11 @@ module Samagotchi
     # A ref for an image already stored in this session (a web upload),
     # rebuilt from the file itself: only its name comes from the caller.
     def self.ref_for(session_dir, file:, name: nil, source: "user")
-      raise Error, "unknown image #{file.to_s[0, 80]}" unless valid_ref?(session_dir, { file: file })
+      raise Error.unknown_image(file) unless valid_ref?(session_dir, { file: file })
 
       bytes = File.binread(File.join(session_dir.to_s, file.to_s))
       info = ImageHeader.read(bytes)
-      raise Error, "unknown image #{file}" unless info && MIME.key?(info.format) && info.width
+      raise Error.unknown_image(file) unless info && MIME.key?(info.format) && info.width
 
       name = File.basename(name.to_s).gsub(/[[:cntrl:]]/, "")[0, 120]
       { file: file.to_s, mime: MIME.fetch(info.format), width: info.width, height: info.height,

data/lib/samagotchi/interrupted_turn.rb

@@ -13,9 +13,12 @@ module Samagotchi
   # runs (its ack's id, LastTurn#enqueued_id once it ends; a Continue turn
   # carries its offer turn's), so any process that loads the session can
   # tell which turn is running (ReplyWait.own_turn); nil when it ran none,
-  # or a worker from before it wrote one.
-  InterruptedTurn = Data.define(:id, :started_at, :at, :iteration, :enqueued_id) do
-    def initialize(id: nil, started_at: nil, at: nil, iteration: nil, enqueued_id: nil) = super
+  # or a worker from before it wrote one. author: a participant's turn's
+  # "p:<id>" (nil for the owner's), which its settled record keeps, so a
+  # chi web restarted since still knows whose wait it is
+  # (ParticipantAccess#turn_author).
+  InterruptedTurn = Data.define(:id, :started_at, :at, :iteration, :enqueued_id, :author) do
+    def initialize(id: nil, started_at: nil, at: nil, iteration: nil, enqueued_id: nil, author: nil) = super
 
     # A saved record (string or symbol keys), an InterruptedTurn as it is;
     # nil for anything else.

data/lib/samagotchi/live_versions.rb

@@ -2,7 +2,7 @@
 
 require_relative "session"
 require_relative "version"
-require_relative "worker_sidecar"
+require_relative "worker_link"
 require_relative "web/info_probe"
 
 module Samagotchi
@@ -21,13 +21,12 @@ module Samagotchi
 
     # @return [Array<Worker>] the workers whose Bridge answers, by session id
     def workers(state_dir: Session.default_state_dir)
-      Dir[File.join(state_dir, "*", WorkerSidecar::FILE)].sort.filter_map do |path|
-        session_dir = File.dirname(path)
-        sidecar = WorkerSidecar.live(session_dir, unlink: false)
-        next unless sidecar
+      WorkerLink.each_dir(state_dir).filter_map do |session_dir|
+        link = WorkerLink.resolve(session_dir, unlink: false)
+        next unless link.live?
 
-        Worker.new(session_id: File.basename(session_dir), version: sidecar.version,
-                   restart: sidecar.features.include?("restart"))
+        Worker.new(session_id: File.basename(session_dir), version: link.version,
+                   restart: link.features.include?("restart"))
       end
     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_bundle/profile.rb

@@ -152,7 +152,7 @@ module Samagotchi
       # @raise [Uninstaller::UninstallError] when +name+ isn't installed
       def uninstall(name, shipped_dir: SourceNormalizer::SHIPPED_DIR, force: false)
         bundle = Provenance.new(name: name).record
-        raise Uninstaller::UninstallError, "Bundle '#{name}' is not installed" unless bundle
+        raise Uninstaller::UninstallError.not_installed(name) unless bundle
 
         shipped = File.join(shipped_dir, name)
         manifest = File.file?(File.join(shipped, "manifest.yml")) ? Manifest.read(dir: shipped) : nil

data/lib/samagotchi/memory_bundle/uninstaller.rb

@@ -12,7 +12,11 @@ require_relative "../model_overlay"
 module Samagotchi
   module MemoryBundle
     class Uninstaller
-      class UninstallError < StandardError; end
+      class UninstallError < StandardError
+        # The bundle +name+ has no install record: one wording for the
+        # uninstall of a bundle and of a profile (Profile#uninstall).
+        def self.not_installed(name) = new("Bundle '#{name}' is not installed")
+      end
 
       # removed_files: the bundle's own hooks/ and plugin/ files (deleted);
       # trashed_files: its memory files, moved to trash_dir (Trash), nil
@@ -34,7 +38,7 @@ module Samagotchi
       def run
         provenance = Provenance.new(name: @name)
         bundle = provenance.record
-        raise UninstallError, "Bundle '#{@name}' is not installed" unless bundle
+        raise UninstallError.not_installed(@name) unless bundle
 
         # The scope from the flag, else the record's
         target_scope = @scope.to_s.strip.empty? ? bundle.effective_scope : @scope

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

@@ -24,9 +24,11 @@ module Samagotchi
       # A call not listed gets no floor check: it is in the first tag (v0.2.0:
       # chi.command/tool/on/service/init, ctx.settings, ctx.sessions,
       # ctx.ask_model, ctx.notify, ctx.card, ctx.messages…). A member of
-      # one (ctx.sessions.children) is listed when it came later. Keys have
-      # no "?" (API_CALL drops it). A keyword added later (ctx.ask_model's
-      # model: in 0.80.0, ctx.sessions.send's delivery: in 0.64.0) has none.
+      # one (ctx.sessions.children) is listed when it came later; fork, send
+      # and read are in v0.2.0. Keys have no "?" (API_CALL drops it). A
+      # keyword added later is "call(keyword:)", the call's receiver as the
+      # plugin writes it (Check#keyword_calls: `ctx.sessions.send(…,
+      # delivery:)` is seen, a `sessions = ctx.sessions` alias isn't).
       # Events aren't listed: chi.on takes any symbol and an older chi never
       # fires one it doesn't know (harmless; chi bundle check warns on it),
       # and a manifest hook's events: list (BundleHook) needs the bundle's
@@ -42,7 +44,8 @@ module Samagotchi
         "chi.tool_source" => "0.67.0", "chi.peer_source" => "0.67.0", "ctx.http" => "0.80.0",
         "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0", "ctx.load_tools" => "0.99.0",
         "ctx.usage" => "0.100.0", "ctx.sessions.stop" => "0.34.0", "ctx.turn_author" => "0.106.0",
-        "ctx.sessions.review" => "0.107.0"
+        "ctx.sessions.review" => "0.107.0", "ctx.sessions.send(delivery:)" => "0.64.0",
+        "chi.toolkit(prompt:)" => "0.72.0", "ctx.ask_model(model:)" => "0.80.0", "chi.toolkit(groups:)" => "0.121.0"
       }.freeze
 
       # @param bundle [String]
@@ -309,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)
+        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)
@@ -330,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/plugin/sessions.rb

@@ -3,7 +3,7 @@
 require_relative "../client_id"
 require_relative "../delivery"
 require_relative "../session"
-require_relative "../bridge_client"
+require_relative "../worker_link"
 require_relative "../bridge/turn_accumulator"
 require_relative "../tools/delegate"
 require_relative "../children_status"
@@ -27,6 +27,11 @@ module Samagotchi
       # A fork, send, read or stop that couldn't be done; the message says why.
       class Error < StandardError; end
 
+      # What starting a session can be refused by, answered as Error with
+      # chi's own message: a model that is gone, a toolkit the config refuses,
+      # a bad argument. #review adds its own: a subject it won't take.
+      REFUSED = [ModelProfile::MissingModel, Toolkit::Refused, ArgumentError].freeze
+
       # @param host [Host] session_id, cwd, model_name and state_dir
       def initialize(host)
         @host = host
@@ -44,7 +49,9 @@ module Samagotchi
       # @param prompt [String, nil] the child's first turn
       # @return [String] the child's id
       # @raise [Error] no session yet, a scratch session (the child would
-      #   outlive it), or too many children running
+      #   outlive it), too many children running, or the model or toolkit the
+      #   child starts on being refused (a config kit with an invalid groups:,
+      #   a model that is gone)
       def fork(messages:, title: nil, prompt: nil)
         parent_id = @host.session_id.call or raise Error, "this session has no id yet"
         raise Error, "a scratch session starts no other sessions: they would outlive it" if @host.scratch&.call
@@ -60,6 +67,8 @@ module Samagotchi
           setup: @host.setup&.call || SessionSetup.new
         )
         child.id
+      rescue *REFUSED => e
+        raise Error, e.message
       end
 
       # A review of this session (ReviewStart.fork, chi review --from): a new
@@ -81,7 +90,7 @@ module Samagotchi
 
         ReviewStart.fork(from: source, subjects: Array(subjects), seed: seed, state_dir: state_dir,
                          recap_wait: recap_wait).id
-      rescue ReviewStart::Refused, ModelProfile::MissingModel, ArgumentError => e
+      rescue *REFUSED, ReviewStart::Refused => e
         raise Error, e.message
       end
 
@@ -212,7 +221,7 @@ module Samagotchi
       end
 
       def live_snapshot(sid, state_dir)
-        BridgeClient.discover(sid, session_dir: Session.session_dir(sid, state_dir: state_dir))&.get_json("snapshot")
+        WorkerLink.client(sid, session_dir: Session.session_dir(sid, state_dir: state_dir))&.get_json("snapshot")
       rescue StandardError
         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/push_command.rb

@@ -135,7 +135,7 @@ module Samagotchi
     # route does). @return [Boolean] delivered
     def test(sub)
       result = client_for(sub).deliver(sub, Web::Push::TEST_PAYLOAD, ttl: Web::Push::TEST_TTL, urgency: "high")
-      words = "#{result.status} #{result.code}#{" (#{result.ms} ms)" if result.ms}"
+      words = [result.status, result.code, ("(#{result.ms} ms)" if result.ms)].reject { |part| part.to_s.empty? }.join(" ")
       words += ": #{result.error}" if result.error && !result.ok?
       if result.status == :gone
         @store.remove(sub.id)