samagotchi 0.119.0 → 0.121.0

data/lib/samagotchi/bridge.rb

@@ -5,8 +5,10 @@ require "json"
 require "uri"
 require "fileutils"
 require "securerandom"
+require "openssl"
 require "time"
 require_relative "atomic_file"
+require_relative "bridge_secret"
 require_relative "delivery"
 require_relative "session_inbox"
 
@@ -47,8 +49,10 @@ module Samagotchi
   #   `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
-  #   turn-execution (RCE). Documented, not fixed.
+  # * Binds 127.0.0.1 only, and answers only a request that names its secret
+  #   (#secret_ok?): a random one per Bridge, in the worker's 0600 bridge.json,
+  #   which only this machine's user can read. Binding 0.0.0.0 would still put
+  #   remote turn-execution (RCE) one leaked secret away: don't.
   # * Optional at runtime: this module is never loaded unless explicitly
   #   engaged as a transport.
   class Bridge
@@ -67,6 +71,12 @@ module Samagotchi
     MAX_BODY_BYTES = 1_000_000
     # A request's deadline (see #handle_post_turn) that isn't epoch seconds.
     BAD_DEADLINE = [{ "Allow" => "POST" }, 400, { error: "bad_deadline", detail: "deadline must be epoch seconds" }].freeze
+    # The request header that names the Bridge's secret, lowercased as #read_request keeps it.
+    SECRET_HEADER = BridgeSecret::HEADER.downcase
+    # Bytes of randomness in a Bridge's secret (hex in bridge.json: twice as many characters).
+    SECRET_BYTES = 32
+    # What a request without this Bridge's secret, or with another one, is told (403 bridge_secret).
+    SECRET_REFUSED = BridgeSecret::REFUSED
 
     # @param engine [Samagotchi::Engine] the owning engine (must already live
     #   in this process)
@@ -130,6 +140,9 @@ module Samagotchi
       @pending_card = PendingCard.new(session_dir)
       @heartbeat_interval = heartbeat_interval
       @epoch = SecureRandom.hex(4)
+      # Only in bridge.json (0600) and this process: never logged, never in an
+      # event, a reply or the session's files.
+      @secret = SecureRandom.hex(SECRET_BYTES)
 
       @capture_handle = nil
       @server = nil
@@ -137,8 +150,8 @@ module Samagotchi
       @connection_threads = []
       @stopped = false
       @mutex = Monitor.new
-      @proxied_log_mutex = Mutex.new
-      @proxied_logged_at = nil
+      @refused_log_mutex = Mutex.new
+      @refused_logged_at = {}
       @open_streams = 0
       # Open streams by the client_id a stream named (`?client_id=`); web
       # tabs, through the `chi web` proxy, name none.
@@ -146,6 +159,10 @@ module Samagotchi
       @last_client_activity_at = monotonic_now
     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
+
     # @return [Boolean] whether the server has been stopped.
     def stopped?
       @mutex.synchronize { @stopped }
@@ -442,7 +459,6 @@ module Samagotchi
         request = read_request(io)
         break if request.nil?
 
-        note_client_activity
         started = monotonic_now
 
         method = request[:method].to_s.upcase
@@ -455,22 +471,37 @@ module Samagotchi
         if request[:too_large]
           write_json(io, 413, { "Connection" => "close" }, { error: "too_large", detail: "request body over #{MAX_BODY_BYTES} bytes" })
           break
+        # A refusal closes the connection, as its Connection: close says: a
+        # client that asked to keep it open (a stream's keep-alive) reads
+        # the refusal to its end at once rather than waiting.
         elsif browser_request?(headers)
           write_json(io, 403, nil, { error: "cross_origin", detail: "the bridge answers chi's own clients only" })
+          break
         elsif proxied_request?(headers)
-          note_proxied_refused(request[:path])
+          note_refused(:proxied, "proxied_refused", request[:path])
           write_json(io, 403, nil, { error: "proxied", detail: "the bridge answers chi's own clients on this machine, " \
                                                                "never a request through a proxy" })
+          break
+        elsif !secret_ok?(headers)
+          note_refused(:secret, "secret_refused", request[:path])
+          write_json(io, 403, nil, { error: BridgeSecret::ERROR, detail: SECRET_REFUSED })
+          break
+        # From here on a client of this worker (it named the secret): only its
+        # requests keep the worker from its idle exit, never a refused one's
+        # (an older chi web's polls, a scan through a forward).
         elsif route.nil?
+          note_client_activity
           write_json(io, 404, { "Allow" => "GET, POST" },
                      { error: "not_found", path: request[:path] })
         elsif route.first == :stream
+          note_client_activity
           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, route.last, last_event_id: cursor, snapshot: snapshot_requested?(request[:query]),
                                     client_id: stream_client_id(request[:query]), raw: raw_requested?(request[:query]))
           break # SSE owns the connection until the client disconnects.
         else
+          note_client_activity
           payload, status, body = dispatch(route.first, route.last, request[:body], request[:query])
           write_json(io, status, payload, body)
         end
@@ -554,15 +585,26 @@ module Samagotchi
     # web's stream proxy forwards Last-Event-ID only (ProxyStreamBody).
     def proxied_request?(headers) = headers.keys.any? { |name| ProxyTrace.header?(name) }
 
-    PROXIED_LOG_INTERVAL = 60.0
+    REFUSED_LOG_INTERVAL = 60.0
+
+    # Whether the request names this Bridge's secret (SECRET_HEADER), compared
+    # in constant time. Every route asks for it, the stream and the read-only
+    # ones too: what they show is the session itself.
+    def secret_ok?(headers)
+      given = headers[SECRET_HEADER]
+      given.is_a?(String) && OpenSSL.secure_compare(given, @secret)
+    end
 
-    # At most once a minute: a scan through a forward would fill the log.
-    def note_proxied_refused(path)
+    # A refusal's log line, at most once a minute per +kind+: a scan through
+    # a forward, or an old chi web's every poll, would fill the log. The path
+    # only, never a header.
+    def note_refused(kind, event, path)
       now = monotonic_now
-      due = @proxied_log_mutex.synchronize do
-        (@proxied_logged_at.nil? || now - @proxied_logged_at >= PROXIED_LOG_INTERVAL).tap { |fresh| @proxied_logged_at = now if fresh }
+      due = @refused_log_mutex.synchronize do
+        last = @refused_logged_at[kind]
+        (last.nil? || now - last >= REFUSED_LOG_INTERVAL).tap { |fresh| @refused_logged_at[kind] = now if fresh }
       end
-      Log.warn(:bridge, "proxied_refused", path: path) if due
+      Log.warn(:bridge, event, path: path) if due
     end
 
     def browser_request?(headers)
@@ -1455,9 +1497,10 @@ module Samagotchi
       # version: the chi this worker runs (chi update and the web's badge
       # report older ones); features: what a client may ask of it; epoch:
       # this worker's, as its event ids carry it.
+      # secret: what every request must name (#secret_ok?).
       WorkerSidecar.new(port: @port, bind: @bind, session_id: @session_id, started_at: Time.now.iso8601(3),
                         version: Samagotchi::VERSION, input_format: @input_format, features: FEATURES,
-                        epoch: @epoch).write(session_dir)
+                        epoch: @epoch, secret: @secret).write(session_dir)
     rescue StandardError => e
       Log.warn(:bridge, "sidecar_write_failed", echo: "Bridge: failed to write #{WorkerSidecar::FILE}: #{e.class}: #{e.message}", error: e.class.name)
     end

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/claude-peer/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: claude-peer
-version: 0.4.3
+version: 0.4.4
 scope: system
 description: "Pair this session with a Claude Code session you work with: the claude_send tool and /claude send it a part of the work (a plan step, a diff, a finding) to validate or as context, and Claude's answer comes back as the claude-outbox context; /claude install-skill installs Claude's chi-peer skill, which pairs"
 trust_level: reviewed
@@ -12,7 +12,7 @@ plugin:
   file: plugin.rb
   sha256: sha256:50f427d3862ae9d0d15693b4d887c528162b96c0320cc663df89d59d830d4660
 scripts:
-  pair: sha256:bd850e8091098e249ac5b9b04a95a4d8a0dd8501cf9d58639a47d4f3bce1d757
+  pair: sha256:106d5b44020602fcd2d8065da30d10e1043e30c1b31ea82b4f27f7f79ada6592
   chi-peer-SKILL.md: sha256:b9366f8f4aee9c54d209368ce421eab7b971c03c75efab0415d1988fd40f9e60
 # The plugin needs Samagotchi::Plugin::Peer and chi.peer_source (chi 0.67.0).
 # An agreeing answer's closing wake (the skills say an OK wakes chi once)

data/lib/samagotchi/bundles/claude-peer/scripts/pair

@@ -147,6 +147,6 @@ attach claude-outbox --why "Claude's answers to what you sent it (claude-peer)"
 if [ -z "$inbox" ]; then
   echo "paired with chi $id (socket $sock)"
 else
-  echo "paired with chi $id (socket $inbox on chi's machine, forwarded from $sock)"
+  echo "paired with chi $id (socket $inbox on chi's machine, forwarded to this Claude's $sock)"
 fi
 $chi context ls "$id"

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

@@ -1,10 +1,10 @@
 ---
 name: dev
-version: 0.7.2
+version: 0.7.3
 scope: system
 description: "Developer tools"
 trust_level: reviewed
-requires_chi: ">= 0.107.0"
+requires_chi: ">= 0.121.0"
 includes:
 - known-names
 - mcp

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

@@ -1,12 +1,12 @@
 ---
 name: mcp
-version: 0.7.1
+version: 0.7.2
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session; their tools go into chi's tool index: the model searches them with find_tools and calls one with call_tool (<server>/<tool>); /mcp lists them"
 trust_level: reviewed
 files: {}
 plugin:
   file: plugin.rb
-  sha256: sha256:67b1ed9337236deb366459aaaed4e49f0d3122a0b38f3ff9328babcd332c0182
+  sha256: sha256:c4bb4cf99ad43168ea68c25283a153c5dea1e5be123743c8a4c1278c16b5ea90
 # 0.67.0 is the release with chi.tool_source (the core tool index the bundle publishes into).
-requires_chi: ">= 0.67.0"
+requires_chi: ">= 0.121.0"

data/lib/samagotchi/bundles/mcp/plugin.rb

@@ -354,6 +354,7 @@ class Plugin
   def register(chi)
     @chi = chi
     ctx = chi.ctx
+    @ctx = ctx
     configs = @settings["servers"]
     configs = {} unless configs.is_a?(Hash)
     unless configs.empty?
@@ -952,7 +953,10 @@ class Plugin
     return "No servers. Add them in config.yml under `bundles: mcp: servers:` (docs/plugins.md, The mcp bundle)." if @servers.empty?
 
     servers = @servers.map do |server|
-      head = "**#{server.name}**: #{state_text(server)}"
+      marker = if @source && !@source.declared_groups.include?(server.name)
+                 " (not in toolkit #{@ctx.toolkit})"
+               end
+      head = "**#{server.name}**: #{state_text(server)}#{marker}"
       # Sorted: a server lists its tools in its own (often grouped) order.
       tools = server.tools.sort_by(&:name).map { |t| ["- `#{t.server}/#{t.name}`", mark(t)].compact.join(" ") }
       tools.empty? ? head : "#{head}\n#{tools.join("\n")}"

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

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.119.0
+version: 0.121.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/engine.rb

@@ -377,6 +377,7 @@ module Samagotchi
       # A cut tool output is saved whole in the session's folder.
       @kernel.session_dir = -> { @session&.id && Session.session_dir(@session.id, state_dir: session_state_dir) }
       @kernel.guardrail_gate = @guardrail_wiring.gate
+      @kernel.participant_turn = -> { Steer.participant_author?(turn_author) }
       # The turn-end warm-up; the kernel asks it for a slot pin per request.
       @prompt_warmup = PromptWarmup.new
       @kernel.warmup = @prompt_warmup

data/lib/samagotchi/kernel_loop.rb

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

data/lib/samagotchi/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/plugin/api.rb

@@ -308,12 +308,14 @@ module Samagotchi
       # toolkit.default, ctx.use_toolkit): +base+'s tools (a toolkit chi or
       # a bundle has) with +add+ declared and +remove+ left out, and
       # +prompt+: text the sessions on it get in their system prompt (nil:
-      # its base's, "" none; at most Toolkit::PROMPT_MAX characters). A
+      #   its base's, "" none; at most Toolkit::PROMPT_MAX characters);
+      #   +groups+: MCP source group names/globs (nil inherits its base).
+      #   A
       # name chi (full, lean, child) or another bundle has is a load error,
       # and so is a prompt that isn't text or is too long; a base that
       # doesn't resolve leaves the sessions on it with every tool
       # (Toolkit#resolve).
-      def toolkit(name, base:, add: [], remove: [], prompt: nil)
+      def toolkit(name, base:, add: [], remove: [], prompt: nil, groups: nil)
         name = name.to_s
         raise ArgumentError, "toolkit name #{name.inspect} must be a-z, 0-9, _ and -" unless name.match?(TOOLKIT_NAME)
 
@@ -327,7 +329,8 @@ module Samagotchi
         end
         raise ArgumentError, "toolkit #{name} is declared twice" if @toolkits.any? { |kit| kit.name == name }
 
-        @toolkits << Toolkit::Kit.new(name: name, base: base, add: add, remove: remove, prompt: prompt, source: @bundle)
+        @toolkits << Toolkit::Kit.new(name: name, base: base, add: add, remove: remove, prompt: prompt,
+                                      groups: groups, source: @bundle)
         nil
       end