samagotchi 0.119.0 → 0.120.0

data/lib/samagotchi/share_command.rb

@@ -22,13 +22,16 @@ module Samagotchi
     include CLI::Command
 
     USAGE = <<~TEXT
-      Usage: chi share ID --name NAME [--agent] [--expires 3d] [--cap 2]
+      Usage: chi share ID --name NAME [--identity EMAIL] [--agent] [--expires 3d] [--cap 2]
              chi share ls [ID] [--format text|json]
              chi share cap ID PARTICIPANT DOLLARS
              chi share revoke ID [PARTICIPANT] | --all
         ID --name NAME   invite NAME to review session ID: prints the link they open (chi web on
                          the LAN, web.host: lan) and its QR code at a terminal. The link is shown
                          once; chi keeps only a digest of its token.
+          --identity EMAIL  bind the link to that account: it opens only through chi web's auth proxy
+                         signed in as EMAIL (web.public_url with web.proxy.identity_header, or
+                         chi web --tunnel tailscale); a forwarded link opens for nobody else
           --agent        the participant is an agent (the same link, used as a Bearer token)
           --expires N    Nh or Nd, 1h to 30d (default 7d, web.participants.expires)
           --cap DOLLARS  what their turns may cost you, $0 to $1000 (default $2, web.participants.cap)
@@ -50,6 +53,7 @@ module Samagotchi
     # The invite's flags (chi share ID …), and ls's and revoke's.
     FLAGS = CLI::Flags.new(help: HELP_WORDS) do |f|
       f.value "--name"
+      f.value "--identity"
       f.switch "--agent"
       f.value "--expires"
       f.value "--cap"
@@ -91,9 +95,9 @@ module Samagotchi
       return parsed if parsed.is_a?(Integer)
 
       send(:"run_#{@sub || "invite"}", parsed.options, parsed.args)
-    rescue SessionAccess::BadRequest => e
+    rescue SessionAccess::BadRequest, Web::Grants::BadIdentity => e
       usage_error(e.message)
-    rescue Web::Grants::Corrupt => e
+    rescue Web::Grants::Unwritable => e
       error_line("#{command_name}: #{e.message}")
       CLI::Exit::FAILED
     rescue ArgumentError => e
@@ -116,9 +120,13 @@ module Samagotchi
       cap = options[:cap] && dollars(options[:cap])
       return usage_error(CAP_USAGE) if cap == false
 
+      identity = options[:identity] && Web::Grants.clean_identity(options[:identity])
+
       id = @access.resolve(args.first)
-      invitation = @access.invite(id, name: options[:name], kind: options[:agent] ? "agent" : "human", ttl: ttl, cap: cap)
+      invitation = @access.invite(id, name: options[:name], kind: options[:agent] ? "agent" : "human", ttl: ttl, cap: cap,
+                                      identity: identity)
       print_invitation(id, invitation)
+      warn_unbound(invitation.participant)
       @changes = [[:joined, invitation.participant.id]]
       0
     end
@@ -186,10 +194,21 @@ module Samagotchi
       0
     end
 
+    # Decision B: an unbound link behind a proxy that could bind it opens
+    # for anyone the proxy lets in who holds it.
+    def warn_unbound(row)
+      return unless row.identity.nil? && (header = @access.identity_header)
+
+      error_line("#{command_name}: warning: #{format(UNBOUND_WARNING, header: header)}")
+    end
+
+    UNBOUND_WARNING = "this link isn't bound to an account: anyone the proxy lets in who gets it can open it " \
+                      "(--identity EMAIL binds it to the email %<header>s carries)"
+
     def print_invitation(id, invitation)
       row = invitation.participant
       @stdout.puts("#{row.id}  #{row.name} (#{row.kind}, #{row.role}) · session #{id[0, 8]} · expires " \
-                   "#{local(row.expires_at, "%Y-%m-%d %H:%M")} · cap #{money(row.cap)}")
+                   "#{local(row.expires_at, "%Y-%m-%d %H:%M")} · cap #{money(row.cap)}#{" · bound to #{row.identity}" if row.identity}")
       @stdout.puts(invitation.link)
       @stdout.puts("(shown once: chi keeps only its digest; chi share revoke #{id[0, 8]} #{row.id} ends it)")
       if invitation.warning
@@ -201,12 +220,14 @@ module Samagotchi
       @stdout.puts(Web::QR.lines(invitation.link)) if @tty
     end
 
-    COLUMNS = ["SESSION", "PARTICIPANT", "NAME", "KIND", "ROLE", "CREATED", "EXPIRES", "LAST USED", "CAP", "STATE"].freeze
+    COLUMNS = ["SESSION", "PARTICIPANT", "NAME", "IDENTITY", "KIND", "ROLE", "CREATED", "EXPIRES", "LAST USED", "CAP",
+               "STATE"].freeze
 
     def print_table(rows)
       cells = rows.map do |row|
-        [row.session_id[0, 8], row.id, row.name, row.kind, row.role, local(row.created_at), local(row.expires_at),
-         row.last_used_at ? local(row.last_used_at) : "-", money(row.cap), row.state]
+        [row.session_id[0, 8], row.id, row.name, row.identity ? "#{row.identity} · bound" : "-", row.kind, row.role,
+         local(row.created_at), local(row.expires_at), row.last_used_at ? local(row.last_used_at) : "-", money(row.cap),
+         row.state]
       end
       widths = COLUMNS.each_index.map { |i| ([COLUMNS[i]] + cells.map { |c| c[i] }).map(&:length).max }
       [COLUMNS, *cells].each do |line|

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../client_id"
+require_relative "../bridge_secret"
 require_relative "../composer_route"
 require_relative "event_renderer"
 require_relative "formatting"
@@ -450,6 +451,8 @@ module Samagotchi
       # The stream ended for good: why, and what brings the session back.
       def closed_line(reason)
         id = @client.session_id
+        # The worker asked for a secret this terminal's chi doesn't send.
+        return "Lost the session's worker: #{BridgeSecret::REFUSED}" if reason == BridgeSecret::ERROR
         return remote_closed_line(reason, id) if via.remote?
 
         # Here a stopped session has always read as unreachable.

data/lib/samagotchi/terminal_ui/local_link.rb

@@ -55,12 +55,27 @@ module Samagotchi
         id = @client.session_id
         return [:gone, "stopped"] if Session.stopped_marker?(id, state_dir: @state_dir)
 
-        [BridgeClient.discover(id, session_dir: session_dir, host: @client.host), nil]
+        # Kept: the stream moves to this very client (EventStream), and
+        # #switched takes it, port and secret, rather than reading again.
+        @found = BridgeClient.discover(id, session_dir: session_dir, host: @client.host)
+        [@found, nil]
       end
 
-      # A new worker's Bridge, on the port its event names.
+      # A new worker's Bridge: the client #live_worker found for the stream
+      # (the event names its port), with that worker's secret. One the event
+      # doesn't name (another worker since) is read from the sidecar for that
+      # port, none when the sidecar names another one by now: that worker is
+      # gone too, and the stream finds the next.
       def switched(event)
-        @client = BridgeClient.new(session_id: @client.session_id, port: AttachLink.event_port(event), host: @client.host)
+        port = AttachLink.event_port(event)
+        found = @found
+        @client = if found&.port == port
+                    found
+                  else
+                    sidecar = WorkerSidecar.read(session_dir)
+                    sidecar = WorkerSidecar.new(port: port) unless sidecar&.port == port
+                    BridgeClient.for_sidecar(@client.session_id, sidecar, host: @client.host)
+                  end
       end
 
       # No sidecar to read: true, its Bridge answers (a P0-P2 worker refuses

data/lib/samagotchi/tools/delegate_relay.rb

@@ -139,6 +139,10 @@ module Samagotchi
       def delivered(response, answer, fields, dismissed)
         return "not delivered (the child's worker is gone)" unless response
 
+        # The child's Bridge asked for a secret this worker didn't send (one
+        # from before the child's chi): not the child's guardrails refusing.
+        return "not delivered (#{BridgeSecret::REFUSED})" if response.secret_refused?
+
         hook = fields[:kind] == HOOK_KIND
         case response.status
         when 200

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.119.0"
+  VERSION = "0.120.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -145,6 +145,8 @@ module Samagotchi
       #   with +public_url+ (the LAN one when both are set)
       # @param push [Push::Runtime, nil] Web Push for this run (PushRoutes);
       #   nil: off (no https public_url, or web.push.enabled false)
+      # @param start_dir [String] the folder chi web starts in (StartDir):
+      #   where a new session without a dir starts (nil: the cwd)
       def initialize(manager: nil, session_class: nil, state_dir: nil, public_dir: nil,
                      bridge_wait_timeout: BRIDGE_WAIT_TIMEOUT, markdown: false, view: Config::BY_KEY["web.view"].default, hub: nil,
                      annotate_presets: Config::BY_KEY["web.annotate_presets"].default,
@@ -152,7 +154,8 @@ module Samagotchi
                      events_heartbeat: EVENTS_HEARTBEAT, events_queue: EVENTS_QUEUE,
                      registry: nil, models_wait_timeout: MODELS_WAIT_TIMEOUT, lan: nil,
                      working_set: Config::BY_KEY["web.working_set"].default, wait_poll_interval: ReplyWait::POLL_INTERVAL,
-                     grants: nil, public_url: nil, public_token: nil, push: nil)
+                     grants: nil, public_url: nil, public_token: nil, push: nil, start_dir: nil)
+        @start_dir = start_dir
         @manager = manager || SessionManager
         @registry = registry
         @registry_given = !registry.nil?
@@ -490,7 +493,9 @@ module Samagotchi
 
       # The token a trade presents: the page's ?token=, or POST /api/token's
       # body's (read once): its token, or the token a one-time link code
-      # stands for (LinkCodes#redeem: used up here, whatever the gate says).
+      # stands for (LinkCodes#redeem: used up here, whatever the gate says,
+      # but for a grant's code bound to another identity: decision C, kept
+      # for the right one, and refused token_bound, #code_token).
       def traded_token(req)
         return req.params["token"] unless fragment_trade?(req)
 
@@ -501,17 +506,38 @@ module Samagotchi
                   else parse_json(raw)
                   end
           value = {} unless value.is_a?(Hash)
-          req.env[TRADED_TOKEN_ENV] = value.key?("code") ? code_token(value["code"]) : string_or_nil(value["token"])
+          req.env[TRADED_TOKEN_ENV] = value.key?("code") ? code_token(req, value["code"]) : string_or_nil(value["token"])
         end
       end
 
       def string_or_nil(value) = value.is_a?(String) ? value : nil
 
-      def code_token(code)
-        kind, token = @link_codes.redeem(code)
+      # A bound grant's code is checked before it is used up: presented by
+      # another identity, or not through the proxy, it stays (the one it was
+      # sent to can still open it) and the trade is refused token_bound.
+      def code_token(req, code)
+        kind, token = @link_codes.redeem(code) do |found_kind, found_token|
+          found_kind == :owner || code_identity_ok?(req, found_token)
+        end
         kind == :owner ? current_token : token
       end
 
+      def code_identity_ok?(req, token)
+        grant = @grants.lookup(token)
+        # No grant to check it against (deleted, left out of a newer store,
+        # a store that doesn't read): kept, the trade refused.
+        return false if grant.nil?
+        return true unless grant.identity
+
+        proxied = proxied?(req)
+        state, identity = proxied ? proxy_identity(req) : [:none, nil]
+        identity = nil unless state == :ok
+        return true if bound_ok?(grant, identity, proxied)
+
+        refuse_bound(req, grant, identity)
+        false
+      end
+
       TRADED_TOKEN_ENV = "samagotchi.traded_token"
 
       def fragment_trade?(req) = req.post? && req.path_info == TOKEN_TRADE_PATH
@@ -566,7 +592,7 @@ module Samagotchi
       # no longer works is cleared too, so the browser it was left in (the
       # owner's, who opened a participant link) is the owner's again.
       def refused_token(req)
-        response = grant_ended_response(req) || unauthorized(req)
+        response = grant_bound_response(req) || grant_ended_response(req) || unauthorized(req)
         return response if token_required?(req) || !Grants.token?(req.cookies[token_cookie_name(req)])
 
         status, headers, body = response
@@ -837,18 +863,27 @@ module Samagotchi
       # workers it starts run that one, not this chi web's version;
       # session_commands: the routes chi --remote needs
       # (SessionAccessRoutes::FEATURE); remote_attach: the ones a remote
-      # attached TUI needs (ATTACH_FEATURE). lan: its LAN address, nil when it
-      # listens on loopback only; public_url: web.public_url's origin, nil
-      # without one. A participant gets app, version and features only
+      # attached TUI needs (ATTACH_FEATURE); bound_grants: an invite takes an
+      # identity (BOUND_FEATURE). lan: its LAN address, nil when it listens
+      # on loopback only; proxy: {identity_header} behind an auth proxy
+      # (web.public_url or a tunnel; the header nil when none is trusted),
+      # nil without one: the Invite dialog's email field and chi share's
+      # warning. A participant gets app, version and features only
       # (#participant_info).
       def handle_info(req)
         return participant_info unless principal(req).owner?
 
         json_response(200, { app: "chi-web", version: Samagotchi::VERSION, installed: @hub&.installed, pid: Process.pid,
-                             cwd: Dir.pwd, features: INFO_FEATURES, lan: @lan && @lan[:ip] })
+                             cwd: Dir.pwd, start_dir: start_dir, features: INFO_FEATURES, lan: @lan && @lan[:ip],
+                             proxy: @public_url && { identity_header: @public_url.identity_header } })
       end
 
-      INFO_FEATURES = ["dir", "newest_workers", SessionAccessRoutes::FEATURE, SessionAccessRoutes::ATTACH_FEATURE].freeze
+      # POST …/participants takes an identity (a grant bound to it): a chi
+      # web without it would ignore one and issue an unbound grant, so chi
+      # --remote share --identity asks for this first.
+      BOUND_FEATURE = "bound_grants"
+      INFO_FEATURES = ["dir", "newest_workers", SessionAccessRoutes::FEATURE, SessionAccessRoutes::ATTACH_FEATURE,
+                       BOUND_FEATURE].freeze
 
       # The models a new session can start on, spelled as chi spells them
       # elsewhere: bare for the default host (what default.model holds), and
@@ -1049,6 +1084,10 @@ module Samagotchi
         return not_live(id) unless client
 
         reply = request.call(client)
+        # Not the route's own 403 (a parent's option refused): the worker
+        # asked for a secret this chi web didn't send.
+        return error_response(502, BridgeSecret::ERROR, BridgeSecret::REFUSED) if reply.secret_refused?
+
         mapped = yield(reply)
         return mapped if mapped
 
@@ -1095,8 +1134,8 @@ module Samagotchi
       # The session's Bridge, waiting briefly for one a resume just spawned.
       # @return [BridgeClient, nil]
       def live_bridge_client(id)
-        port = bridge_sidecar_port(id) || await_bridge_port(id, timeout: [@bridge_wait_timeout.to_f, 5.0].min)
-        port && BridgeClient.new(session_id: id, port: port, host: DEFAULT_HOST)
+        sidecar = bridge_sidecar(id) || await_bridge_sidecar(id, timeout: [@bridge_wait_timeout.to_f, 5.0].min)
+        bridge_client_for(id, sidecar)
       end
 
       # The process holding the session (an OwnerLock::Owner), or nil. A worker always runs a Bridge; a TUI (plain `chi`) doesn't share.
@@ -1319,14 +1358,16 @@ module Samagotchi
         # Single live transport: proxy to the session's Bridge. When no live
         # worker exists there is nothing to stream — history is available via
         # GET /api/sessions/:id/output.
-        bridge_port = bridge_sidecar_port(id)
+        sidecar = bridge_sidecar(id)
         # A resume just spawned the worker: its bridge may still be binding.
         # Wait briefly for it so the first SSE connect lands on a live bridge
         # instead of an instantly-closed empty 200 / 503 during startup.
-        if bridge_port.nil? && @bridge_wait_timeout.to_i.positive?
-          bridge_port = await_bridge_port(id, timeout: [@bridge_wait_timeout.to_f, 2.0].min)
+        if sidecar.nil? && @bridge_wait_timeout.to_i.positive?
+          sidecar = await_bridge_sidecar(id, timeout: [@bridge_wait_timeout.to_f, 2.0].min)
         end
-        return error_response(503, "not_live", "no live bridge for session #{id}") unless bridge_port
+        return error_response(503, "not_live", "no live bridge for session #{id}") unless sidecar
+
+        client = bridge_client_for(id, sidecar)
 
         headers = {
           "Content-Type" => "text/event-stream",
@@ -1341,19 +1382,19 @@ module Samagotchi
         # handler supports hijacking, stream frames straight to the socket
         # instead of returning an enumerable.
         if req.env["rack.hijack?"]
-          hijack = sse_hijack(id, req, bridge_port)
+          hijack = sse_hijack(id, req, client)
           return [200, headers.merge("rack.hijack" => hijack), []]
         end
 
-        [200, headers, proxy_stream_body(id, req, bridge_port)]
+        [200, headers, proxy_stream_body(id, req, client)]
       end
 
       # The one ProxyStreamBody both of #handle_stream's transports send:
       # the session's Bridge stream, through the request principal's frame
       # filter (#stream_filter).
-      def proxy_stream_body(id, req, port)
+      def proxy_stream_body(id, req, client)
         query = participant_view?(req) ? participant_stream_query(req) : stream_query(req)
-        ProxyStreamBody.new(host: DEFAULT_HOST, port: port, session_id: id, query: query, headers: req.env,
+        ProxyStreamBody.new(client: client, query: query, headers: req.env,
                             server_running: stream_running(principal(req)), filter: stream_filter(req, id))
       end
 
@@ -1424,45 +1465,47 @@ module Samagotchi
       # frames directly to the client socket until it disconnects. The handler
       # (WEBrick via rackup) has already sent the status line + headers, so
       # only body bytes go to the socket here.
-      def sse_hijack(id, req, port)
+      def sse_hijack(id, req, client)
         # Made before the status line goes out: a principal with no filter
         # is refused (#stream_filter), never streamed.
-        body = proxy_stream_body(id, req, port)
+        body = proxy_stream_body(id, req, client)
         lambda do |io|
           body.each { |chunk| io.write(chunk) }
         rescue Errno::EPIPE, Errno::ECONNRESET, IOError
           nil # client went away — end the stream quietly
         rescue StandardError => e
-          Log.warn(:web, "proxy_failed", sid: id, port: port, error: e.class.name, msg: e.message)
+          Log.warn(:web, "proxy_failed", sid: id, port: client.port, error: e.class.name, msg: e.message)
           nil
         end
       end
 
       # Bounded wait for a freshly-spawned worker's bridge sidecar so the
       # response hands the client a live transport without client-side polling.
-      # Returns the bridge port, or nil when it is not up by the deadline (the
+      # Returns the bridge's sidecar (WorkerSidecar), or nil when it is not up by the deadline (the
       # session still exists; EventSource auto-reconnect covers late binders).
-      def await_bridge_port(session_id, timeout: @bridge_wait_timeout)
+      def await_bridge_sidecar(session_id, timeout: @bridge_wait_timeout)
         return nil if timeout.nil? || timeout <= 0
 
-        BridgeClient.poll(timeout, interval: BridgeClient::SPAWN_POLL_INTERVAL) { bridge_sidecar_port(session_id) }
+        BridgeClient.poll(timeout, interval: BridgeClient::SPAWN_POLL_INTERVAL) { bridge_sidecar(session_id) }
       rescue StandardError
         nil
       end
 
-      # Port of the session's live Bridge (stale sidecars are removed), or nil.
-      def bridge_sidecar_port(session_id)
+      # The session's live Bridge's sidecar (stale ones are removed), or nil:
+      # read again for every request, so a respawned worker's port and secret
+      # are the ones used.
+      # @return [WorkerSidecar, nil]
+      def bridge_sidecar(session_id)
         dir = @session_class.session_dir(session_id, state_dir: default_state_dir)
-        BridgeClient.sidecar_port(dir, host: DEFAULT_HOST)
+        BridgeClient.live_sidecar(dir, host: DEFAULT_HOST)
       rescue StandardError
         nil
       end
 
       # @return [BridgeClient, nil] a client for the session's live Bridge
-      def bridge_client(session_id)
-        port = bridge_sidecar_port(session_id)
-        port && BridgeClient.new(session_id: session_id, port: port, host: DEFAULT_HOST)
-      end
+      def bridge_client(session_id) = bridge_client_for(session_id, bridge_sidecar(session_id))
+
+      def bridge_client_for(session_id, sidecar) = BridgeClient.for_sidecar(session_id, sidecar, host: DEFAULT_HOST)
 
       # GET a read path of the session's live Bridge (+path+: "state",
       # "snapshot", "stats", ...).
@@ -1582,6 +1625,9 @@ module Samagotchi
         @state_dir || Session.default_state_dir
       end
 
+      # The folder chi web starts in (StartDir), the cwd when none was given.
+      def start_dir = @start_dir || Dir.pwd
+
       # The sessions folder as the page shows it: ~ for the home folder.
       def sessions_dir_label
         home_label(File.expand_path(default_state_dir))
@@ -1590,34 +1636,61 @@ module Samagotchi
       def home_label(dir) = Paths.tilde(dir)
 
       # <body> data for the page: where sessions are stored, where an
-      # all-view new chat starts (the server's cwd), and, when ?dir names a
+      # all-view new chat starts (the start folder), and, when ?dir names a
       # folder in a repo, that project's name and root. A bad dir adds
       # nothing here: the list call answers 400 and the page says so.
+      # Without ?dir (and without ?scope=all) the page is the start folder's
+      # project view when that folder is in a repo: data-scope-dir names it
+      # for the page (the URL stays bare, so a token's 303, a link code's
+      # #code= and the app's start_url "/" all land there). ?dir= beats
+      # ?scope=all.
       def index_data_attributes(req)
         # version: the chi that served the page; the events snapshot names
         # the one serving now (an upgraded chi web after a reconnect).
-        attrs = { "sessions-dir" => sessions_dir_label, "server-dir" => home_label(Dir.pwd), "version" => Samagotchi::VERSION }
+        attrs = { "sessions-dir" => sessions_dir_label, "server-dir" => home_label(start_dir), "version" => Samagotchi::VERSION }
         attrs["view"] = view_name(req.params["view"])
         # Only when on: the page reads its presence (the turn view ignores it).
         attrs["working-set"] = "1" if working_set?(req.params["working_set"])
-        # Always there: an empty one means no presets, not the default.
-        attrs["annotate-presets"] = @annotate_presets
+        attrs.merge!(annotate_presets_data)
         dir, = scope_dir(req.params["dir"])
+        unless dir
+          dir = default_scope_dir(req)
+          attrs["scope-dir"] = dir if dir
+        end
         root = dir && ProjectScope.root_for(dir)
         if root
           attrs["project-name"] = File.basename(root)
           attrs["project-dir"] = home_label(root)
         elsif dir.nil?
           # The all view's way back: the project view it came from
-          # (?from=), else the project chi web runs in.
+          # (?from=), else the project chi web starts in.
           back, = scope_dir(req.params["from"])
-          back ||= Dir.pwd
+          back ||= start_dir
           if (back_root = ProjectScope.root_for(back))
             attrs["back-name"] = File.basename(back_root)
             attrs["back-dir"] = back
           end
         end
-        attrs.map { |key, value| %(data-#{key}="#{Rack::Utils.escape_html(value)}") }.join(" ")
+        body_data(attrs)
+      end
+
+      # +attrs+ as <body> data attributes, each value escaped.
+      def body_data(attrs) = attrs.map { |key, value| %(data-#{key}="#{Rack::Utils.escape_html(value)}") }.join(" ")
+
+      # The Annotate presets (web.annotate_presets) for a page's <body>, the
+      # owner's and the participant page's. Always there: an empty one means
+      # no presets, not the default.
+      def annotate_presets_data = { "annotate-presets" => @annotate_presets }
+
+      # The folder a bare page (no ?dir, no ?scope=all) is scoped to: the
+      # start folder when it is still a folder in a repo, else nil (every
+      # session).
+      def default_scope_dir(req)
+        return nil unless req.params["dir"].to_s.strip.empty?
+        return nil if req.params["scope"] == "all"
+
+        dir = File.expand_path(start_dir)
+        File.directory?(dir) && ProjectScope.root_for(dir) ? dir : nil
       end
 
       VIEWS = Config::BY_KEY["web.view"].enum_values
@@ -1750,8 +1823,9 @@ module Samagotchi
         #   is kept (the env carries the token cookie, never held or inspected)
         # @param filter [#call, nil] chunk -> String (nil or "": nothing sent);
         #   it sees the Bridge's reads as they come, not whole frames
-        def initialize(host:, port:, session_id:, query:, headers:, server_running: -> { true }, filter: nil)
-          @client = BridgeClient.new(session_id: session_id, port: port, host: host)
+        # @param client [BridgeClient] the session's Bridge (App#bridge_client_for)
+        def initialize(client:, query:, headers:, server_running: -> { true }, filter: nil)
+          @client = client
           @query = query
           @last_event_id = headers["HTTP_LAST_EVENT_ID"]
           @server_running = server_running