samagotchi 0.121.0 → 0.122.0

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

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

data/lib/samagotchi/run_options.rb

@@ -165,6 +165,8 @@ 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 toolkit report [--days N]   grade toolkit suggestions against the tools sessions used
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME

data/lib/samagotchi/session.rb

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

data/lib/samagotchi/session_access/contract.rb

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

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

data/lib/samagotchi/session_access/web_bridge_client.rb

@@ -6,6 +6,7 @@ require_relative "../session_access"
 require_relative "../bridge_client"
 require_relative "../delivery"
 require_relative "../log"
+require_relative "../worker_link"
 require_relative "http_transport"
 
 module Samagotchi
@@ -39,9 +40,6 @@ module Samagotchi
       # A read a join waits on (a turn's saved records, the children
       # counts): a slow chi web can't hold the join up for long (L9).
       JOIN_READ_TIMEOUT = 5
-      # chi web answers no live worker for the session (Mapping).
-      NO_WORKER = "no live worker for session %s on %s"
-
       # chi web's answers as the session's Bridge would have given them.
       module Mapping
         module_function
@@ -60,7 +58,7 @@ module Samagotchi
         def response(route, reply, session_id:, remote:)
           json = reply.json.is_a?(Hash) ? reply.json : {}
           case [reply.status, json["error"]]
-          in [503, "not_live"] | [404, "not_found"] then raise Unreachable, format(NO_WORKER, session_id, remote)
+          in [503, "not_live"] | [404, "not_found"] then raise Unreachable, "#{WorkerLink.not_live(session_id)} on #{remote}"
           in [504, _] then bridge(408, error: "deadline_passed", detail: json["detail"])
           in [501, _] if route == :command && json["command"]
             bridge(400, error: "unknown_command", detail: json["detail"], command: json["command"])
@@ -69,6 +67,15 @@ module Samagotchi
           end
         end
 
+        def stream(sock, status, headers, session_id:, remote:)
+          outcome = BridgeClient::StreamOpen.classify(sock, status, headers)
+          return outcome unless status.to_i == 503 && outcome.is_a?(BridgeClient::StreamOpen::Unreachable)
+
+          expected = [WorkerLink.unanswered(session_id), WorkerLink.not_live(session_id)]
+          detail = expected.include?(outcome.detail) ? outcome.detail : WorkerLink.not_live(session_id)
+          BridgeClient::StreamOpen::Unreachable.new(attempts: outcome.attempts, detail: "#{detail} on #{remote}")
+        end
+
         def bridge(status, **body) = BridgeClient::Response.new(status: status, body: JSON.generate(body.compact))
       end
 
@@ -198,24 +205,35 @@ module Samagotchi
                                             idle_timeout: STREAM_IDLE_TIMEOUT, &on_event).start
       end
 
-      # GET /api/sessions/:id/stream through StreamRequest, with the token
-      # as Bearer. A chunked response (a proxy in between: no decoding in
-      # v1) and an https chi web (no TLS on the stream yet) are logged and
-      # read as unreachable.
-      # @return [Array(TCPSocket, Integer, Hash), nil] see StreamRequest.open
-      def connect_stream(query: "", last_event_id: nil, timeout: nil)
+      # GET /api/sessions/:id/stream through StreamRequest, classifying chi
+      # web's stream answers as Bridge outcomes.
+      # @param header_timeout [Float] see BridgeClient::STREAM_HEADER_TIMEOUT
+      # @yield [sock] called after response headers arrive, before classifying a
+      #   refusal; EventStream uses it to publish the socket for #close
+      # @return [BridgeClient::StreamOpen::Opened, BridgeClient::StreamOpen::Refused,
+      #   BridgeClient::StreamOpen::Unreachable]
+      def open_stream(query: "", last_event_id: nil, header_timeout: BridgeClient::STREAM_HEADER_TIMEOUT, attempts: 1)
         uri = URI(@remote.entry.url)
         return refused("tls_unsupported") if uri.scheme == "https"
 
         token = @remote.entry.token
-        opened = BridgeClient::StreamRequest.open(host: uri.hostname, port: uri.port,
-                                                  path: "/api/sessions/#{@session_id}/stream#{query}",
-                                                  last_event_id: last_event_id, timeout: timeout,
-                                                  headers: token ? { "Authorization" => "Bearer #{token}" } : {})
-        return opened unless opened && opened[2]["transfer-encoding"].to_s.downcase.include?("chunked")
+        connection = BridgeClient::StreamRequest.open(host: uri.hostname, port: uri.port,
+                                                      path: "/api/sessions/#{@session_id}/stream#{query}",
+                                                      last_event_id: last_event_id, timeout: header_timeout,
+                                                      headers: token ? { "Authorization" => "Bearer #{token}" } : {})
+        return BridgeClient::StreamOpen::Unreachable.new(attempts: 1) unless connection
+
+        sock, status, headers = connection
+        unless !block_given? || yield(sock)
+          sock.close rescue nil
+          return BridgeClient::StreamOpen::Unreachable.new(attempts: 1)
+        end
+        return refused("chunked_unsupported", sock) if headers["transfer-encoding"].to_s.downcase.include?("chunked")
 
-        opened[0].close rescue nil
-        refused("chunked_unsupported")
+        Mapping.stream(sock, status, headers, session_id: @session_id, remote: @remote.name)
+      rescue SystemCallError, SocketError, IOError
+        sock&.close rescue nil
+        BridgeClient::StreamOpen::Unreachable.new(attempts: 1)
       end
 
       private
@@ -234,9 +252,10 @@ module Samagotchi
         raise Unreachable, e.message
       end
 
-      def refused(reason)
+      def refused(reason, sock = nil)
+        sock&.close rescue nil
         Log.warn(:attached, "stream_refused", reason: reason, remote: @remote.name)
-        nil
+        BridgeClient::StreamOpen::Unreachable.new(attempts: 1)
       end
     end
   end

data/lib/samagotchi/session_access.rb

@@ -179,15 +179,27 @@ module Samagotchi
     end
 
     # A session's worker as an attach finds it (Local#worker, chi web's GET
-    # …/worker): +sidecar+ the live worker's WorkerSidecar (port, version,
-    # features, epoch; nil: none runs), +stopped+ its stop marker, +owner+
-    # its OwnerLock::Owner (a worker, a chi REPL, nil).
-    WorkerState = Data.define(:sidecar, :stopped, :owner) do
-      def live? = !sidecar.nil?
-
-      # No Bridge, and the owner is a worker leaving (writing its recap on
-      # leave): a wake waits for it (Local#wake).
-      def leaving? = !live? && !!owner&.leaving?
+    # …/worker): +link+ the one WorkerLink outcome every field reads, +stopped+
+    # its stop marker.
+    WorkerState = Data.define(:link, :stopped) do
+      # @return [WorkerSidecar, nil] the live worker's (port, version,
+      #   features, epoch; nil: none answers)
+      def sidecar = link.live? ? link.sidecar : nil
+
+      # @return [OwnerLock::Owner, nil] a worker, a chi REPL, nil
+      def owner = link.owner
+
+      def live? = link.live?
+
+      # The owner is a worker leaving (writing its recap on leave): a wake
+      # waits for it (Local#wake).
+      def leaving? = link.is_a?(WorkerLink::Leaving)
+
+      # A worker holds the lock past WorkerLink::START_LIMIT with no Bridge.
+      def stuck? = link.is_a?(WorkerLink::Starting) && link.stuck
+
+      # A worker whose sidecar speaks a newer protocol than this chi.
+      def skew? = link.is_a?(WorkerLink::Skew)
     end
 
     # What a wake for an attach did (Local#wake, chi web's POST …/wake):

data/lib/samagotchi/session_continue.rb

@@ -9,6 +9,7 @@ require_relative "child_move"
 require_relative "archive_store"
 require_relative "recap_store"
 require_relative "bridge_client"
+require_relative "worker_link"
 require_relative "model_profile"
 require_relative "log"
 require_relative "session_manager"
@@ -303,10 +304,8 @@ module Samagotchi
     # answers at once. Best effort: the continue goes on without. A review
     # fork (ReviewStart) asks the same, with nothing archived after.
     def self.recap_before_archive(id, state_dir, wait:)
-      return unless SessionManager.worker_live?(id, state_dir: state_dir)
-
       dir = Session.session_dir(id, state_dir: state_dir)
-      client = BridgeClient.discover(id, session_dir: dir) or return
+      client = WorkerLink.client(id, session_dir: dir) or return
       before = RecapStore.read(dir)
       reply = client.request_recap
       asked = reply.status == 200 && reply.json.is_a?(Hash) ? reply.json["request"] : nil