samagotchi 0.120.0 → 0.121.1

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/kernel_loop.rb

@@ -176,6 +176,11 @@ module Samagotchi
     # The Guardrails::Gate ToolRunner asks before each call; the Engine sets
     # it (nil: ToolRunner's own, hooks only).
     attr_accessor :guardrail_gate
+    # Whether the current turn belongs to a participant, so pre-gate
+    # refusals can defer to ReviewBoundary.
+    attr_accessor :participant_turn
+
+    def participant_turn? = @participant_turn&.call == true
     # @return [LLM::TurnSettings] the turn's vision, sampling, thinking and
     #   model name, set by the Engine per turn (#run sets the model name
     #   too); the thinking level is its own field, since the native path

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/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/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]
@@ -308,16 +311,18 @@ module Samagotchi
       # toolkit.default, ctx.use_toolkit): +base+'s tools (a toolkit chi or
       # 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). A
+      #   its base's, "" none; at most Toolkit::PROMPT_MAX characters);
+      #   +groups+: MCP source group names/globs (nil inherits its base).
+      #   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)
+      def toolkit(name, base:, add: [], remove: [], prompt: nil, groups: 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.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)
@@ -327,7 +332,8 @@ module Samagotchi
         end
         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, source: @bundle)
+        @toolkits << Toolkit::Kit.new(name: name, base: base, add: add, remove: remove, prompt: prompt,
+                                      groups: groups, source: @bundle)
         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/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)

data/lib/samagotchi/relay_verifier.rb

@@ -2,8 +2,7 @@
 
 require_relative "client_id"
 require_relative "session"
-require_relative "bridge_client"
-require_relative "worker_sidecar"
+require_relative "worker_link"
 require_relative "question_desk"
 require_relative "log"
 
@@ -87,7 +86,7 @@ module Samagotchi
     # @return [Hash, nil] what the parent's live Bridge says about the relay
     def parent_relay(parent_id, relay_id)
       dir = Session.session_dir(parent_id, state_dir: @state_dir)
-      client = BridgeClient.discover(parent_id, session_dir: dir) or return nil
+      client = WorkerLink.client(parent_id, session_dir: dir) or return nil
       response = client.relay_status(relay_id)
       response.ok? ? response.json : nil
     rescue SystemCallError, IOError

data/lib/samagotchi/relay_watcher.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "worker_sidecar"
+require_relative "worker_link"
 require_relative "log"
 
 module Samagotchi
@@ -20,7 +20,7 @@ module Samagotchi
     # @param live [#call] whether the parent's worker is up
     # @return [Thread]
     def start(engine:, question_id:, relay_id:, parent_dir:, interval: INTERVAL,
-              live: -> { WorkerSidecar.live(parent_dir, unlink: false) })
+              live: -> { WorkerLink.resolve(parent_dir, unlink: false).live? })
       Thread.new do
         loop do
           sleep(interval)

data/lib/samagotchi/remote_attach_command.rb

@@ -48,7 +48,7 @@ module Samagotchi
       ignored(id) if existing
       launch(id, existing: existing)
     rescue TerminalUI::AttachLauncher::Error, SessionAccess::RemoteFailed, SessionAccess::Refused,
-           SessionManager::OwnedByTUI, ModelProfile::MissingModel, ArgumentError => e
+           SessionManager::OwnedByTUI, ModelProfile::MissingModel, Toolkit::Refused, ArgumentError => e
       e.is_a?(SessionAccess::BadRequest) ? usage(e.message) : failed(e.message)
     rescue Interrupt
       CLI::Exit::INTERRUPTED

data/lib/samagotchi/reply_wait/poll.rb

@@ -5,6 +5,7 @@ require_relative "../session_inbox"
 require_relative "../turn_checkpoint"
 require_relative "../continue_offer"
 require_relative "../steer"
+require_relative "../worker_link"
 
 module Samagotchi
   module ReplyWait
@@ -164,11 +165,16 @@ module Samagotchi
         pending = session.pending_question
         return nil unless pending && !@baseline&.question?(pending.id) &&
                           (@turn.nil? || ReplyWait.own_question?(session, @turn, @claimed)) &&
-                          session.waiting_question(live: SessionManager.worker_live?(@id, state_dir: @state_dir))
+                          session.waiting_question(live: worker_owned?)
 
         Result.new(status: :waiting_for_answer, question: pending, session: session)
       end
 
+      # A worker holds the session's lock (a chi REPL's question is its own).
+      def worker_owned?
+        WorkerLink.resolve(Session.session_dir(@id, state_dir: @state_dir), unlink: false).worker_owned?
+      end
+
       # A participant's turn its worker holds while the owner's Continue
       # offer stands (Worker#run_input_files): it waits for the owner's
       # answer to that question, whenever it was asked (the baseline's
@@ -176,7 +182,7 @@ module Samagotchi
       def held(session)
         pending = session.pending_question
         return nil unless @participant_input && !@claimed && pending&.kind.to_s == ContinueOffer::KIND &&
-                          session.waiting_question(live: SessionManager.worker_live?(@id, state_dir: @state_dir))
+                          session.waiting_question(live: worker_owned?)
 
         Result.new(status: :waiting_for_answer, question: pending, session: session)
       end

data/lib/samagotchi/reply_wait.rb

@@ -4,7 +4,7 @@ require_relative "session"
 require_relative "turn_note"
 require_relative "session_inbox"
 require_relative "turn_checkpoint"
-require_relative "worker_sidecar"
+require_relative "worker_link"
 require_relative "reply_wait/poll"
 
 module Samagotchi
@@ -214,9 +214,10 @@ module Samagotchi
       running || queued || ended
     end
 
-    # Whether the session's worker sidecar names TURN_IDS_FEATURE.
+    # Whether the session's live worker names TURN_IDS_FEATURE.
     def turn_ids?(session_dir)
-      WorkerSidecar.read(session_dir)&.features&.include?(TURN_IDS_FEATURE) || false
+      link = WorkerLink.resolve(session_dir, unlink: false)
+      link.live? && link.features.include?(TURN_IDS_FEATURE)
     end
 
     # A pending question is a turn: wait's (its enqueued_id) only when that

data/lib/samagotchi/review_command.rb

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

data/lib/samagotchi/run_options.rb

@@ -165,6 +165,7 @@ module Samagotchi
                  chi review FILE... [--dir DIR] | --from ID   a review session to share (chi share)
                  chi memory <ls|rm> [--scope project|system]   the memories; rm moves one to the bundle trash
                  chi bundle <install|upgrade|uninstall|status|diff|list|build|trash|new|test|check|try>
+                 chi guardrails replay [--dry-run] [--threshold T] [--model M]   seed System 1's record from answered approvals
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME

data/lib/samagotchi/session.rb

@@ -427,10 +427,14 @@ module Samagotchi
     #   seed); [] by default
     # @param setup [SessionSetup] the session's own settings (none by default)
     # @param now [Time] its created_at and updated_at (a spec's clock)
+    # @raise [Toolkit::Refused] its toolkit (setup's, else the configured
+    #   one SessionManager.spawn_session gives it) builds on a config kit
+    #   with an invalid groups: (Toolkit.check_new!)
     def self.new_session(mode:, model_name:, working_directory:, test_run: nil,
                          preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, messages: [],
                          scratch: false, model_typed: nil, delegate: false, setup: SessionSetup.new, continues: nil,
                          review: nil, now: Time.now)
+      Toolkit.check_new!(setup.toolkit || Toolkit.configured(delegate: delegate))
       now = now.iso8601(3)
       resolved_test = if test_run.nil?
                         test_session_env?

data/lib/samagotchi/session_access/local.rb

@@ -14,6 +14,7 @@ require_relative "../context_sources"
 require_relative "../send_command/busy"
 require_relative "../chi_invocation"
 require_relative "../worker_sidecar"
+require_relative "../worker_link"
 require_relative "../review_start"
 require_relative "../launch_mode"
 require_relative "../participants"
@@ -95,13 +96,22 @@ module Samagotchi
         session = show(id)
         raise Refused.new(LaunchMode::SCRATCH_LEFTOVER, code: "scratch") if session.scratch
 
-        live = WorkerSidecar.live(session_dir(id), unlink: true)
-        return Woken.new(woke: false, sidecar: live) if live
+        link = WorkerLink.resolve(session_dir(id), unlink: true)
+        case link
+        when WorkerLink::Live then return Woken.new(woke: false, sidecar: link.sidecar)
+        when WorkerLink::Skew then raise Refused.new(link.message(id), code: "worker_newer")
+        when WorkerLink::Starting
+          # A worker that never publishes its Bridge (a failed start, a
+          # crash's teardown) lets go of the lock: then resume, not 504.
+          found = WorkerLink.await(id, session_dir: session_dir(id), timeout: wait,
+                                       give_up: ->(link) { !link.worker_owned? })
+          return Woken.new(woke: false, sidecar: found.live? ? found.sidecar : nil) if found.worker_owned?
+        end
 
         OwnerLock.await_release(session_dir(id))
         SessionManager.resume_session(id, **dir)
-        found = BridgeClient.wait_for(id, session_dir: session_dir(id), timeout: wait)
-        Woken.new(woke: true, sidecar: found && WorkerSidecar.read(session_dir(id)))
+        found = WorkerLink.await(id, session_dir: session_dir(id), timeout: wait)
+        Woken.new(woke: true, sidecar: found.live? ? found.sidecar : nil)
       end
 
       # The session's worker now, never started (chi web's GET …/worker).
@@ -109,8 +119,8 @@ module Samagotchi
       # @raise [ArgumentError] no such session
       def worker(id)
         show(id)
-        WorkerState.new(sidecar: WorkerSidecar.live(session_dir(id), unlink: true),
-                        stopped: Session.stopped_marker?(id, state_dir: state_dir!), owner: owner(id))
+        WorkerState.new(link: WorkerLink.resolve(session_dir(id), unlink: true),
+                        stopped: Session.stopped_marker?(id, state_dir: state_dir!))
       end
 
       # --- create and send
@@ -148,7 +158,7 @@ module Samagotchi
       # Whether a just-created session's worker came up (its Bridge
       # answers) within +timeout+ seconds.
       def await_worker(id, timeout:)
-        BridgeClient.wait_for(id, session_dir: session_dir(id), timeout: timeout)
+        WorkerLink.await(id, session_dir: session_dir(id), timeout: timeout).live?
       end
 
       # Copies of +refs+ (ImageStore refs stored in +from+) in the
@@ -479,7 +489,7 @@ module Samagotchi
       # The block's post to the session's live worker, again on a 408 (the
       # worker didn't take it in time).
       def on_worker(id)
-        client = BridgeClient.discover(id, session_dir: session_dir(id)) or return nil
+        client = WorkerLink.client(id, session_dir: session_dir(id)) or return nil
         reply = nil
         2.times do
           reply = yield client

data/lib/samagotchi/session_access/remote.rb

@@ -12,6 +12,7 @@ require_relative "../bridge_client"
 require_relative "../session_continue"
 require_relative "../guardrails/parent_policy"
 require_relative "../model_profile"
+require_relative "../web/grants"
 require_relative "http_transport"
 require_relative "../chi_invocation"
 
@@ -679,6 +680,10 @@ module Samagotchi
         # No model configured there, or --model's host unknown there: what
         # spawn_session raises here (chi send: could not start a session).
         when "invalid_model" then raise ModelProfile::MissingModel, message.to_s
+        # A toolkit whose config kit's groups: is invalid there: the same.
+        when "toolkit_refused" then raise Toolkit::Refused, message.to_s
+        # The grants store doesn't read there: chi share says what it says here.
+        when "grants_unwritable" then raise Web::Grants::Unwritable, message.to_s
         when /\Ainvalid_/, "missing_fields", "bad_images"
           # invalid_participant: chi share's name, kind or ttl, an archived session
           raise BadRequest.new(message.to_s, code: error)