samagotchi 0.6.0 → 0.8.0

data/lib/samagotchi/bootstrap/config_writer.rb

@@ -4,6 +4,7 @@ require "json"
 require "yaml"
 require "fileutils"
 require "ipaddr"
+require_relative "../atomic_file"
 require_relative "../config"
 
 module Samagotchi
@@ -328,13 +329,10 @@ module Samagotchi
         candidate
       end
 
+      # The target's mode is kept (a fresh file's when it is new).
       def atomic_write(target, text)
-        tmp = "#{target}.tmp-#{Process.pid}"
-        File.binwrite(tmp, text)
-        File.chmod(File.stat(target).mode & 0o7777, tmp) if File.exist?(target)
-        File.rename(tmp, target)
-      ensure
-        FileUtils.rm_f(tmp) if tmp && File.exist?(tmp)
+        perm = File.stat(target).mode & 0o7777 if File.exist?(target)
+        AtomicFile.write(target, text, perm: perm)
       end
     end
   end

data/lib/samagotchi/bootstrap/probe.rb

@@ -7,6 +7,8 @@ require "uri"
 require "ipaddr"
 require_relative "../version"
 require_relative "../llm/openai_chat"
+require_relative "../llm/http"
+require_relative "../llm/api_key"
 
 module Samagotchi
   module Bootstrap
@@ -223,12 +225,14 @@ module Samagotchi
         [response.code.to_i, response.body]
       end
 
+      # One attempt through LLM::HTTP (User-Agent, the key's Bearer header),
+      # any status returned as is. A key whose variable is not set sends no
+      # header: the server's 401 then says one is needed.
       def send_request(uri, request, key_env, read_timeout:)
-        request["User-Agent"] = Samagotchi::USER_AGENT
-        key = key_env && @env[key_env].to_s
-        request["Authorization"] = "Bearer #{key}" if key && !key.strip.empty?
-        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout,
-                                            read_timeout: read_timeout) { |http| http.request(request) }
+        key = key_env && !@env[key_env].to_s.strip.empty? ? LLM::ApiKey.for(key_env, host: uri.host, env: @env) : nil
+        LLM::HTTP.new(label: uri.host, open_timeout: @timeout, read_timeout: read_timeout, api_key: key,
+                      retry_policy: LLM::HTTP::RetryPolicy.none)
+                 .fetch(uri, request, retries: false, check_status: false, log_fields: { purpose: "probe" })
       end
 
       def network_errors

data/lib/samagotchi/bootstrap_command.rb

@@ -5,13 +5,15 @@ require_relative "config"
 require_relative "model_profile"
 require_relative "bootstrap/probe"
 require_relative "bootstrap/config_writer"
+require_relative "bootstrap/bundles"
 
 module Samagotchi
   # `chi bootstrap [TARGET]`: the first setup. It names a model server, works
   # out what it is (llama.cpp's native API or an OpenAI-compatible one),
   # picks the model, sends one test request and writes config.yml: a fresh
-  # file, or a hosts: entry added to an existing one. Prompts only on a
-  # terminal; a script gets the list and exit 2 instead.
+  # file, or a hosts: entry added to an existing one. Then it installs the
+  # system bundle and the core profile, and on a terminal asks about dev.
+  # Prompts only on a terminal; a script gets the list and exit 2 instead.
   class BootstrapCommand
     USAGE = <<~TEXT
       Usage: chi bootstrap [TARGET] [--name NAME] [--model ID] [--key-env VAR] [--no-test] [--dry-run]
@@ -31,16 +33,25 @@ module Samagotchi
         --dry-run     show what would be written; write nothing
         With no config.yml it writes one; an existing one gets a hosts:
         entry added (after a backup), and its other lines stay as they are.
+        Then it installs the system bundle and the core bundles (loop-guard,
+        check-in, guardrails), and on a terminal offers the dev bundles.
     TEXT
 
     PICK_SHOWN = 20
     # A test request slower than this says it is waiting (a model loading).
     LOADING_AFTER = 3
+    # The profile bootstrap installs, and the one it offers on a terminal.
+    CORE = "core"
+    DEV = "dev"
+    # The config outcomes after which the bundles are installed.
+    INSTALLS_BUNDLES = %i[new appended exists snippet].freeze
 
     # @param argv [Array<String>] the arguments after "bootstrap"
     # @param probe [Bootstrap::Probe, nil] (specs)
+    # @param bundles [Bootstrap::Bundles, nil] (specs: the bundles go where
+    #   the process ENV points, not +env+)
     def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, env: ENV, probe: nil, config_path: nil,
-                   platform: RbConfig::CONFIG["host_os"])
+                   platform: RbConfig::CONFIG["host_os"], bundles: nil)
       @argv = argv.dup
       @stdin = stdin
       @stdout = stdout
@@ -49,6 +60,7 @@ module Samagotchi
       @probe = probe || Bootstrap::Probe.new(env: env)
       @config_path = config_path || ConfigFile.global_path(env: env)
       @platform = platform
+      @bundles = bundles || Bootstrap::Bundles.new
     end
 
     # @return [Integer] 0 written (or already there), 1 failed (a failed
@@ -244,7 +256,64 @@ module Samagotchi
         return nil
       end
       outcome = writer.write(name: name, fields: fields, model: model, dry_run: options[:dry_run])
-      report(outcome, model)
+      code = report(outcome, model)
+      return code unless INSTALLS_BUNDLES.include?(outcome.kind)
+
+      code = [code, install_bundles].max
+      next_steps if outcome.kind == :new
+      code
+    end
+
+    # The system bundle, core, and dev when a terminal says yes: one line
+    # each. 1 when something failed.
+    def install_bundles(dry_run: false)
+      ok = system_bundle_line(@bundles.sync_system(dry_run: dry_run), dry_run)
+      ok = install_profile(CORE, dry_run) && ok
+      unless dry_run || !tty? || (members = dev_to_install).empty?
+        @stdout.print("Also install #{DEV} (#{members.join(", ")})? [y/N] ")
+        ok = install_profile(DEV, false) && ok if @stdin.gets.to_s.strip.downcase.start_with?("y")
+      end
+      ok ? 0 : 1
+    end
+
+    # One line for the profile; false when it (or a member) failed.
+    def install_profile(name, dry_run)
+      profile_line(@bundles.install(name, dry_run: dry_run), dry_run)
+    rescue StandardError => e
+      @stdout.puts("#{name} bundles: failed (#{e.message.lines.first.to_s.strip})")
+      false
+    end
+
+    def dev_to_install
+      @bundles.to_install(DEV)
+    rescue StandardError
+      []
+    end
+
+    def system_bundle_line(result, dry_run)
+      version = "v#{result.to || result.from}"
+      text = case result.status
+             when :installed then dry_run ? "would install #{version}" : "#{version} installed"
+             when :updated then "#{result.from} → #{result.to} #{dry_run ? "would update" : "updated"}"
+             when :restored then "#{version} #{dry_run ? "would restore" : "restored"} missing files"
+             when :up_to_date then "#{version} up to date"
+             when :newer_installed then "v#{result.from} left as is (newer than this chi's v#{result.to})"
+             when :skipped then "skipped (#{result.error})"
+             else "failed (#{result.error})"
+             end
+      @stdout.puts("system bundle: #{text}")
+      result.status != :failed
+    end
+
+    def profile_line(result, dry_run = false)
+      parts = []
+      parts << "#{dry_run ? "would install" : "installed"} #{result.installed.join(", ")}" unless result.installed.empty?
+      parts << "already installed #{result.already.join(", ")}" unless result.already.empty?
+      result.skipped.each { |member, why| parts << "skipped #{member} (#{why})" }
+      result.failed.each { |member, why| parts << "#{member} failed (#{why})" }
+      parts << "nothing new to install" if parts.empty?
+      @stdout.puts("#{result.name} bundles: #{parts.join("; ")}")
+      !result.failed?
     end
 
     # The hosts entry: host/port for a plain http server (api: openai when it
@@ -267,10 +336,9 @@ module Samagotchi
         @stdout.puts("dry run: would write #{outcome.where} (#{path}):")
         @stdout.puts(outcome.text.gsub(/^/, "  "))
         @stdout.puts("and print: #{outcome.model_hint}") if outcome.model_hint
-        0
+        install_bundles(dry_run: true)
       when :new
         @stdout.puts("config: #{path} (new)")
-        next_steps
         0
       when :appended
         @stdout.puts("config: #{path} (hosts entry '#{outcome.name}' added; backup #{File.basename(outcome.backup)})")
@@ -296,10 +364,12 @@ module Samagotchi
     end
 
     def next_steps
-      lines = [["chi", "a session"], ["chi web --open", "the web UI"], ["chi bundle list", "optional bundles (guardrails, …)"]]
+      dev = dev_to_install
+      bundles = dev.empty? ? ["chi bundle list", "the installed bundles"] : ["chi bundle install #{DEV}", "more bundles (#{dev.join(", ")})"]
+      lines = [["chi", "a session"], ["chi web --open", "the web UI"], bundles]
       lines << ["chi desktop install", "macOS \"Send to chi\" helper"] if @platform.to_s.include?("darwin")
       lines.each_with_index do |(command, what), i|
-        @stdout.puts("#{i.zero? ? "next:" : "     "}  #{command.ljust(20)} # #{what}")
+        @stdout.puts("#{i.zero? ? "next:" : "     "}  #{command.ljust(22)} # #{what}")
       end
     end
 

data/lib/samagotchi/bridge/pending_card.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "fileutils"
+require_relative "../atomic_file"
 
 module Samagotchi
   class Bridge
@@ -72,9 +73,7 @@ module Samagotchi
 
       def write(id, bundle)
         FileUtils.mkdir_p(File.dirname(@path))
-        temp = "#{@path}.tmp"
-        File.write(temp, JSON.generate({ "id" => id, "bundle" => bundle }))
-        File.rename(temp, @path)
+        AtomicFile.write(@path, JSON.generate({ "id" => id, "bundle" => bundle }))
         @id = id
       end
 

data/lib/samagotchi/bridge.rb

@@ -6,6 +6,8 @@ require "uri"
 require "fileutils"
 require "securerandom"
 require "time"
+require_relative "atomic_file"
+require_relative "session_inbox"
 
 require_relative "bridge/bounded_queue"
 require_relative "bridge/card_store"
@@ -20,6 +22,7 @@ require_relative "session_commands"
 require_relative "image_store"
 require_relative "log"
 require_relative "version"
+require_relative "worker_sidecar"
 
 module Samagotchi
   # Bridge is an optional HTTP transport that lets an external web / desktop
@@ -30,7 +33,7 @@ module Samagotchi
   # Design invariants (see multi_ui_architecture):
   # * Reuses `Engine#subscribe` for SSE fan-out — never a second Engine, never
   #   `run_turn` across the thread/process boundary. POST reuses the
-  #   `SessionManager` file-IPC input path.
+  #   `SessionInbox` file-IPC input path.
   # * One capture observer fills a shared ring buffer; each connection gets a
   #   per-connection live queue (see SSEWriter).
   # * Binds 127.0.0.1 only. There is NO auth: binding 0.0.0.0 exposes remote
@@ -39,7 +42,6 @@ module Samagotchi
   #   engaged as a transport.
   class Bridge
     DEFAULT_BIND = "127.0.0.1"
-    SIDECAR_FILE = "bridge.json"
     DEFAULT_RING_CAPACITY = 256
     DEFAULT_HEARTBEAT_INTERVAL = 15.0
     # Cancel reasons a client may name (the web sends user, an attached TUI
@@ -63,7 +65,7 @@ module Samagotchi
     # @param heartbeat_interval [Float] idle `: ping` seconds
     # @param input_format [Integer, nil] the input-file format the owning
     #   worker reads, advertised in the sidecar for writers (see
-    #   SessionManager.write_turn_input); nil advertises none (plain text)
+    #   SessionInbox::INPUT_FORMAT); nil advertises none
     # @param on_input [#call, nil] called once a turn for this session is
     #   queued, to wake the worker loop (Worker::Waker#wake)
     # @param on_command [#call, nil] takes a session command
@@ -298,54 +300,28 @@ module Samagotchi
 
         method = request[:method].to_s.upcase
         headers = request[:headers]
+        route = route_for(method, request[:path])
         # Every request but a stream gets its answer before #stop kills this
         # thread; a stream never ends on its own.
-        Thread.current[:bridge_answering] = !(stream_match(request[:path]) && method == "GET")
+        Thread.current[:bridge_answering] = route&.first != :stream
 
         if request[:too_large]
           write_json(io, 413, { "Connection" => "close" }, { error: "too_large", detail: "request body over #{MAX_BODY_BYTES} bytes" })
           break
         elsif browser_request?(headers)
           write_json(io, 403, nil, { error: "cross_origin", detail: "the bridge answers chi's own clients only" })
-        elsif (m = stream_match(request[:path])) && method == "GET"
+        elsif route.nil?
+          write_json(io, 404, { "Allow" => "GET, POST" },
+                     { error: "not_found", path: request[:path] })
+        elsif route.first == :stream
           cursor = reconnect_cursor(headers, request[:query])
           Log.debug(:bridge, "stream", method: method, path: request[:path], client_id: stream_client_id(request[:query]))
-          serve_sse(io, m[1], last_event_id: cursor, snapshot: snapshot_requested?(request[:query]),
-                              client_id: stream_client_id(request[:query]))
+          serve_sse(io, route.last, last_event_id: cursor, snapshot: snapshot_requested?(request[:query]),
+                                    client_id: stream_client_id(request[:query]))
           break # SSE owns the connection until the client disconnects.
-        elsif (m = cancel_match(request[:path])) && method == "POST"
-          payload, status, body = handle_cancel(m[1], request[:body])
-          write_json(io, status, payload, body)
-        elsif (m = answer_match(request[:path])) && method == "POST"
-          payload, status, body = handle_answer(m[1], request[:body])
-          write_json(io, status, payload, body)
-        elsif (m = dismiss_match(request[:path])) && method == "POST"
-          payload, status, body = handle_dismiss_question(m[1], request[:body])
-          write_json(io, status, payload, body)
-        elsif (m = turn_match(request[:path])) && method == "POST"
-          payload, status, body = handle_post_turn(m[1], request[:body])
-          write_json(io, status, payload, body)
-        elsif (m = command_match(request[:path])) && method == "POST"
-          payload, status, body = handle_command(m[1], request[:body])
-          write_json(io, status, payload, body)
-        elsif (m = exit_match(request[:path])) && method == "POST"
-          payload, status, body = handle_exit_request(m[1], request[:body])
-          write_json(io, status, payload, body)
-        elsif (m = recap_match(request[:path])) && method == "POST"
-          payload, status, body = handle_recap(m[1])
-          write_json(io, status, payload, body)
-        elsif (m = state_match(request[:path])) && method == "GET"
-          payload, status, body = handle_state(m[1])
-          write_json(io, status, payload, body)
-        elsif (m = stats_match(request[:path])) && method == "GET"
-          payload, status, body = handle_stats(m[1])
-          write_json(io, status, payload, body)
-        elsif (m = snapshot_match(request[:path])) && method == "GET"
-          payload, status, body = handle_snapshot(m[1])
-          write_json(io, status, payload, body)
         else
-          write_json(io, 404, { "Allow" => "GET, POST" },
-                     { error: "not_found", path: request[:path] })
+          payload, status, body = send(route.first, route.last, request[:body])
+          write_json(io, status, payload, body)
         end
 
         Thread.current[:bridge_answering] = false
@@ -428,54 +404,36 @@ module Samagotchi
       !host.empty? && !LOOPBACK_NAMES.include?(host.downcase.sub(/:\d*\z/, ""))
     end
 
-    def stream_match(path)
-      %r|\A/session/([^/]+)/stream\z|u.match(path.to_s)
-    end
-
-    def turn_match(path)
-      %r|\A/session/([^/]+)/turn\z|u.match(path.to_s)
-    end
-
-    def state_match(path)
-      %r|\A/session/([^/]+)/state\z|u.match(path.to_s)
-    end
-
-    def stats_match(path)
-      %r|\A/session/([^/]+)/stats\z|u.match(path.to_s)
-    end
-
-    def snapshot_match(path)
-      %r|\A/session/([^/]+)/snapshot\z|u.match(path.to_s)
-    end
-
-    def cancel_match(path)
-      %r|\A/session/([^/]+)/cancel\z|u.match(path.to_s)
-    end
-
-    def answer_match(path)
-      %r|\A/session/([^/]+)/answer\z|u.match(path.to_s)
-    end
-
-    def dismiss_match(path)
-      %r|\A/session/([^/]+)/question/dismiss\z|u.match(path.to_s)
-    end
-
-    def command_match(path)
-      %r|\A/session/([^/]+)/command\z|u.match(path.to_s)
-    end
-
-    def exit_match(path)
-      %r|\A/session/([^/]+)/exit\z|u.match(path.to_s)
-    end
+    # The routes, by method and what follows /session/:id/: a handler takes
+    # the session id and the request body and returns [headers, status, body].
+    # GET stream is served apart (#serve_sse owns the connection).
+    ROUTES = {
+      %w[GET stream] => :stream,
+      %w[POST cancel] => :handle_cancel,
+      %w[POST answer] => :handle_answer,
+      %w[POST question/dismiss] => :handle_dismiss_question,
+      %w[POST turn] => :handle_post_turn,
+      %w[POST command] => :handle_command,
+      %w[POST exit] => :handle_exit_request,
+      %w[POST recap] => :handle_recap,
+      %w[GET state] => :handle_state,
+      %w[GET stats] => :handle_stats,
+      %w[GET snapshot] => :handle_snapshot
+    }.freeze
+    ROUTE_PATH = %r|\A/session/([^/]+)/(.+)\z|u
 
-    def recap_match(path)
-      %r|\A/session/([^/]+)/recap\z|u.match(path.to_s)
+    # @return [Array(Symbol, String), nil] the handler and the session id, or
+    #   nil when no route takes this method and path
+    def route_for(method, path)
+      m = ROUTE_PATH.match(path.to_s) or return nil
+      handler = ROUTES[[method, m[2]]] or return nil
+      [handler, m[1]]
     end
 
     # /recap in an attached TUI: the saved recap, and a new one asked for at
     # once (it arrives as :recap_ready). Answers mid-turn too.
     # 200 {enabled:, saved:, request:, min_user_turns:}. Returns [headers, status, body].
-    def handle_recap(session_id)
+    def handle_recap(session_id, _body = nil)
       return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
 
       recap = @engine.recap
@@ -680,6 +638,10 @@ module Samagotchi
         return [{ "Allow" => "POST" }, 400,
                 { error: "missing_fields", detail: "session_id and prompt are required" }]
       end
+      # Checked before the id names a folder: "../x" would write outside the
+      # sessions dir (turn_images and enqueue_turn build paths from it).
+      return [{}, 400, { error: "invalid_session_id" }] unless Session.valid_id?(sid)
+
       images = turn_images(sid, fetched(parsed, "images"))
       return [{}, 400, { error: "bad_images", detail: images }] if images.is_a?(String)
 
@@ -716,17 +678,12 @@ module Samagotchi
 
       [{}, 202, { status: "accepted", enqueued_id: enqueued_id, session_id: sid }]
     rescue StandardError => e
-      # SessionManager loads lazily (enqueue_turn).
-      if defined?(SessionManager::ImagesUnsupported) && e.is_a?(SessionManager::ImagesUnsupported)
-        return [{}, 409, { error: "images_unsupported", detail: e.message }]
-      end
-
       [{}, 500, { error: "bridge_error", detail: e.message }]
     end
 
     # Read-only snapshot surface. AC #4: too-old reconnects re-derive state
     # from here.
-    def handle_state(session_id)
+    def handle_state(session_id, _body = nil)
       unless own_session?(session_id)
         return [{}, 404, { error: "unknown_session" }]
       end
@@ -738,7 +695,7 @@ module Samagotchi
     # /stats for an attached client: the metrics, with the window and prompt
     # profile asked from the server when no turn has reported them yet (so,
     # unlike /state, it may wait on one short /props GET).
-    def handle_stats(session_id)
+    def handle_stats(session_id, _body = nil)
       return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
 
       [{}, 200, { session_id: @session_id, metrics: @engine.stats_snapshot }]
@@ -748,7 +705,7 @@ module Samagotchi
     # the messages elsewhere (the web server strips and formats them): it then
     # streams from the snapshot's event_seq, and the ring replays what came
     # after (or the stream resets). Returns [headers, status, body].
-    def handle_snapshot(session_id)
+    def handle_snapshot(session_id, _body = nil)
       return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
 
       body = @engine.synchronize_events do
@@ -768,7 +725,7 @@ module Samagotchi
     # stream and state surfaces must serve that session and nothing else —
     # serving a different id's data (or closing with no response) would be a
     # cross-session leak. POST/turn enqueue stays lenient (fire-and-forget to
-    # another worker's input dir) and validates via write_turn_input.
+    # another worker's input dir) through SessionInbox.write_input.
     def own_session?(session_id)
       session_id.to_s == @session_id.to_s
     end
@@ -797,14 +754,9 @@ module Samagotchi
     # Write a turn into the target session's input dir, reusing the file IPC
     # the worker polls. Never calls run_turn across the boundary.
     def enqueue_turn(session_id:, prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [])
-      require_relative "session_manager"
-      Samagotchi::SessionManager.write_turn_input(
-        session_id, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id, no_interrupt: no_interrupt,
-                    state_dir: @state_dir, images: images
-      )
-    rescue LoadError
-      # SessionManager not available (e.g. bridge used standalone in a spec).
-      false
+      session_dir = Session.session_dir(session_id, state_dir: @state_dir || Session.default_state_dir)
+      SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
+                                            no_interrupt: no_interrupt, images: images)
     end
 
     # A turn's images as [{file:, name:}], or a String saying what's wrong.
@@ -963,31 +915,19 @@ module Samagotchi
     end
 
     def write_sidecar
-      record = {
-        "port" => @port,
-        "bind" => @bind,
-        "session_id" => @session_id,
-        "started_at" => Time.now.iso8601(3),
-        # The chi this worker runs (chi update reports older ones).
-        "version" => Samagotchi::VERSION
-      }
-      record["input_format"] = @input_format if @input_format
-      path = File.join(session_dir, SIDECAR_FILE)
-      FileUtils.mkdir_p(session_dir)
-      temp = "#{path}.tmp"
-      File.write(temp, JSON.pretty_generate(record) + "\n")
-      File.rename(temp, path)
+      # version: the chi this worker runs (chi update reports older ones).
+      WorkerSidecar.new(port: @port, bind: @bind, session_id: @session_id, started_at: Time.now.iso8601(3),
+                        version: Samagotchi::VERSION, input_format: @input_format).write(session_dir)
     rescue StandardError => e
-      Log.warn(:bridge, "sidecar_write_failed", echo: "Bridge: failed to write #{SIDECAR_FILE}: #{e.class}: #{e.message}", error: e.class.name)
+      Log.warn(:bridge, "sidecar_write_failed", echo: "Bridge: failed to write #{WorkerSidecar::FILE}: #{e.class}: #{e.message}", error: e.class.name)
     end
 
     # Only while it still names this bridge: a racing worker for the same
     # session may have written its own since.
     def remove_sidecar
-      path = File.join(session_dir, SIDECAR_FILE)
-      return unless @server && File.file?(path)
+      return unless @server
 
-      File.unlink(path) if JSON.parse(File.read(path))["port"].to_i == @port
+      File.unlink(WorkerSidecar.path(session_dir)) if WorkerSidecar.read(session_dir)&.port == @port
     rescue StandardError
       nil
     end

data/lib/samagotchi/bridge_client.rb

@@ -3,19 +3,20 @@
 require "json"
 require "socket"
 
+require_relative "worker_sidecar"
 require_relative "bridge_client/sse_parser"
 require_relative "bridge_client/event_stream"
 
 module Samagotchi
   # Client side of a session worker's Bridge: the 127.0.0.1 HTTP + SSE server
   # each SessionManager worker runs for its Engine (see Bridge). Discovery goes
-  # through the worker's `bridge.json` sidecar in the session directory.
+  # through the worker's `bridge.json` sidecar (WorkerSidecar) in the session
+  # directory.
   #
   # Requests are raw one-shot HTTP/1.1 over a TCPSocket (`Connection: close`),
   # exactly what the Bridge's minimal server expects.
   class BridgeClient
     HOST = "127.0.0.1"
-    SIDECAR_FILE = "bridge.json"
     PROBE_TIMEOUT = 0.2
     STREAM_CONNECT_ATTEMPTS = 3
     # Seconds #stream waits for bytes before it asks `running` again.
@@ -58,13 +59,8 @@ module Samagotchi
     # @param session_dir [String]
     # @return [Integer, nil]
     def self.sidecar_port(session_dir, host: HOST)
-      sidecar = File.join(session_dir, SIDECAR_FILE)
-      return nil unless File.file?(sidecar)
-
-      data = JSON.parse(File.read(sidecar))
-      port = data["port"]
-      port = port.is_a?(Integer) ? port : port.to_i
-      return nil unless port.to_i > 0
+      port = WorkerSidecar.read(session_dir)&.port
+      return nil unless port&.positive?
 
       # Validate liveness: stale sidecar after worker death causes ECONNREFUSED
       # which surfaces as WEBrick ERROR. Probe quickly and clean up if dead.
@@ -72,7 +68,7 @@ module Samagotchi
         Socket.tcp(host, port, connect_timeout: PROBE_TIMEOUT).close
       rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError, IOError, StandardError
         begin
-          File.unlink(sidecar)
+          File.unlink(WorkerSidecar.path(session_dir))
         rescue StandardError
           nil
         end
@@ -149,7 +145,7 @@ module Samagotchi
     # @return [Response]
     # @param no_interrupt [Boolean] run the turn with the raised iteration limit
     # @param images [Array<Hash>] refs ({file:, name:}) to images already in
-    #   the session's images/ (409 images_unsupported from an older worker)
+    #   the session's images/
     def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil)
       body = { session_id: @session_id, prompt: prompt, client_id: client_id }
       body[:no_interrupt] = true if no_interrupt