samagotchi 0.122.0 → 0.123.0

data/docs/internals/prompt-caching.md

@@ -73,6 +73,16 @@ right-hand column happens.
   beside `apply_staged_tools!`, then `reset!`): the chat loop builds `tools:` per request, so a mid-turn change
   would differ from the turn's prompt. Under `full` nothing is filtered and no line is added: the bytes are what
   they were before toolkits.
+- A toolkit suggestion (`toolkit.suggest.mode: on`) is set before `apply_toolkit!` of the turn it was asked on
+  (`Engine#settle_toolkit_suggestion` → `ToolkitBinding#suggest`), and no request goes out before that, so on a
+  session's first turn it costs nothing. Its **deferred switch** (a later prompt after `undecided`, within
+  `toolkit.suggest.defer_turns` / `defer_tokens`) is engine-side, so `/toolkit`'s CacheConfirm doesn't apply: it
+  changes the declared tools at the front of the request, and the server re-reads **system prompt + tools +
+  conversation** on that turn. The defer bound keeps that conversation small; its notice says "from this turn".
+  When System 1 runs on the model's own single-slot local server (`Engine#toolkit_judge_shares_local_host?`), any
+  ask takes the slot and evicts its cached prefix: a first-turn ask costs that cache even when nothing switches
+  (there is little cached on a session's first turn), so on mode asks only there, skips the deferred path, and
+  sends no worker warm-up.
 - A kit's prompt text (`toolkit.kits.<name>.prompt:`, `chi.toolkit … prompt:`) sits after the appended files and
   before the memory indexes (`SystemPrompt#kit_prompt_section`): one prefix per kit, never per-session text, so
   sessions on the kit share it; a memory write (the indexes after it) doesn't move it. It is part of the
@@ -119,13 +129,15 @@ right-hand column happens.
   dropped or brought back) is a tail system message after the history, one per turn with ops, escaped as context
   notes are (`Prompt::ESCAPED_KINDS`). The turn-end warm-up never warms a drop sent after the turn: it misses once.
 - **Participants** ([participants.md](participants.md#attribution)). A participant's message carries a wire-only
-  header line (`Steer.review_header`), a pure function of the saved message (its `author_name` included), so a
-  replay sends the same bytes; the owner's messages are sent as before (`spec/review_contribution_spec.rb`, per loop
-  and on a Messages host). The participants line opens the system prompt's volatile tail, after breakpoint #1:
-  a new session's cache is untouched. The Engine checks the sidecar at each turn's start and rebuilds (`reset!`)
-  only when the first participant joins and when the last leaves or expires: one history re-read each, then stable.
-  Under D3(a) the declared tools stay the session's, so an author switch costs nothing: the review boundary is a
-  gate on the calls, not a toolkit switch. The forged-header mark (`(quoted) `) is a pure function of the text too.
+  header line (`Steer.review_header`), a pure function of the saved message (its `author_name` and its
+  `participant_mode` stamp included: a review or a pair header), so a replay sends the same bytes; the owner's
+  messages are sent as before (`spec/review_contribution_spec.rb`, per loop and on a Messages host). The
+  participants line opens the system prompt's volatile tail, after breakpoint #1: a new session's cache is
+  untouched. Its words follow the session's `ParticipantMode` (a review or a working session's line), which never
+  changes for a session. The Engine checks the sidecar at each turn's start and rebuilds (`reset!`) only when the
+  first participant joins and when the last leaves or expires: one history re-read each, then stable. Under D3(a)
+  the declared tools stay the session's, so an author switch costs nothing: the review and pair boundaries are
+  gates on the calls, not a toolkit switch. The forged-header mark (`(quoted) `) is a pure function of the text too.
 - Side requests (idle recap, `/btw`) go through `IdleClient` with their own short system prompt (the recap's also
   asks for its auto title line, `RecapPrompt::TITLE`: static text, still that one request). On a current
   llama.cpp they don't evict the session (see the server settings below); chi never pins them to a slot.

data/docs/internals/web-push.md

@@ -101,10 +101,12 @@ The service worker is the only reader of the payload (JSON, at most `Notifier::O
 
 - `{"v":1,"kind":"show","tag":KEY,"title":…,"body":…,"url":URL,"badge":N,"open":[KEY…]}`: a waiting
   reason's (approval, question, continue, card) TTL 12 h (`SHOW_TTL`), `Urgency: high`; a failed or done turn's
-  TTL 10 min (`EVENT_TTL`), `Urgency: normal`. `open` only while the whole list fits the limit; the test push
+  TTL 10 min (`EVENT_TTL`), `Urgency: normal`; an available chi update uses a 24 h TTL (`UPDATE_TTL`) and
+  `Urgency: normal`. `open` only while the whole list fits the limit; the test push
   (`chi:test`) has neither `open` nor `badge`. URL (`Notifier.session_url`) is the session in its own project's
   view, `/?dir=<project root>#/s/<id>` (the folder URL-encoded, its slashes kept), or `/?scope=all#/s/<id>` for a
-  session in no repo: never the bare `/`, which is chi web's start project.
+  session in no repo: never the bare `/`, which is chi web's start project (except the update show, which names no
+  session: `/`).
 
 `badge` and `open` are the waiting keys still open in the Notifier's summaries (`Attention.open_keys`: a pending
 question of any reason, a hook's and a continue's too, not relayed, and a card with actions; never a failed or done
@@ -160,7 +162,9 @@ the top and in `pending_question` / `pending_card`, strings in `last_turn`), `no
 from chi web's request threads (`SessionHub#touch`, from the stop/archive/delete routes), so it only enqueues: a push
 is a 0.5 s https call. `emit` already rescues a raising sink. The sink keeps the last summary per session and turns
 each `session` / `session_gone` event into a `Show` (with its text) or a `Close` (it was answered anywhere) on a
-Queue.
+Queue. A `chi` event marked `update_notice` becomes a `chi:update:<version>` show for the bare page; the checker
+sets that marker only for a newly selected version not already in its persistent `notified` list. It uses the same
+Presence skip and hourly CAP as session shows, and the 24-hour TTL lets an offline phone receive it later.
 
 **Seeding**: `Notifier#start(hub)` subscribes with `snapshot: true` and takes the summaries as the seed, so what is
 open already never pushes. The hub's projection is empty before its first scan, so `Server.start` runs `hub.scan`

data/docs/sessions.md

@@ -264,7 +264,9 @@ A session can **continue** an earlier one: "the next run of the same routine" (a
 ## Review sessions
 
 A **review session** is one made to be shared with participants (the shared-sessions plan's D2: a review is its own
-session, so a participant's review turn can't quote a working session's tool outputs). `chi review FILE…` starts one
+session, so a participant's review turn can't quote a working session's tool outputs, and only reads). Sharing a
+working session itself is pairing: a participant's turns there act with its tools under the owner's guardrails
+([CLI: Participants](cli.md#participants), [guardrails](guardrails.md#a-participants-pair-boundary)). `chi review FILE…` starts one
 in a project, `chi review --from ID` as a review fork of a working session (see [CLI: Review
 sessions](cli.md#review-sessions)); both start idle and print the `chi share` line to invite someone.
 
@@ -292,7 +294,8 @@ sessions](cli.md#review-sessions)); both start idle and print the `chi share` li
   space-separated, relative to the page's folder; a path with a space in double quotes, `"docs/my plan.md"`): its
   chip then reads `review: plan.md +1`, and Start makes a review session (the message typed, if any, is its first
   turn; with none it starts idle). A refused file shows the server's one message in the chip's form, opened again. On a session that isn't a review session the participants panel (the session bar's
-  participants chip) says so before its Invite, with the share warning (how many tool outputs its history holds)
+  participants chip) says so before its Invite, with the share warning (that a participant's turns act there, writes
+  included and asks to the owner, or only read while an older worker holds it; how many tool outputs its history holds)
   and **Start a review of it**: a review fork of it, opened, with a toast (`Review 4b7e9a01 started from 3f9a1c2e's
   recap; 3f9a1c2e keeps running.`) whose **Invite** opens the new session's panel. Every summary carries `review`
   (null for other sessions).
@@ -311,7 +314,8 @@ declares every tool (full). The file stores only the name: a kit's tools and pro
 
 `toolkit_origin` records why the session is on that kit: `default` for the configured kit, `chosen` for a
 user-selected kit (including `/toolkit` and `ctx.use_toolkit`), `inherited` for a continue or fork, or `suggested`
-for a future toolkit suggestion. A session file from before the field reads as `chosen`.
+when `toolkit.suggest.mode: on` switched it ([Toolkits](configuration.md#toolkits)). A session file from before the
+field reads as `chosen`. Only a `default` session is ever suggested a kit.
 
 A `find_tools` result on a chat host saves the tools its hit loads as `loaded: ["list_sessions", "mcp_fs_read"]` on
 its `tool_response` entry (wire names: a built-in's, an MCP tool's `mcp_<server>_<tool>`), whatever the host: a

data/lib/samagotchi/bridge.rb

@@ -629,8 +629,11 @@ module Samagotchi
     # review_turns: a participant's turn runs as its own, inside the review
     # boundary (Guardrails::ReviewBoundary); a worker without it has none,
     # so chi web sends it no participant's turn (Delivery::REVIEW_FEATURE).
+    # pair_turns: a participant's turn in a working session runs as a pair
+    # turn (Guardrails::PairBoundary); a worker without it runs it as a
+    # review turn, and chi web says so (Delivery::PAIR_FEATURE).
     FEATURES = ["restart", "task_stop", "reparent", Delivery::QUEUE_FEATURE, ReplyWait::TURN_IDS_FEATURE,
-                SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE].freeze
+                SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE, Delivery::PAIR_FEATURE].freeze
 
     # The routes, by method and what follows /session/:id/: a handler takes
     # the session id and the request body and returns [headers, status, body].

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.122.0
+version: 0.123.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/config.rb

@@ -249,7 +249,8 @@ module Samagotchi
       # delegate child's. toolkit.kits (the user's own) is read by Toolkit.kits.
       Entry.new(key: "toolkit.default",          yaml_path: %w[toolkit default],          type: :string, default: nil,              expose: %i[env config], lifecycle: :session_creation),
       Entry.new(key: "toolkit.child",            yaml_path: %w[toolkit child],            type: :string, default: nil,              expose: %i[env config], lifecycle: :session_creation),
-      # Toolkit suggestion (ToolkitSuggest): off, audit, or on; on currently behaves as audit and never changes a session.
+      # Toolkit suggestion (ToolkitSuggest): off; audit (logs, never blocks or changes a session); on (the first eligible
+      # turn waits up to guardrails.system_one.timeout_ms and may start on the suggested kit).
       Entry.new(key: "toolkit.suggest.mode",     yaml_path: %w[toolkit suggest mode],     type: :enum,   default: "off", expose: %i[config], enum_values: %w[off audit on], lifecycle: :worker_start),
       Entry.new(key: "toolkit.suggest.threshold", yaml_path: %w[toolkit suggest threshold], type: :float, default: 0.5, expose: %i[config], lifecycle: :worker_start),
       Entry.new(key: "toolkit.suggest.defer_turns", yaml_path: %w[toolkit suggest defer_turns], type: :integer, default: 3, expose: %i[config], lifecycle: :worker_start),
@@ -289,6 +290,11 @@ module Samagotchi
       Entry.new(key: "update.gem",               yaml_path: %w[update gem],               type: :bool,    default: true,            expose: %i[env config], lifecycle: :next_update),
       Entry.new(key: "update.bundles",           yaml_path: %w[update bundles],           type: :bool,    default: true,            expose: %i[env config], lifecycle: :next_update),
       Entry.new(key: "update.desktop",           yaml_path: %w[update desktop],           type: :bool,    default: true,            expose: %i[env config], lifecycle: :next_update),
+      Entry.new(key: "update.notify",            yaml_path: %w[update notify],            type: :enum,    default: "on",             expose: %i[env config], enum_values: %w[on off], lifecycle: :web_start),
+      Entry.new(key: "update.check_hours",       yaml_path: %w[update check_hours],       type: :integer, default: 24,               expose: %i[env config], lifecycle: :web_start,
+                check: ->(value) { "at least 1" unless value >= 1 }),
+      Entry.new(key: "update.min_age_hours",     yaml_path: %w[update min_age_hours],     type: :integer, default: 24,               expose: %i[env config], lifecycle: :web_start,
+                check: ->(value) { "at least 0" unless value >= 0 }),
       # The desktop helper's kitty targets (Desktop::MacOS.kitty_settings, one of its terminal_settings): listen_on copied from kitty.conf (unset = none),
       # the kitty binary, and the foreground programs listed, "|"-separated (a YAML list works too; "*" = every window).
       Entry.new(key: "kitty.listen_on",          yaml_path: %w[kitty listen_on],          type: :string, default: nil,              expose: %i[env config], lifecycle: :desktop_update),

data/lib/samagotchi/delivery.rb

@@ -58,6 +58,13 @@ module Samagotchi
                   "the owner must restart it (chi sessions restart ID, or the web's update badge)"
     }.freeze
 
+    # A worker that runs a participant's turn in a working session as a pair
+    # turn (ParticipantMode :pair, Guardrails::PairBoundary). One without it
+    # still runs it as a review turn (ReviewBoundary), so chi web and chi
+    # share treat the session as :review (ParticipantMode.live) until it
+    # restarts.
+    PAIR_FEATURE = "pair_turns"
+
     # Whether it is the one every sender defaulting to a step boundary uses.
     def self.next_step?(value) = parse(value) == NEXT_STEP
 

data/lib/samagotchi/engine.rb

@@ -159,6 +159,7 @@ module Samagotchi
       @chat_backend = nil
       @chat_backend_mutex = Mutex.new
       @toolkit_audit_thread = nil
+      @toolkit_warmup_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
@@ -240,7 +241,7 @@ module Samagotchi
       # start: their names for the messages they wrote.
       @participants = SessionParticipants.new(state_dir: -> { session_state_dir })
       # Whether the system prompt carries the participants line.
-      @participants_line = false
+      @participants_line = nil
       # Who is in the review now, and who came or went (#announce_participants).
       @participants_watch = ParticipantsWatch.new(session_id: -> { @session&.id }, state_dir: -> { session_state_dir })
       @session = nil
@@ -381,6 +382,9 @@ module Samagotchi
       @kernel.session_dir = -> { @session&.id && Session.session_dir(@session.id, state_dir: session_state_dir) }
       @kernel.guardrail_gate = @guardrail_wiring.gate
       @kernel.participant_turn = -> { Steer.participant_author?(turn_author) }
+      @kernel.participant_mode = -> { @guardrail_wiring.turn_mode }
+      # A pair turn stops once its participant passed their cap.
+      @kernel.generation_guard = -> { guard_participant_spend }
       # The turn-end warm-up; the kernel asks it for a slot pin per request.
       @prompt_warmup = PromptWarmup.new
       @kernel.warmup = @prompt_warmup
@@ -410,7 +414,10 @@ module Samagotchi
         # from config on every ask, and the running turn's cancel controller
         # closes a judgment that is no longer wanted.
         system_one: -> { SystemOne::Client.from_config(host_registry: @host_registry) },
-        cancel_controller: -> { active_cancel_controller }
+        cancel_controller: -> { active_cancel_controller },
+        # A participant's turn: their name on the owner's card, their
+        # grant's mode for the turn's (GuardrailWiring#turn_mode).
+        participant: ->(author) { @participants.entry_for(author, session: @session) }
       )
     end
     private :build_guardrail_wiring
@@ -1115,6 +1122,8 @@ module Samagotchi
         thread.join([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max)
       end
       @toolkit_audit_thread&.join(TOOLKIT_AUDIT_JOIN_SECONDS)
+      # The warm-up's answer is dropped anyway.
+      stop_toolkit_warmup
       left = threads.count(&:alive?)
       Log.warn(:plugins, "anytime_commands_left", count: left) if left.positive?
       @plugin_tasks.kill_leftovers
@@ -1395,6 +1404,34 @@ module Samagotchi
 
     def session_state_dir = @session_state_dir || Session.default_state_dir
 
+    # Whether a participant's pair turn must stop, read before each of its
+    # generations (#guard_participant_spend): author ("p:<id>") → why (their
+    # link ended, or they passed their cap), nil while it may go on. The
+    # Worker sets it (Worker#participant_turn_stop); without one (the REPL)
+    # nothing is checked mid-turn.
+    attr_writer :participant_stop
+
+    # What a participant turn's stop is attributed to (HookRoutes#stop_turn).
+    PARTICIPANTS_HOOK = "participants"
+
+    # Before each generation (KernelLoop#generation_guard): a pair turn whose
+    # participant's link ended, or whose spend (Engine#metrics: their
+    # finished turns, this one's finished generations, their side requests)
+    # passed their cap, stops on the plugins' stop path (cost-cap's,
+    # work-cap's), with its notice. A generation's own cost is known only
+    # once it ends, so a turn can pass the cap by its last generation. The
+    # turn-start check is the Worker's (Worker#participant_refusal); a
+    # review turn only reads, and keeps to it.
+    def guard_participant_spend
+      author = turn_author
+      return if author.nil? || @participant_stop.nil?
+      return unless @guardrail_wiring.turn_mode == ParticipantMode::PAIR
+
+      reason = @participant_stop.call(author) or return
+      hook_stop_turn(reason, PARTICIPANTS_HOOK)
+    end
+    private :guard_participant_spend
+
     # The running turn's metrics so far, saved as a turn a worker died in
     # would leave them (SessionMetrics#persist's running_turn): a worker's
     # turn checkpoint (TurnCheckpoint) calls it when it writes.
@@ -1500,14 +1537,15 @@ module Samagotchi
       change
     end
 
-    # Reads the session's participants at a turn's start; the first to join
-    # and the last to leave rebuild the system prompt (its participants
-    # line), once each: a turn in between sends the same prefix.
+    # Reads the session's participants at a turn's start; the first to join,
+    # the first invited to act (a pair participant: the line's words) and
+    # the last to leave rebuild the system prompt (its participants line),
+    # once each: a turn in between sends the same prefix.
     def refresh_participants!(session)
-      active = @participants.refresh!(session).active?
-      return if active == @participants_line
+      line = @participants.refresh!(session).prompt_mode(session)
+      return if line == @participants_line
 
-      @participants_line = active
+      @participants_line = line
       @prompt_builder.reset!
     end
     private :refresh_participants!
@@ -1527,8 +1565,9 @@ module Samagotchi
     # 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 } : {}
+    def participant_mode_fields(author)
+      mode = Steer.participant_author?(author) && @guardrail_wiring.turn_mode
+      mode ? { participant_mode: mode.to_s } : {}
     end
 
     # Why a turn stopped (TurnEndings#stop_facts).
@@ -2139,11 +2178,15 @@ module Samagotchi
       turn_started[:cut_after] = steer_cut_after
       # A participant's turn names them (author, author_name) for the UIs'
       # badge; the owner's turn_started stays as it was.
-      turn_started.merge!(author_fields(turn.origin.author, session: session))
+      turn_started.merge!(author_fields(turn.origin.author, session: session),
+                          participant_mode_fields(turn.origin.author))
       emit_event(turn.on_event, turn.tag(turn_started))
       raise image_error if image_error
 
-      start_toolkit_suggestion_audit(turn)
+      # On mode's ask starts here too; the turn joins it before
+      # apply_toolkit! below, so its latency hides behind the probes and
+      # the init wait.
+      toolkit_suggestion = start_toolkit_suggestion(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.
@@ -2159,7 +2202,10 @@ module Samagotchi
       refuse_images!(turn.settings.vision) unless image_refs.empty?
       # A Stop during the probes: the turn ends before the load-failure
       # warnings, which show once, so the next turn still shows them.
-      return false if turn.controller.cancelled?
+      if turn.controller.cancelled?
+        toolkit_suggestion&.abandon(:canceled)
+        return false
+      end
 
       announce_guardrail_failures(turn.on_event)
       # Plugins' slow setup that brings tools (an MCP server's first
@@ -2172,9 +2218,12 @@ module Samagotchi
       # session's toolkit (a /toolkit change since the last turn): what the
       # prompt built next declares, unchanged until the next turn's start.
       apply_staged_tools!
+      # On mode: the suggested kit, before anything is declared (a Stop
+      # during the wait is caught by the check below).
+      settle_toolkit_suggestion(turn, toolkit_suggestion)
       apply_toolkit!(session, turn.on_event)
       refresh_participants!(session)
-      # A Stop during the wait above: the turn ends here,
+      # A Stop during the waits above: the turn ends here,
       # before the hooks run or a reminder is used up.
       return false if turn.controller.cancelled?
 
@@ -2191,6 +2240,10 @@ module Samagotchi
 
       turn_messages(turn, image_refs)
       true
+    ensure
+      # A turn that ended (a failure, an Interrupt) before it settled the
+      # ask: its line says so. Nothing once it was settled.
+      toolkit_suggestion&.abandon(:failed)
     end
     private :prepare_turn
 
@@ -2306,7 +2359,7 @@ module Samagotchi
 
       unless turn.continue
         user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author),
-                         **participant_mode_fields(turn.origin.author, session: session), MessageTime::KEY => turn.at }
+                         **participant_mode_fields(turn.origin.author), MessageTime::KEY => turn.at }
         user_message[:images] = image_refs unless image_refs.empty?
         turn.messages << user_message
         session.last_prompt = turn.prompt
@@ -2729,20 +2782,22 @@ 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)
+    # Start the toolkit classifier after :turn_started, for audit and on
+    # mode alike (one eligibility, one snapshot, one thread). All session
+    # and tool-registry reads happen here; the thread receives only this
+    # snapshot. Audit never blocks: the thread logs its line. On mode
+    # returns the ask's Pending, which the turn joins before apply_toolkit!
+    # (#settle_toolkit_suggestion), with the turn's controller as the
+    # request's cancel controller.
+    # @return [ToolkitSuggest::Pending, nil] nil unless the turn joins an ask
+    def start_toolkit_suggestion(turn)
       mode = Config.get("toolkit.suggest.mode").to_s
       return if mode == "off"
 
+      joined = mode == "on"
       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}")
-                               })
+      log = toolkit_suggestion_log
       # 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
@@ -2769,11 +2824,19 @@ module Samagotchi
       client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
       return unless client
 
-      if toolkit_judge_shares_local_host?(client.host)
+      # D7: on a shared single-slot server audit's free ask would compete
+      # with the turn's prefill, and any ask evicts the session's cached
+      # prefix: on mode asks only on a first turn there (nothing is cached
+      # yet worth keeping), never on the deferred path.
+      if (!joined || ToolkitSuggest.model_reply?(session.messages)) && toolkit_judge_shares_local_host?(client.host)
         Log.info(:toolkit, "toolkit_suggest_shared_host_skipped", session_id: session.id, host: client.host)
         return
       end
 
+      # The warm-up's only value is the cache: the real ask never queues
+      # behind it.
+      stop_toolkit_warmup
+
       # 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).
@@ -2794,16 +2857,124 @@ module Samagotchi
         state: { project: state[:project].dup.freeze, prompt: state[:prompt].dup.freeze }.freeze
       )
       threshold = Config.get("toolkit.suggest.threshold")
+      pending = ToolkitSuggest::Pending.new(log: log, joined: joined,
+                                            timeout_seconds: SystemOne::Client.configured_timeout_ms / 1000.0)
+      # On mode: cut by a Stop while the turn waits (Pending#wait), not
+      # by one after it went on; audit's ask is never cut.
+      controller = joined ? pending.cancel_controller : nil
       @toolkit_audit_thread = Thread.new do
-        ToolkitSuggest.ask(client: client, log: log, snapshot: snapshot, threshold: threshold)
-      rescue StandardError => e
-        ToolkitSuggest.warn(e)
+        judged = nil
+        begin
+          judged = ToolkitSuggest.judge(client: client, snapshot: snapshot, threshold: threshold,
+                                        cancel_controller: controller)
+        rescue LLM::RequestCancelled
+          nil
+        rescue StandardError => e
+          ToolkitSuggest.warn(e)
+        ensure
+          pending.finish(judged)
+        end
+      end
+      joined ? pending : nil
+    rescue StandardError => e
+      ToolkitSuggest.warn(e)
+      nil
+    end
+    private :start_toolkit_suggestion
+
+    # On mode, before apply_toolkit!: wait for the ask (#start_toolkit_
+    # suggestion) up to System 1's timeout from its start, or until a Stop,
+    # and put the session on a candidate picked with confidence ≥ threshold
+    # (ToolkitBinding#suggest: origin suggested, saved, the notice). Any
+    # other outcome (the default, below threshold, undecided, no judgment,
+    # a timeout, a Stop) leaves the session on its default. Nothing here
+    # sends a request; prepare_turn's cancel check ends a stopped turn. A
+    # Stop wins over an answer already in (Pending#wait checks it first).
+    def settle_toolkit_suggestion(turn, pending)
+      return if pending.nil?
+
+      outcome, judged = pending.wait(turn.controller)
+      unless outcome == :answered
+        Log.info(:toolkit, "toolkit_suggest_#{outcome}", session_id: turn.session.id)
+        return
+      end
+      return if judged.nil?
+
+      pending.record(toolkit_suggestion_outcome(turn.session, judged))
+    rescue StandardError => e
+      ToolkitSuggest.warn(e)
+      pending&.record("failed")
+    end
+    private :settle_toolkit_suggestion
+
+    # What the turn does with an answered ask, as the log line's did:
+    # suggested (switched), chosen (the toolkit isn't the default any
+    # more), unavailable (the kit is gone), defer or default.
+    def toolkit_suggestion_outcome(session, judged)
+      case judged.would
+      when "suggested"
+        return "chosen" unless session.toolkit_origin == "default"
+        return "unavailable" unless @toolkit_binding.kits.key?(judged.suggestion.kit)
+
+        switched = @toolkit_binding.suggest(session, judged.suggestion.kit, confidence: judged.suggestion.confidence,
+                                                                            deferred: ToolkitSuggest.model_reply?(session.messages))
+        switched ? "suggested" : "chosen"
+      when "defer" then "defer"
+      else "default"
+      end
+    end
+    private :toolkit_suggestion_outcome
+
+    # On mode, as an idle worker starts (Worker#start_background): one ask
+    # with the real question and a stand-in prompt, on its own thread,
+    # never logged and never waited for, so System 1's server has the
+    # question's prefix cached for the first prompt. Only for a session a
+    # first prompt could be asked for: origin default, no model reply, not
+    # a delegate child or a review session, at least two candidates; and
+    # not when the worker starts on a first prompt (that ask comes at once).
+    def warm_toolkit_suggestion!
+      return unless Config.get("toolkit.suggest.mode").to_s == "on"
+
+      session = @session
+      return if session.nil? || session.toolkit_origin != "default" || session.delegate? || session.review?
+      return if ToolkitSuggest.model_reply?(session.messages) || !session.last_prompt.to_s.strip.empty?
+
+      default = Toolkit.of(session.toolkit)
+      kits = @toolkit_binding.kits
+      return if ToolkitSuggest.candidates(kits, default_name: default.name).size < 2
+
+      client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
+      return unless client
+      # D7: on the model's own single-slot server it would evict the
+      # session's cached prefix for a question that may never come.
+      return if toolkit_judge_shares_local_host?(client.host)
+
+      project = File.basename(session.project_root.to_s)
+      @toolkit_warmup_thread = Thread.new do
+        ToolkitSuggest.warm(client: client, default: default, kits: kits, project: project)
       end
     rescue StandardError => e
       ToolkitSuggest.warn(e)
       nil
     end
-    private :start_toolkit_suggestion_audit
+    public :warm_toolkit_suggestion!
+
+    # A still-running warm-up, stopped: a real ask (or the worker leaving)
+    # doesn't wait behind it.
+    def stop_toolkit_warmup
+      @toolkit_warmup_thread&.kill
+      @toolkit_warmup_thread = nil
+    end
+    private :stop_toolkit_warmup
+
+    def toolkit_suggestion_log
+      path = ToolkitSuggest.log_path(session_state_dir)
+      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}")
+                         })
+    end
+    private :toolkit_suggestion_log
 
     # 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:

data/lib/samagotchi/gem_update.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "open3"
 require "rbconfig"
 require "rubygems/package"
+require "time"
 require_relative "version"
 require_relative "redacted_inspect"
 
@@ -22,12 +23,14 @@ module Samagotchi
     end
 
     LATEST_URL = URI("https://rubygems.org/api/v1/versions/samagotchi/latest.json")
+    RELEASES_URL = URI("https://rubygems.org/api/v1/versions/samagotchi.json")
     # Not SAMAGOTCHI_UPDATE_GEM: that is the env form of config update.gem.
     LOCAL_ENV = "SAMAGOTCHI_UPDATE_GEM_FILE"
     TIMEOUT = 5
 
     # source is what `gem install` takes: the gem's name, or a .gem file.
     Latest = Struct.new(:version, :source, keyword_init: true)
+    Release = Data.define(:version, :created_at, :prerelease)
 
     # Runs a command without a shell; [output, success].
     class Runner
@@ -57,7 +60,7 @@ module Samagotchi
       local = @env[LOCAL_ENV].to_s
       return Latest.new(version: Gem::Package.new(local).spec.version.to_s, source: local) unless local.empty?
 
-      version = JSON.parse(@fetcher.call.to_s)["version"].to_s
+      version = JSON.parse(fetch_body(LATEST_URL).to_s)["version"].to_s
       raise Error, "rubygems.org answered without a version" if version.empty? || !Gem::Version.correct?(version)
 
       Latest.new(version: version, source: "samagotchi")
@@ -67,6 +70,29 @@ module Samagotchi
       raise Error, "#{e.class}: #{e.message}".lines.first.strip
     end
 
+    # @return [Array<Release>] rubygems releases, or the one local smoke gem
+    def releases
+      local = @env[LOCAL_ENV].to_s
+      return [local_release(local)] unless local.empty?
+
+      records = JSON.parse(fetch_body(RELEASES_URL).to_s)
+      raise Error, "rubygems.org answered without a releases list" unless records.is_a?(Array)
+
+      records.map do |record|
+        version = record["number"].to_s
+        created_at = record["created_at"].to_s
+        unless Gem::Version.correct?(version) && !created_at.empty? && [true, false].include?(record["prerelease"])
+          raise Error, "rubygems.org answered with an invalid release"
+        end
+
+        Release.new(version: version, created_at: Time.iso8601(created_at), prerelease: record["prerelease"])
+      end
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "#{e.class}: #{e.message}".lines.first.strip
+    end
+
     def newer?(latest, current = VERSION)
       Gem::Version.new(latest.version) > Gem::Version.new(current)
     end
@@ -83,9 +109,20 @@ module Samagotchi
 
     private
 
-    def fetch
-      Net::HTTP.start(LATEST_URL.host, LATEST_URL.port, use_ssl: true, open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
-        request = Net::HTTP::Get.new(LATEST_URL)
+    def local_release(path)
+      version = Gem::Package.new(path).spec.version
+      Release.new(version: version.to_s, created_at: File.mtime(path), prerelease: version.prerelease?)
+    end
+
+    def fetch_body(url)
+      return @fetcher.call if @fetcher.arity.zero?
+
+      @fetcher.call(url)
+    end
+
+    def fetch(url = LATEST_URL)
+      Net::HTTP.start(url.host, url.port, use_ssl: true, open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+        request = Net::HTTP::Get.new(url)
         request["User-Agent"] = USER_AGENT
         response = http.request(request)
         raise Error, "rubygems.org answered #{response.code}" unless response.code == "200"