samagotchi 0.122.0 → 0.124.0

data/lib/samagotchi/desktop/macos/Sessions.swift

@@ -0,0 +1,272 @@
+// The panel's chi side without the panel: what a send to chi sessions runs
+// (SendPlan, built from the panel's state, run by PanelController), and the
+// build spec's seams: `ChiHelper --sessions` prints the session rows the
+// panel lists, `ChiHelper --send-plan` the chi calls a send would make.
+import Foundation
+
+/// A send to chi sessions as the chi calls it makes: `chi send` (a message,
+/// or `--new` on a new row, this Mac's or a remote's) or `chi note`, one per
+/// machine. Pure: nothing runs here.
+struct SendPlan {
+  /// One chi call: its args after the launch file's argv, its stdin, its
+  /// name in the panel's lines ("chi send"), the remote it goes to and its
+  /// time limit.
+  struct Call: Equatable {
+    let command: String
+    let args: [String]
+    let stdin: Data?
+    var remote: String?
+    var timeout: TimeInterval = 10
+  }
+
+  /// A session on a machine: nil is this Mac.
+  struct Target: Equatable {
+    let remote: String?
+    let id: String
+  }
+
+  let kind: SendKind
+  /// UUID-shaped session ids and their machines, in list order; not used
+  /// with +new+.
+  let targets: [Target]
+  let new: Bool
+  /// The remote a new session starts on; nil: this Mac.
+  let newRemote: String?
+  /// Where a new session starts (PanelModel.newSessionDir, or
+  /// newSessionDir(remote:) on a remote); nil: nowhere known, no call.
+  let newDir: String?
+  /// `--model` for `chi send --new` on this Mac, verbatim; nil for the
+  /// default. Never on a remote (D4: the list is this Mac's).
+  let model: String?
+  /// The message line, trimmed; `-m` of `chi send`.
+  let prompt: String
+  /// A message's stdin: the quoted context; nil when there is none.
+  let context: String?
+  /// `chi note`'s stdin: the message line, then the context.
+  let note: String
+  /// `chi note --source`, trimmed; "" for none.
+  let source: String
+  /// `--image` paths; a note's are dropped before (text only).
+  let images: [String]
+
+  /// The panel's state for this send.
+  static func from(_ model: PanelModel, kind: SendKind, sessions: [LiveSession], new: Bool, images: [PanelImage]) -> SendPlan {
+    let newRemote = new ? model.newRemote : nil
+    let newDir = newRemote.map(model.newSessionDir(remote:)) ?? model.newSessionDir
+    return SendPlan(kind: kind, targets: sessions.map { Target(remote: $0.remote, id: $0.id) }, new: new, newRemote: newRemote,
+             newDir: newDir, model: newRemote == nil ? model.modelForSend : nil,
+             prompt: model.trimmedPrompt, context: model.hasContext ? model.text : nil, note: model.noteText,
+             source: model.source.trimmingCharacters(in: .whitespacesAndNewlines), images: images.map(\.url.path))
+  }
+
+  /// This Mac's call first, then one per remote in list order. A session
+  /// goes once, to the first machine it is under; a remote whose name chi
+  /// wouldn't take is left out (the listing never makes one).
+  var calls: [Call] {
+    if new {
+      guard newDir != nil, newRemote.map(Remotes.valid) ?? true else { return [] }
+      return [call(ids: [], remote: newRemote)]
+    }
+    var machines: [String?] = []
+    var ids: [String?: [String]] = [:]
+    var seen = Set<String>()
+    let ordered = targets.filter { $0.remote == nil } + targets.filter { $0.remote != nil }
+    for target in ordered where target.remote.map(Remotes.valid) ?? true && seen.insert(target.id).inserted {
+      if ids[target.remote] == nil { machines.append(target.remote) }
+      ids[target.remote, default: []].append(target.id)
+    }
+    return machines.map { call(ids: ids[$0] ?? [], remote: $0) }
+  }
+
+  /// Reading, converting and a new worker's start take longer than text;
+  /// a remote's text, waking a stopped worker there, too.
+  private func call(ids: [String], remote: String?) -> Call {
+    var args: [String]
+    let command: String
+    let stdin: Data?
+    switch kind {
+    case .message, .paste:
+      // stdin is the quoted context; without -m, chi takes it as the message.
+      command = "chi send"
+      args = new ? ["send", "--new", "--dir", newDir ?? ""] : ["send"]
+      // The row's name verbatim; none for the default, nor on a remote.
+      if new, remote == nil, let model { args += ["--model", model] }
+      if !prompt.isEmpty { args += ["-m", prompt] }
+      args += images.flatMap { ["--image", $0] }
+      stdin = context.map { Data($0.utf8) }
+    case .note:
+      command = "chi note"
+      args = ["note"]
+      if !source.isEmpty { args += ["--source", source] }
+      stdin = Data(note.utf8)
+    }
+    if !new { args += ids }
+    if let remote { args = ["--remote", remote] + args }
+    let timeout: TimeInterval = !images.isEmpty && kind != .note ? 30 : remote == nil ? 10 : 15
+    return Call(command: command, args: args, stdin: stdin, remote: remote, timeout: timeout)
+  }
+}
+
+private func printJSON(_ object: Any) {
+  let data = try! JSONSerialization.data(withJSONObject: object, options: [.sortedKeys])
+  print(String(decoding: data, as: UTF8.self))
+}
+
+/// `ChiHelper --sessions [--launch PATH] [--last KEY]... [--order
+/// local-first|remotes-first] [--click KEY]...`: the panel's session rows in
+/// its order (live, then recent), the new row's folder, a section per remote
+/// (rows not listed before, or its line, and its new row's folder) and what
+/// the panel preselects with KEYs as the remembered choice (none by default:
+/// never the user's) when the answers come in that order (this Mac's first
+/// by default), then after the clicks (a row's key, "new", "new:REMOTE" for
+/// a remote's new row, "model" for ⌘M), as JSON ({"rows": [{"id", "desc",
+/// "cwd", "busy", "recent"}], "new_dir", "remotes": [{"name", "rows" (each
+/// with "remote"), "error", "new_dir" (null: no new row)}], "selected",
+/// "new_selected", "new_remote", "picker_open", "message", "hint"}); a
+/// failed listing of this Mac's is its message on stderr, exit 1.
+func sessionsCommand(_ args: [String]) -> Int32 {
+  var args = args
+  var launchPath = ChiRunner.launchPath
+  var last: [String] = []
+  var remotesFirst = false
+  var clicks: [String] = []
+  let usage = "usage: ChiHelper --sessions [--launch PATH] [--last KEY]... [--order local-first|remotes-first] [--click KEY]...\n"
+  while !args.isEmpty {
+    let arg = args.removeFirst()
+    switch arg {
+    case "--launch" where !args.isEmpty: launchPath = args.removeFirst()
+    case "--last" where !args.isEmpty: last.append(args.removeFirst())
+    case "--click" where !args.isEmpty: clicks.append(args.removeFirst())
+    case "--order" where !args.isEmpty:
+      let order = args.removeFirst()
+      guard ["local-first", "remotes-first"].contains(order) else {
+        FileHandle.standardError.write(usage.data(using: .utf8)!)
+        return 2
+      }
+      remotesFirst = order == "remotes-first"
+    default:
+      FileHandle.standardError.write(usage.data(using: .utf8)!)
+      return 2
+    }
+  }
+  let runner = ChiRunner(launchPath: launchPath)
+  // As the panel: this Mac's lists beside `remote ls`, then each remote's
+  // at once. All are awaited, then fed to the panel's model in the order
+  // --order says (the panel takes them as they come).
+  let queue = DispatchQueue(label: "sessions-command")
+  let group = DispatchGroup()
+  var local: Result<[LiveSession], ChiError>?
+  var names: [String] = []
+  var answers: [String: Result<[LiveSession], ChiError>] = [:]
+  group.enter()
+  runner.sessions(queue: queue) { local = $0; group.leave() }
+  group.enter()
+  runner.remotes(queue: queue) { found in
+    names = found
+    for name in found {
+      group.enter()
+      runner.sessions(remote: name, queue: queue) { answers[name] = $0; group.leave() }
+    }
+    group.leave()
+  }
+  group.wait()
+  let model = PanelModel()
+  model.lastChoice = last
+  model.startRemotes(names)
+  let showRemotes = { for name in names { model.showRemote(name, answers[name]!) } }
+  if remotesFirst { showRemotes() }
+  model.showSessions(local!)
+  if !remotesFirst { showRemotes() }
+  for key in clicks {
+    switch key {
+    case "new": model.toggleNew()
+    case "model": _ = model.pressModel()
+    case let key where key.hasPrefix("new:"): model.toggleNew(remote: String(key.dropFirst(4)))
+    default: model.toggle(key)
+    }
+  }
+  switch local! {
+  case .failure(let error):
+    FileHandle.standardError.write("\(error.description)\n".data(using: .utf8)!)
+    return 1
+  case .success:
+    let row = { (s: LiveSession) -> [String: Any] in
+      var row: [String: Any] = ["id": s.id, "desc": s.desc ?? NSNull(), "cwd": s.cwd ?? NSNull(), "busy": s.busy ?? NSNull(),
+                                "recent": s.recent]
+      if let remote = s.remote { row["remote"] = remote }
+      return row
+    }
+    let remotes: [[String: Any]] = model.remoteGroups.map { group in
+      ["name": group.section.name, "rows": group.rows.map(row), "error": group.section.error ?? NSNull(),
+       "new_dir": model.newSessionDir(remote: group.section.name) ?? NSNull()]
+    }
+    printJSON(["rows": model.sessions.map(row), "new_dir": model.newSessionDir, "remotes": remotes,
+               "selected": model.selected.sorted(), "new_selected": model.newSelected, "new_remote": model.newRemote ?? NSNull(),
+               "picker_open": model.pickerOpen, "message": model.message, "hint": model.machineHint])
+    return 0
+  }
+}
+
+/// `ChiHelper --send-plan message|note|paste [--id [REMOTE:]ID]... [--new [REMOTE:]DIR]
+/// [--default MODEL] [--model MODEL] [--prompt P] [--source S] [--image PATH]...`:
+/// the panel's text on stdin; prints the calls SendPlan makes as JSON
+/// ([{"command", "args", "stdin", "timeout"}], stdin null when none). An id
+/// as a row's key: "studio:<id>" on a remote. --new is the new row, DIR the
+/// folder of its only (live) session; with REMOTE: (DIR absolute), that
+/// remote's new row; --default is the configured model, --model the pick.
+func sendPlanCommand(_ args: [String]) -> Int32 {
+  let usage = "usage: ChiHelper --send-plan message|note|paste [--id [REMOTE:]ID]... [--new [REMOTE:]DIR] [--default MODEL] "
+    + "[--model MODEL] "
+    + "[--prompt P] [--source S] [--image PATH]...\n"
+  var args = args
+  let kinds: [String: SendKind] = ["message": .message, "note": .note, "paste": .paste]
+  guard let first = args.first, let kind = kinds[first] else {
+    FileHandle.standardError.write(usage.data(using: .utf8)!)
+    return 2
+  }
+  args.removeFirst()
+  let model = PanelModel()
+  var sessions: [LiveSession] = [], newDir: String?, images: [PanelImage] = []
+  while !args.isEmpty {
+    let arg = args.removeFirst()
+    guard !args.isEmpty else { FileHandle.standardError.write(usage.data(using: .utf8)!); return 2 }
+    let value = args.removeFirst()
+    switch arg {
+    case "--id":
+      // A UUID has no ":", so the last one splits off the remote.
+      let colon = value.lastIndex(of: ":")
+      var session = LiveSession(id: colon.map { String(value[value.index(after: $0)...]) } ?? value, desc: nil, cwd: nil,
+                                busy: nil, owner: nil, updatedAt: nil)
+      session.remote = colon.map { String(value[..<$0]) }
+      sessions.append(session)
+    case "--new" where value.hasPrefix("/"): newDir = value
+    case "--new":
+      guard let colon = value.firstIndex(of: ":") else { FileHandle.standardError.write(usage.data(using: .utf8)!); return 2 }
+      let name = String(value[..<colon])
+      var session = LiveSession(id: UUID().uuidString, desc: nil, cwd: String(value[value.index(after: colon)...]), busy: nil,
+                                owner: nil, updatedAt: nil)
+      session.remote = name
+      model.startRemotes([name])
+      model.showRemote(name, .success([session]))
+      model.newRemote = name
+    case "--default": model.newModel = value
+    case "--model": model.pickedModel = value
+    case "--prompt": model.prompt = value
+    case "--source": model.source = value
+    case "--image": images.append(PanelImage(url: URL(fileURLWithPath: value), temp: false))
+    default:
+      FileHandle.standardError.write(usage.data(using: .utf8)!)
+      return 2
+    }
+  }
+  model.text = String(decoding: FileHandle.standardInput.readDataToEndOfFile(), as: UTF8.self)
+  if let newDir {
+    model.sessions = [LiveSession(id: UUID().uuidString, desc: nil, cwd: newDir, busy: nil, owner: nil, updatedAt: nil)]
+  }
+  let plan = SendPlan.from(model, kind: kind, sessions: sessions, new: newDir != nil || model.newRemote != nil, images: images)
+  printJSON(plan.calls.map { call -> [String: Any] in
+    ["command": call.command, "args": call.args, "timeout": call.timeout,
+     "stdin": call.stdin.map { String(decoding: $0, as: UTF8.self) } ?? NSNull()]
+  })
+  return 0
+}

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: