samagotchi 0.119.0 → 0.120.0

data/lib/samagotchi/bridge_client/event_stream.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "uri"
+require_relative "../bridge_secret"
 
 module Samagotchi
   class BridgeClient
@@ -13,8 +14,9 @@ module Samagotchi
     # what was missed, or sends a `reset` frame carrying a fresh snapshot when
     # it can't. Either snapshot kind means "re-render from here".
     #
-    # When the Bridge stays unreachable through every reconnect delay, or does
-    # not serve the session (404), it yields one synthetic
+    # When the Bridge stays unreachable through every reconnect delay, does
+    # not serve the session (404), or refuses it for want of its secret (403
+    # bridge_secret, after rediscovery found no new worker), it yields one synthetic
     # `{"type" => "stream_closed", "reason" => ...}` and stops. #close stops
     # it without that event.
     #
@@ -120,6 +122,16 @@ module Samagotchi
           break if closed?
           return finish("unknown_session") if outcome == :unknown_session
 
+          # Refused for want of the secret: a new worker (a new sidecar, a
+          # new secret) is followed at once; else no retry would get in.
+          if outcome == :secret_refused
+            return finish(BridgeSecret::ERROR) unless rediscover_worker == :moved
+
+            failures = 0
+            @reason = nil
+            next
+          end
+
           if outcome == :events
             failures = 0
             @reason = nil
@@ -146,7 +158,7 @@ module Samagotchi
 
       # One connection: :events when it yielded any, else why it failed.
       def read_connection
-        sock, status = @client.connect_stream(query: @query, last_event_id: @last_event_id, timeout: HEADER_TIMEOUT)
+        sock, status, headers = @client.connect_stream(query: @query, last_event_id: @last_event_id, timeout: HEADER_TIMEOUT)
         return :unreachable unless sock
 
         unless attach(sock)
@@ -154,6 +166,7 @@ module Samagotchi
           return :closed
         end
         return :unknown_session if status == 404
+        return :secret_refused if status == 403 && BridgeSecret.refused?(status, refusal_body(sock, headers))
         return :unreachable unless status == 200
 
         # Back as soon as the stream answers: a replay may bring nothing
@@ -181,6 +194,24 @@ module Samagotchi
         detach(sock)
       end
 
+      # A refusal's JSON body: its Content-Length's worth, else up to the
+      # Bridge's close, within HEADER_TIMEOUT.
+      def refusal_body(sock, headers)
+        body = +""
+        length = headers.to_h["content-length"]&.to_i
+        limit = length&.between?(0, 16_384) ? length : 16_384
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + HEADER_TIMEOUT
+        while body.bytesize < limit
+          left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break unless left.positive? && sock.wait_readable(left)
+
+          body << sock.readpartial(limit - body.bytesize)
+        end
+        body
+      rescue IOError, SystemCallError
+        body
+      end
+
       # Publish the socket for #close; false when already closed.
       def attach(sock)
         @mutex.synchronize do

data/lib/samagotchi/bridge_client.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json"
 require "socket"
 
 require_relative "worker_sidecar"
+require_relative "bridge_secret"
 require_relative "delivery"
 require_relative "chi_invocation"
 require_relative "bridge_client/sse_parser"
@@ -22,6 +24,8 @@ module Samagotchi
     HOST = "127.0.0.1"
     # A reply's status line; its code is group 1.
     STATUS_LINE = StreamRequest::STATUS_LINE
+    # The request header that carries the Bridge's secret (Bridge#secret_ok?).
+    SECRET_HEADER = BridgeSecret::HEADER
     STREAM_CONNECT_ATTEMPTS = 3
     # Seconds #stream waits for the Bridge's response headers, per attempt:
     # a worker that took the connection and froze must not hold the web's
@@ -45,6 +49,9 @@ module Samagotchi
     Response = Struct.new(:status, :body, keyword_init: true) do
       def ok? = status == 200
 
+      # The Bridge refused it for want of its secret (BridgeSecret::REFUSED says what to do).
+      def secret_refused? = BridgeSecret.refused?(status, body)
+
       # @return [Hash, nil] the body parsed as JSON, or nil when it is not
       def json
         JSON.parse(body.to_s)
@@ -68,19 +75,28 @@ module Samagotchi
       "this session's worker runs an older chi and can't #{cant}; restart it: #{restart} (its turns still work)"
     end
 
-    # Port of the live Bridge advertised in +session_dir+'s sidecar, or nil.
-    # A sidecar whose port refuses a quick connect is stale (its worker died)
-    # and is removed.
+    # The live Bridge's sidecar in +session_dir+, or nil. A sidecar whose
+    # port refuses a quick connect is stale (its worker died) and is removed.
     # @param session_dir [String]
-    # @return [Integer, nil]
-    def self.sidecar_port(session_dir, host: HOST)
-      WorkerSidecar.live_port(session_dir, unlink: true, host: host)
+    # @return [WorkerSidecar, nil]
+    def self.live_sidecar(session_dir, host: HOST)
+      WorkerSidecar.live(session_dir, unlink: true, host: host)
+    end
+
+    # The one way a client is made for a worker: its port and its secret
+    # come from the same sidecar read, so a respawned worker (a new port, a
+    # new secret) is reached by a client made after it, never by hand.
+    # @param sidecar [WorkerSidecar, nil]
+    # @return [BridgeClient, nil] nil without a sidecar
+    def self.for_sidecar(session_id, sidecar, host: HOST, read_timeout: READ_TIMEOUT)
+      return nil unless sidecar
+
+      new(session_id: session_id, port: sidecar.port, secret: sidecar.secret, host: host, read_timeout: read_timeout)
     end
 
     # @return [BridgeClient, nil] a client for the live Bridge in +session_dir+
-    def self.discover(session_id, session_dir:, host: HOST)
-      port = sidecar_port(session_dir, host: host)
-      port && new(session_id: session_id, port: port, host: host)
+    def self.discover(session_id, session_dir:, host: HOST, read_timeout: READ_TIMEOUT)
+      for_sidecar(session_id, live_sidecar(session_dir, host: host), host: host, read_timeout: read_timeout)
     end
 
     # How often a wait for a new worker's Bridge looks: a missing sidecar is
@@ -92,8 +108,8 @@ module Samagotchi
     # @param timeout [Float] seconds
     # @return [BridgeClient, nil] nil when no live sidecar appeared in time
     def self.wait_for(session_id, session_dir:, timeout:, host: HOST)
-      port = poll(timeout, interval: SPAWN_POLL_INTERVAL) { sidecar_port(session_dir, host: host) }
-      port && new(session_id: session_id, port: port, host: host)
+      sidecar = poll(timeout, interval: SPAWN_POLL_INTERVAL) { live_sidecar(session_dir, host: host) }
+      for_sidecar(session_id, sidecar, host: host)
     end
 
     # Call the block every +interval+ seconds until it returns a truthy value
@@ -113,17 +129,27 @@ module Samagotchi
     attr_reader :session_id, :port, :host
 
     # Which worker this client talks to, for EventStream: a rediscovered
-    # client with another key is a new worker. A Bridge's port.
-    def worker_key = @port
-
+    # client with another key is a new worker. A Bridge's port, and a
+    # fingerprint of its secret when it has one: a new worker that got the
+    # old one's port back has another secret, so it is still a new worker.
+    def worker_key = @secret ? "#{@port}-#{Digest::SHA256.hexdigest(@secret)[0, 12]}" : @port
+
+    # @param secret [String, nil] the Bridge's secret, sent in SECRET_HEADER
+    #   with every request (nil: a worker from before secrets, which asks for
+    #   none); from the worker's sidecar (.for_sidecar), never typed
     # @param read_timeout [Numeric] see READ_TIMEOUT
-    def initialize(session_id:, port:, host: HOST, read_timeout: READ_TIMEOUT)
+    def initialize(session_id:, port:, secret:, host: HOST, read_timeout: READ_TIMEOUT)
       @session_id = session_id
       @port = port
+      @secret = secret
       @host = host
       @read_timeout = read_timeout
     end
 
+    # The secret never shows in an inspect (a log line, an error's message).
+    def inspect = "#<#{self.class.name} session_id=#{@session_id.inspect} port=#{@port}>"
+    alias to_s inspect
+
     # POST /session/:id/answer. 200 = recorded, 409 = another client answered
     # first (or the question is gone), 400 = invalid selection, 408
     # deadline_passed = read too late and dropped (see DEADLINE_SHARE), 403
@@ -289,7 +315,7 @@ module Samagotchi
     #   (nil when it isn't JSON); [nil, nil] when no reply came
     def get(path)
       sock = TCPSocket.new(@host, @port)
-      sock.write("GET /session/#{@session_id}/#{path} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\nConnection: close\r\n\r\n")
+      sock.write("GET /session/#{@session_id}/#{path} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\n#{secret_line}Connection: close\r\n\r\n")
       response = read_reply(sock, path)
       sock.close rescue nil
       # A 500 whose text has "200" in it is not a 200.
@@ -332,14 +358,22 @@ module Samagotchi
       # the bridge socket briefly refuses). A few quick bounded retries
       # avoid the silent empty-200 that EventSource would otherwise keep
       # re-opening.
+      status = nil
       STREAM_CONNECT_ATTEMPTS.times do |attempt|
-        sock, = connect_stream(query: query, last_event_id: last_event_id, timeout: header_timeout)
+        sock, status = connect_stream(query: query, last_event_id: last_event_id, timeout: header_timeout)
         break if sock
 
         sleep(0.15 * (attempt + 1))
       end
       return unless sock
 
+      # A refusal (a 403 such as bridge_secret) is no event stream: its JSON
+      # isn't passed on as one.
+      if status == 403
+        sock.close rescue nil
+        return
+      end
+
       begin
         loop do
           if running
@@ -375,11 +409,16 @@ module Samagotchi
     #   nil when the Bridge can't be reached
     def connect_stream(query: "", last_event_id: nil, timeout: nil)
       StreamRequest.open(host: @host, port: @port, path: "/session/#{@session_id}/stream#{query}",
-                         last_event_id: last_event_id, timeout: timeout)
+                         last_event_id: last_event_id, headers: secret_headers, timeout: timeout)
     end
 
     private
 
+    # The request header naming the Bridge's secret (none without one).
+    def secret_headers = @secret ? { SECRET_HEADER => @secret } : {}
+
+    def secret_line = secret_headers.map { |name, value| "#{name}: #{value}\r\n" }.join
+
     # When this client stops waiting for a reply, as epoch seconds (see
     # DEADLINE_SHARE). Wall clock: the worker runs on this machine and reads
     # the same one.
@@ -388,7 +427,7 @@ module Samagotchi
     def post(path, payload, read_body:, read_timeout: @read_timeout)
       sock = TCPSocket.new(@host, @port)
       json_body = JSON.generate(payload)
-      sock.write("POST /session/#{@session_id}/#{path} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\nContent-Type: application/json\r\nContent-Length: #{json_body.bytesize}\r\nConnection: close\r\n\r\n#{json_body}")
+      sock.write("POST /session/#{@session_id}/#{path} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\n#{secret_line}Content-Type: application/json\r\nContent-Length: #{json_body.bytesize}\r\nConnection: close\r\n\r\n#{json_body}")
       reply = read_reply(sock, path, whole: read_body, timeout: read_timeout)
       body = read_body ? reply.split("\r\n\r\n", 2)[1] : nil
       Response.new(status: reply[STATUS_LINE, 1].to_i, body: body)

data/lib/samagotchi/bridge_secret.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Samagotchi
+  # A session Bridge's secret, as both sides name it: the request header
+  # that carries it (Bridge#secret_ok?, BridgeClient), the error a Bridge
+  # answers without it (403), and the one message every client shows for
+  # that refusal.
+  module BridgeSecret
+    # The request header (Bridge's #read_request keeps names lowercased).
+    HEADER = "X-Chi-Bridge"
+    # The 403's error.
+    ERROR = "bridge_secret"
+    # What a request without this Bridge's secret, or with another one, is
+    # told, and what a client shows when it gets that: the asker comes from
+    # a chi that reads no secret, a chi web, an attached terminal or a
+    # session worker (a delegate's parent) started before chi was updated.
+    REFUSED = "the request didn't name this session worker's secret: a chi web, an attached terminal or a session " \
+              "worker started before chi was updated can't reach it; restart chi web, re-attach terminals " \
+              "(chi --attach ID) and restart the older session workers (chi sessions restart ID...)"
+
+    module_function
+
+    # Whether a Bridge reply (+status+, raw +body+) is this refusal.
+    def refused?(status, body)
+      return false unless status.to_i == 403
+
+      parsed = body.is_a?(Hash) ? body : JSON.parse(body.to_s)
+      parsed.is_a?(Hash) && parsed["error"] == ERROR
+    rescue JSON::ParserError
+      false
+    end
+  end
+end

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.119.0
+version: 0.120.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/config.rb

@@ -326,6 +326,9 @@ module Samagotchi
       Entry.new(key: "web.annotate_presets",     yaml_path: %w[web annotate_presets],     type: :string, default: "Agreed|Could you please elaborate?", expose: %i[env config cli], lifecycle: :web_start),
       # What a file ref (a tool row's file, a diff line) opens on this machine: a preset (vscode, vscode-insiders, cursor, zed, none) or a URL template with {path} and an optional {line} (Web::Editor).
       Entry.new(key: "web.editor",               yaml_path: %w[web editor],               type: :string, default: "vscode",        expose: %i[env config cli], lifecycle: :web_start),
+      # The folder chi web starts in (Web::StartDir): its bare page shows that folder's project, and a new session
+      # without a folder (the all view's) starts there. Unset: the folder chi web runs in. chi web --start-dir wins.
+      Entry.new(key: "web.start_dir",            yaml_path: %w[web start_dir],            type: :string, default: nil,             expose: %i[env config], lifecycle: :web_start),
       # Participants (chi share): a new grant's lifetime (Nh or Nd, 1h to 30d), and what a grant without its own
       # takes: its spending cap in dollars ($0 to $1000) and how many of its turns may wait (0 to 20). Read when used.
       Entry.new(key: "web.participants.expires", yaml_path: %w[web participants expires], type: :string, default: "7d", expose: %i[env config], lifecycle: :next_matching_turn_display_poll_write),

data/lib/samagotchi/participant_messages.rb

@@ -10,6 +10,11 @@ module Samagotchi
     TOKEN_REVOKED = "this review link was revoked by the session's owner"
     # 401 token_expired: the grant's time ran out.
     TOKEN_EXPIRED = "this review link expired: ask the session's owner for a new one"
+    # 401 token_bound: a link bound to one account (chi share --identity)
+    # opened by another, or not through the auth proxy (the LAN, this
+    # machine). Never names either identity.
+    TOKEN_BOUND = "this review link is for another account: open it through the proxy, signed in as the person " \
+                  "it was sent to"
     # Either of those, where only that the link ended is known: the
     # worker's cancel_reason "revoked" (participants.json reads them
     # removed or past expires_at), as their chi send --wait reports it.

data/lib/samagotchi/participants.rb

@@ -98,21 +98,29 @@ module Samagotchi
     end
 
     # Invites a participant to +session_id+: the grant (+grants+, a
-    # Web::Grants), the sidecar and the audit line.
+    # Web::Grants), the sidecar and the audit line. A grant bound to
+    # +identity+ needs +public_url+ (the chi web's Web::PublicUrl) with an
+    # identity header: only a request through that proxy can carry it.
     # @return [Web::Grants::Issued]
     # @raise [Web::Grants::Invalid] an archived session, or bad values
+    #   (Unbindable: an identity without such a public_url)
     # @raise [ArgumentError] no such session
-    def invite(grants, session_id:, name:, kind: "human", ttl: nil, cap: nil, state_dir: Session.default_state_dir)
+    def invite(grants, session_id:, name:, kind: "human", ttl: nil, cap: nil, identity: nil, public_url: nil,
+               state_dir: Session.default_state_dir)
       raise ArgumentError, "Session not found: #{session_id}" unless File.exist?(Session.session_file(session_id, state_dir: state_dir))
+
+      identity = Web::Grants.clean_identity(identity) unless identity.nil?
+      raise Web::Grants::Unbindable if !identity.nil? && public_url&.identity_header.nil?
       if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: state_dir))
         raise Web::Grants::Invalid, "session #{session_id[0, 8]} is archived: unarchive it to invite anyone"
       end
 
-      issued = grants.issue(session_id: session_id, name: name, kind: kind, ttl: ttl, cap: cap,
+      issued = grants.issue(session_id: session_id, name: name, kind: kind, ttl: ttl, cap: cap, identity: identity,
                             on_write: sidecar_writer(state_dir, [session_id]))
       grant = issued.grant
       log(session_id, :issued, state_dir: state_dir, participant: grant.id, name: grant.name, kind: grant.kind,
-                               role: grant.role, expires_at: grant.expires_at, cap: grant.spend_cap)
+                               role: grant.role, expires_at: grant.expires_at, cap: grant.spend_cap,
+                               **(grant.identity ? { identity: grant.identity } : {}))
       issued
     end
 
@@ -148,11 +156,13 @@ module Samagotchi
     # session nobody was invited to.
     # A grants store that doesn't read (Web::Grants::Corrupt) doesn't stop
     # the archive or delete: its links already find no grant, and the
-    # store itself says so (Log.warn) until it's fixed.
+    # store itself says so (Log.warn) until it's fixed. Nor does one a newer
+    # chi wrote (Newer): chi web's gate refuses a grant whose session is
+    # archived or gone even when it can't write the revoke.
     def end_sessions(session_ids, by:, state_dir: Session.default_state_dir)
       grants = Web::Grants.new(Web::Grants.path(state_dir: state_dir))
       session_ids.each { |sid| revoke(grants, session_id: sid, by: by, state_dir: state_dir) }
-    rescue Web::Grants::Corrupt
+    rescue Web::Grants::Unwritable
       nil
     end
   end

data/lib/samagotchi/review_command.rb

@@ -110,7 +110,9 @@ module Samagotchi
       @stdout.puts("#{id}  #{what}#{subjects} · idle")
       @stdout.puts("warning: #{created.model_warning}") if created.model_warning
       @stdout.puts("open it: #{@access.invocation.open_it(id[0, 8])}")
-      @stdout.puts("invite someone: #{@access.invocation.command("share #{id[0, 8]} --name NAME")}")
+      # Behind a proxy that names the user, a link can be bound to them.
+      identity = " --identity EMAIL" if @access.identity_header
+      @stdout.puts("invite someone: #{@access.invocation.command("share #{id[0, 8]} --name NAME#{identity}")}")
     end
 
     def refused(message)

data/lib/samagotchi/run_options.rb

@@ -14,7 +14,7 @@ module Samagotchi
   module RunOptions
     # The flags an underscored spelling is refused for (--recap_base_url),
     # with the config registry's.
-    KNOWN = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --dir --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token --tunnel].freeze
+    KNOWN = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --dir --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token --tunnel --start-dir].freeze
 
     module_function
 
@@ -223,6 +223,8 @@ module Samagotchi
         opts.on("--tunnel PROVIDER", %w[tailscale],
                 "`chi web`: reach it over https from your tailnet through Tailscale Serve (never Funnel), for this run; " \
                 "turned off on exit") { |v| options[:tunnel] = v }
+        opts.on("--start-dir DIR", "`chi web`: the folder it starts in (web.start_dir; default: this one): its page opens on that " \
+                                   "folder's project, and a new session from the all view starts there") { |v| options[:start_dir] = v }
         opts.on("--scope VALUE", %w[project all],
                 "Which sessions `chi web` and `chi sessions list` show: project (the default: this folder's git project; " \
                 "every session outside a repo) or all") { |v| options[:scope] = v }

data/lib/samagotchi/session_access/contract.rb

@@ -123,6 +123,9 @@ module Samagotchi
         "share --agent" => SUPPORTED,
         "share --expires" => SUPPORTED,
         "share --cap" => SUPPORTED,
+        # A chi web without bound grants (Remote#invite checks its
+        # bound_grants feature) is refused, never sent the identity.
+        "share --identity" => SUPPORTED,
         "share cap" => SUPPORTED,
         "share ls" => SUPPORTED,
         "share ls --format" => SUPPORTED,
@@ -150,7 +153,7 @@ module Samagotchi
                         --llm-context-budget --toolkit --tool --no-tool --set --parent-answers --no-interrupt
                         --no-default-input --dir --version -h --help],
         LOCAL_ONLY => %w[--no-shared --non-interactive -v --verbose --append-system-prompt --memory --mute --profile
-                         --port --open --new-token --tunnel --scope --web-markdown --no-web-markdown]
+                         --port --open --new-token --tunnel --start-dir --scope --web-markdown --no-web-markdown]
       }.freeze
       # A short run flag's name in a refusal.
       RUN_WORDS = { "-v" => "--verbose" }.freeze

data/lib/samagotchi/session_access/local.rb

@@ -370,12 +370,16 @@ module Samagotchi
       # and port when one runs on the LAN (the port it recorded, else
       # web.port), else 127.0.0.1 (+lan+ false: the link opens on this
       # machine only).
+      # A grant bound to +identity+ needs that public_url with an identity
+      # header (Participants.invite).
       # @return [Invitation]
       # @raise [ArgumentError] no such session
-      # @raise [BadRequest] a bad name, kind or ttl, an archived session
-      def invite(id, name:, kind:, ttl: nil, cap: nil)
-        issued = Participants.invite(grants, session_id: id, name: name, kind: kind, ttl: ttl, cap: cap, state_dir: state_dir!)
+      # @raise [BadRequest] a bad name, kind, ttl or identity, an archived
+      #   session, an identity with no proxy to check it
+      def invite(id, name:, kind:, ttl: nil, cap: nil, identity: nil)
         public_url = configured_public_url
+        issued = Participants.invite(grants, session_id: id, name: name, kind: kind, ttl: ttl, cap: cap,
+                                             identity: identity, public_url: public_url, state_dir: state_dir!)
         web = public_url ? nil : local_web
         link = if public_url then public_url.link(link_code(issued), "s=#{id}")
                else "http://#{web.ip || "127.0.0.1"}:#{web.port}/?token=#{issued.token}#s=#{id}"
@@ -387,6 +391,13 @@ module Samagotchi
         raise BadRequest.new(e.message, code: "invalid_participant")
       end
 
+      # The header this machine's chi web names the signed-in user in (a
+      # link can be bound to an email: chi share --identity), nil when it
+      # has no such proxy: config's web.public_url with
+      # web.proxy.identity_header, or a running chi web --tunnel's.
+      # @return [String, nil]
+      def identity_header = configured_public_url&.identity_header
+
       # @return [Array<ParticipantView>] the ones it revoked
       def revoke_participants(id = nil, participant: nil)
         Participants.revoke(grants, session_id: id, id: participant, state_dir: state_dir!)
@@ -440,7 +451,7 @@ module Samagotchi
         configured = Config.get("web.public_url")
         return Web::Running.live_public_url(path: Web::Running.path(state_dir: state_dir!)) if configured.to_s.strip.empty?
 
-        Web::PublicUrl.from_config(url: configured)
+        Web::PublicUrl.from_config(url: configured, identity_header: Config.get("web.proxy.identity_header"))
       rescue Web::PublicUrl::Invalid
         nil
       end

data/lib/samagotchi/session_access/remote.rb

@@ -122,7 +122,7 @@ module Samagotchi
         end
       end
 
-      ACCESS_ERRORS = [TokenRevoked, TokenExpired, NotPermitted, TooManyTurns, CapReached].freeze
+      ACCESS_ERRORS = [TokenRevoked, TokenExpired, TokenBound, NotPermitted, TooManyTurns, CapReached].freeze
 
       # --- ids and sessions
 
@@ -252,15 +252,37 @@ module Samagotchi
       end
 
       # @param ttl [Integer, nil] seconds; nil: the grant's default
+      # @param identity [String, nil] bind the grant to this email: only a
+      #   chi web with bound grants (BOUND_FEATURE) is asked; an older one
+      #   would ignore it and issue a grant anyone could open
       # @return [Invitation]
-      # @raise [BadRequest] a bad name, kind or ttl, an archived session
-      def invite(id, name:, kind:, ttl: nil, cap: nil)
-        reply = request(:post, "#{session_path(id)}/participants", body: { name: name, kind: kind, ttl: ttl, cap: cap }.compact)
+      # @raise [BadRequest] a bad name, kind, ttl or identity, an archived
+      #   session, an identity that chi web has no proxy to check
+      # @raise [RemoteTooOld] an identity, and a chi web without bound grants
+      def invite(id, name:, kind:, ttl: nil, cap: nil, identity: nil)
+        require_feature!(BOUND_FEATURE) unless identity.nil?
+        body = { name: name, kind: kind, ttl: ttl, cap: cap, identity: identity }.compact
+        reply = request(:post, "#{session_path(id)}/participants", body: body)
         raise_refusal(reply) unless reply.status == 201
 
         json = reply.json
-        Invitation.new(participant: ParticipantView.from_h(json.fetch("participant")), token: json.fetch("token"),
-                       link: json.fetch("link"), lan: json["lan"] == true, warning: json["warning"])
+        participant = ParticipantView.from_h(json.fetch("participant"))
+        check_bound!(id, participant, identity)
+        Invitation.new(participant: participant, token: json.fetch("token"), link: json.fetch("link"),
+                       lan: json["lan"] == true, warning: json["warning"])
+      end
+
+      # Web::App::BOUND_FEATURE: POST …/participants takes an identity.
+      BOUND_FEATURE = "bound_grants"
+
+      # The header that chi web names the signed-in user in (GET
+      # /api/info's proxy), nil when it has no such proxy, or is a chi
+      # web from before it said.
+      # @return [String, nil]
+      def identity_header
+        check_server!
+        header = @proxy.is_a?(Hash) ? @proxy["identity_header"] : nil
+        header.is_a?(String) && !header.empty? ? header : nil
       end
 
       # Revokes one participant (+participant+), a session's, or with no
@@ -602,6 +624,7 @@ module Samagotchi
         if reply.json.is_a?(Hash)
           @version = reply.json["version"]
           @features = Array(reply.json["features"])
+          @proxy = reply.json["proxy"]
         end
         problem = Remote.info_problem(@entry, reply)
         raise problem if problem
@@ -611,6 +634,18 @@ module Samagotchi
 
       def too_old(version) = Remote.too_old_message(@entry, version)
 
+      # A grant asked bound to +identity+ came back bound to it, or is
+      # revoked at once (its link never printed) and refused: belt and
+      # braces behind BOUND_FEATURE.
+      # @raise [RemoteFailed]
+      def check_bound!(id, participant, identity)
+        return if identity.nil? || participant.identity == identity.to_s.strip.downcase
+
+        revoke_participants(id, participant: participant.id)
+        raise RemoteFailed, "#{@entry.label}: its chi web issued #{participant.id} unbound, so chi revoked it: " \
+                            "update chi there (chi update)"
+      end
+
       def strategy_or_hard(json) = strategy_of(json) || Guardrails::ParentPolicy.strategy(Guardrails::ParentPolicy::HARD)
 
       # chi web's 404 for a path no route takes (#serve_static's), not a
@@ -730,7 +765,7 @@ module Samagotchi
       # chi web's answer/dismiss reply as the worker's Bridge would have
       # given it: 503 not_live is no worker (nil), 504 the Bridge's 408, 501
       # not_supported its 404 for a route it lacks, 409 question_not_pending
-      # its 409; the rest as it came.
+      # its 409, 502 bridge_secret its 403 (BridgeSecret); the rest as it came.
       def bridge_reply(reply)
         json = reply.json.is_a?(Hash) ? reply.json : {}
         case [reply.status, json["error"]]
@@ -738,6 +773,7 @@ module Samagotchi
         in [404, "not_found"] then nil
         in [504, _] then BridgeClient::Response.new(status: 408, body: reply.body)
         in [501, "not_supported"] then BridgeClient::Response.new(status: 404, body: JSON.generate(json.merge("error" => "not_found")))
+        in [502, BridgeSecret::ERROR] then BridgeClient::Response.new(status: 403, body: reply.body)
         else BridgeClient::Response.new(status: reply.status, body: reply.body)
         end
       end

data/lib/samagotchi/session_access.rb

@@ -51,6 +51,13 @@ module Samagotchi
       def initialize(label) = super("#{label}: #{ParticipantMessages::TOKEN_EXPIRED}")
     end
 
+    # 401 token_bound: a link bound to one account, used without that
+    # account's sign-in (chi --remote doesn't go through the proxy).
+    class TokenBound < AuthRefused
+      CODE = "token_bound"
+      def initialize(label) = super("#{label}: #{ParticipantMessages::TOKEN_BOUND}")
+    end
+
     # 403 not_permitted: a participant's token on a route only the session's
     # owner may use.
     class NotPermitted < RemoteFailed
@@ -94,8 +101,11 @@ module Samagotchi
     # (Web::Grants::Grant#public_h): never its token or digest. +state+
     # "active", "revoked" or "expired".
     # +cap+ dollars and +queue+ turns (nil from a chi web before them).
+    # +identity+ the email the grant is bound to, nil for any.
     ParticipantView = Data.define(:id, :session_id, :kind, :name, :role, :created_at, :expires_at, :revoked_at,
-                                  :revoked_by, :last_used_at, :state, :cap, :queue) do
+                                  :revoked_by, :last_used_at, :state, :cap, :queue, :identity) do
+      def initialize(identity: nil, **) = super
+
       def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key] || hash[key.to_s]] })
     end
 

data/lib/samagotchi/session_manager.rb

@@ -689,7 +689,7 @@ module Samagotchi
         raise RestartRefused.new(session_id, :unsupported, version: sidecar.version)
       end
 
-      reply = BridgeClient.new(session_id: session_id, port: sidecar.port).request_exit(client_id: client_id, restart: true)
+      reply = BridgeClient.for_sidecar(session_id, sidecar).request_exit(client_id: client_id, restart: true)
       raise RestartRefused.new(session_id, reply.json&.fetch("reason", nil) || :failed) if reply.status == 409
       raise RestartRefused.new(session_id, :failed) unless reply.status == 200
 

data/lib/samagotchi/sessions_command.rb

@@ -371,8 +371,7 @@ module Samagotchi
     # @return [Array(Hash, nil, Boolean, String, nil)]
     def stats_snapshot_for(session)
       dir = Samagotchi::Session.session_dir(session.id)
-      if (port = Samagotchi::BridgeClient.sidecar_port(dir))
-        client = Samagotchi::BridgeClient.new(session_id: session.id, port: port, read_timeout: STATS_TIMEOUT)
+      if (client = Samagotchi::BridgeClient.discover(session.id, session_dir: dir, read_timeout: STATS_TIMEOUT))
         body = client.get_json("stats")&.dig("metrics")
         if body.is_a?(Hash)
           return [TerminalUI::EventRenderer.deep_symbolize_keys(body), true, nil]