samagotchi 0.102.0 → 0.104.0

data/lib/samagotchi/bridge_client/event_stream.rb

@@ -19,11 +19,23 @@ module Samagotchi
     # it without that event.
     #
     # With +rediscover+, a failed connection first looks for the session's
-    # live worker (its sidecar): a new one (a restart) is followed from its
-    # snapshot, announced by a synthetic `{"type" => "worker_changed",
-    # "port" => ...}` first, since its event ids start over. (A new worker
-    # on the old one's port is the plain reconnect: its Bridge can't replay
-    # the old ids and sends a reset.)
+    # live worker (its sidecar): a new one (a restart: a client with another
+    # BridgeClient#worker_key) is followed from its snapshot, announced by a
+    # synthetic `{"type" => "worker_changed", "port" => ...}` first, since its
+    # event ids start over. (A new worker on the old one's port is the plain
+    # reconnect: its Bridge can't replay the old ids and sends a reset.)
+    # Rediscovery may also give a reason ([nil, reason] while it retries,
+    # [:gone, reason] to stop): the stream_closed event carries the last one.
+    #
+    # Off by default, for a stream through chi web (SessionAccess::
+    # WebBridgeClient), where the client stays the same object across
+    # workers: +epoch_watch+ (a frame whose id has another epoch than the
+    # cursor's is a new worker: worker_changed first, the client's key
+    # updated), +announce_retries+ (stream_retrying once a reconnect fails
+    # and rediscovery neither moved nor ended the stream, stream_resumed
+    # once a stream answers again), +idle_timeout+ (no byte, not even
+    # the Bridge's 15 s ping, for that long: a half-open connection,
+    # reconnected with the cursor).
     class EventStream
       DEFAULT_RECONNECT_DELAYS = [0.1, 0.25, 0.5, 1.0, 2.0].freeze
       # Long enough for a restarted worker to boot (its Engine, the plugins).
@@ -40,12 +52,26 @@ module Samagotchi
       # @param reconnect_delays [Array<Float>] sleeps between failed attempts;
       #   one more failure than there are delays gives up
       # @param rediscover [#call, nil] → a BridgeClient for the session's live
-      #   worker now, nil when there is none yet, or :gone to give up now
+      #   worker now, nil when there is none yet, or :gone to give up now;
+      #   or AttachLink#live_worker's pair, [one of those, a reason]
+      # @param epoch_watch [Boolean] see the class comment; the client takes
+      #   worker_key= then
+      # @param announce_retries [Boolean] see the class comment
+      # @param idle_timeout [Float, nil] seconds; nil: a quiet stream is
+      #   never cut (a Bridge on this machine)
       # @yieldparam event [Hash] string-keyed event
       def initialize(client, snapshot: true, client_id: nil, reconnect_delays: DEFAULT_RECONNECT_DELAYS, rediscover: nil,
-                     &on_event)
+                     epoch_watch: false, announce_retries: false, idle_timeout: nil, &on_event)
         @client = client
+        # The worker followed: a client that keeps its object across
+        # workers (epoch_watch) changes its key, not itself.
+        @worker_key = client.worker_key
         @rediscover = rediscover
+        @epoch_watch = epoch_watch
+        @announce_retries = announce_retries
+        @idle_timeout = idle_timeout
+        @retrying = false
+        @reason = nil
         params = []
         params << %w[snapshot 1] if snapshot
         params << ["client_id", client_id] if client_id
@@ -96,18 +122,23 @@ module Samagotchi
 
           if outcome == :events
             failures = 0
+            @reason = nil
             next
           end
 
+          # Rediscovery first: a stopped session or a new worker is no
+          # retry to announce (a stop prints its line alone).
           case rediscover_worker
           when :moved
             failures = 0
+            @reason = nil
             next
-          when :gone then return finish("unreachable")
+          when :gone then return finish(@reason || "unreachable")
           end
+          announce_retry
 
           failures += 1
-          return finish("unreachable") if failures > @reconnect_delays.size
+          return finish(@reason || "unreachable") if failures > @reconnect_delays.size
 
           sleep(@reconnect_delays[failures - 1])
         end
@@ -125,14 +156,20 @@ module Samagotchi
         return :unknown_session if status == 404
         return :unreachable unless status == 200
 
+        # Back as soon as the stream answers: a replay may bring nothing
+        # (the session was quiet), and the next frame could be minutes away.
+        announce_resumed
         yielded = false
         parser = SSEParser.new
         loop do
+          raise Errno::ETIMEDOUT if @idle_timeout && !sock.wait_readable(@idle_timeout)
+
           chunk = sock.readpartial(4096)
           parser.feed(chunk) do |frame|
             event = parse(frame[:data])
             next unless event
 
+            watch_epoch(frame[:id]) if @epoch_watch
             @last_event_id = frame[:id] if frame[:id]
             yielded = true
             @on_event.call(event)
@@ -172,18 +209,55 @@ module Samagotchi
       def rediscover_worker
         return nil unless @rediscover
 
-        found = @rediscover.call
+        found, reason = @rediscover.call
+        @reason = reason if reason
         return :gone if found == :gone
-        return nil if found.nil? || found.port == @client.port
+        return nil if found.nil? || found.worker_key == @worker_key
 
         @client = found
         @last_event_id = nil
-        @on_event.call({ "type" => "worker_changed", "port" => found.port }) unless closed?
+        moved(found.port, found.worker_key)
         :moved
       rescue StandardError
         nil
       end
 
+      # The frame +id+'s epoch (EventId: "<seq>-<epoch>") differs from the
+      # cursor's: a new worker answers the old cursor (its Bridge sends a
+      # reset next, or this is it). Announced before the frame.
+      def watch_epoch(id)
+        epoch = id.to_s[/-(\w+)\z/, 1]
+        cursor = @last_event_id.to_s[/-(\w+)\z/, 1]
+        return if epoch.nil? || cursor.nil? || epoch == cursor
+
+        @client.worker_key = epoch
+        moved(nil, epoch)
+      end
+
+      # Following another worker now: its key, and the worker_changed event
+      # (with its epoch for a stream through chi web).
+      def moved(port, key)
+        @worker_key = key
+        event = { "type" => "worker_changed", "port" => port }
+        event["epoch"] = key if @epoch_watch
+        @on_event.call(event) unless closed?
+      end
+
+      # A reconnect failed: said once, until a frame comes again.
+      def announce_retry
+        return if !@announce_retries || @retrying || closed?
+
+        @retrying = true
+        @on_event.call({ "type" => "stream_retrying" })
+      end
+
+      def announce_resumed
+        return unless @retrying
+
+        @retrying = false
+        @on_event.call({ "type" => "stream_resumed" })
+      end
+
       def finish(reason)
         @on_event.call({ "type" => "stream_closed", "reason" => reason }) unless closed?
       end

data/lib/samagotchi/bridge_client/stream_request.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Samagotchi
+  class BridgeClient
+    # The GET that opens an event stream, written by hand over a TCPSocket,
+    # and its response headers read up to the body: BridgeClient's stream
+    # (the worker's Bridge, `/session/:id/stream`), and any other server that
+    # serves the same SSE body at its own path with its own extra headers.
+    # TLS would plug in here.
+    module StreamRequest
+      # A reply's status line; its code is group 1 (BridgeClient::STATUS_LINE).
+      STATUS_LINE = %r{\AHTTP/1\.[01] (\d{3})}
+
+      module_function
+
+      # Open the stream and read past the response headers.
+      # @param host [String]
+      # @param port [Integer]
+      # @param path [String] the request path with its query
+      # @param last_event_id [String, nil] the reconnect cursor
+      # @param headers [Hash{String => String}] extra request headers, after
+      #   Last-Event-ID
+      # @param timeout [Float, nil] give up when the headers aren't all in by then
+      # @return [Array(TCPSocket, Integer, Hash), nil] the socket positioned
+      #   at the body, the HTTP status and the response headers (names in
+      #   lower case), or nil when the server can't be reached
+      def open(host:, port:, path:, last_event_id: nil, headers: {}, timeout: nil)
+        sock = TCPSocket.new(host, port)
+        sock.write(request(host: host, port: port, path: path, last_event_id: last_event_id, headers: headers))
+        deadline = timeout && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout)
+        status = header_line(sock, deadline).to_s[STATUS_LINE, 1].to_i
+        received = {}
+        while (line = header_line(sock, deadline))
+          break if line.strip.empty?
+
+          name, value = line.split(":", 2)
+          received[name.strip.downcase] = value.to_s.strip if value
+        end
+        [sock, status, received]
+      rescue SystemCallError, SocketError, IOError
+        sock&.close rescue nil
+        nil
+      end
+
+      # The request's bytes.
+      # @return [String]
+      def request(host:, port:, path:, last_event_id: nil, headers: {})
+        lei = last_event_id.to_s.strip
+        last_event_line = lei.empty? ? "" : "Last-Event-ID: #{lei}\r\n"
+        extra = headers.map { |name, value| "#{name}: #{value}\r\n" }.join
+        "GET #{path} HTTP/1.1\r\nHost: #{host}:#{port}\r\nAccept: text/event-stream\r\n#{last_event_line}#{extra}" \
+          "Connection: keep-alive\r\n\r\n"
+      end
+
+      # One line of the response headers, or nil at EOF; raises
+      # Errno::ETIMEDOUT once +deadline+ (monotonic, nil: none) has passed. A
+      # line read in pieces, so a server that stops mid-line can't hold it.
+      def header_line(sock, deadline)
+        return sock.gets unless deadline
+
+        line = +""
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise Errno::ETIMEDOUT unless remaining.positive? && sock.wait_readable(remaining)
+
+          char = sock.getc
+          return line.empty? ? nil : line if char.nil?
+
+          line << char
+          return line if char == "\n"
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/bridge_client.rb

@@ -5,8 +5,10 @@ require "socket"
 
 require_relative "worker_sidecar"
 require_relative "delivery"
+require_relative "chi_invocation"
 require_relative "bridge_client/sse_parser"
 require_relative "bridge_client/event_stream"
+require_relative "bridge_client/stream_request"
 
 module Samagotchi
   # Client side of a session worker's Bridge: the 127.0.0.1 HTTP + SSE server
@@ -19,7 +21,7 @@ module Samagotchi
   class BridgeClient
     HOST = "127.0.0.1"
     # A reply's status line; its code is group 1.
-    STATUS_LINE = %r{\AHTTP/1\.[01] (\d{3})}
+    STATUS_LINE = StreamRequest::STATUS_LINE
     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
@@ -54,9 +56,16 @@ module Samagotchi
     # What a UI says when the Bridge answers a route with 404: the worker runs
     # code from before the route. Restarting it picks up the installed chi.
     # @param cant [String] what the old worker can't do, e.g. "run commands"
-    def self.stale_worker_message(session_id, cant:)
-      "this session's worker runs an older chi and can't #{cant}; " \
-        "restart it: chi sessions stop #{session_id} && chi --resume #{session_id} (its turns still work)"
+    # @param via [ChiInvocation] how the commands are spelled (chi --remote
+    #   NAME: no --resume there, a message starts the fresh worker)
+    def self.stale_worker_message(session_id, cant:, via: ChiInvocation::HERE)
+      stop = via.command("sessions stop #{session_id}")
+      restart = if via.remote?
+                  "#{stop}, then a message (#{via.command("send #{session_id} -m …")}) starts a fresh one"
+                else
+                  "#{stop} && chi --resume #{session_id}"
+                end
+      "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.
@@ -103,6 +112,10 @@ 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
+
     # @param read_timeout [Numeric] see READ_TIMEOUT
     def initialize(session_id:, port:, host: HOST, read_timeout: READ_TIMEOUT)
       @session_id = session_id
@@ -152,9 +165,12 @@ module Samagotchi
     # @param no_interrupt [Boolean] run the turn with the raised iteration limit
     # @param images [Array<Hash>] refs ({file:, name:}) to images already in
     #   the session's images/
-    def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil)
+    # @param author [String, nil] who wrote it when it isn't the session's
+    #   owner; sent only when given (SessionManager.deliver_turn)
+    def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil, author: nil)
       body = { session_id: @session_id, prompt: prompt, client_id: client_id }
       body[:no_interrupt] = true if no_interrupt
+      body[:author] = author if author
       body[:images] = images if images && !images.empty?
       body[:delivery] = delivery unless delivery.nil? || Delivery.next_step?(delivery)
       body[:deadline] = deadline
@@ -332,45 +348,16 @@ module Samagotchi
 
     # Open GET /session/:id/stream and read past the response headers.
     # @param timeout [Float, nil] give up when the headers aren't all in by then
-    # @return [Array(TCPSocket, Integer), nil] the socket positioned at the
-    #   body and the HTTP status, or nil when the Bridge can't be reached
+    # @return [Array(TCPSocket, Integer, Hash), nil] the socket positioned
+    #   at the body, the HTTP status and the headers (StreamRequest.open), or
+    #   nil when the Bridge can't be reached
     def connect_stream(query: "", last_event_id: nil, timeout: nil)
-      sock = TCPSocket.new(@host, @port)
-      lei = last_event_id.to_s.strip
-      last_event_line = lei.empty? ? "" : "Last-Event-ID: #{lei}\r\n"
-      sock.write("GET /session/#{@session_id}/stream#{query} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\nAccept: text/event-stream\r\n#{last_event_line}Connection: keep-alive\r\n\r\n")
-      deadline = timeout && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout)
-      status = header_line(sock, deadline).to_s[STATUS_LINE, 1].to_i
-      while (line = header_line(sock, deadline))
-        break if line.strip.empty?
-      end
-      [sock, status]
-    rescue SystemCallError, SocketError, IOError
-      sock&.close rescue nil
-      nil
+      StreamRequest.open(host: @host, port: @port, path: "/session/#{@session_id}/stream#{query}",
+                         last_event_id: last_event_id, timeout: timeout)
     end
 
     private
 
-    # One line of the response headers, or nil at EOF; raises
-    # Errno::ETIMEDOUT once +deadline+ (monotonic, nil: none) has passed. A
-    # line read in pieces, so a Bridge that stops mid-line can't hold it.
-    def header_line(sock, deadline)
-      return sock.gets unless deadline
-
-      line = +""
-      loop do
-        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        raise Errno::ETIMEDOUT unless remaining.positive? && sock.wait_readable(remaining)
-
-        char = sock.getc
-        return line.empty? ? nil : line if char.nil?
-
-        line << char
-        return line if char == "\n"
-      end
-    end
-
     # 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.

data/lib/samagotchi/bundles/claude-peer/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: claude-peer
-version: 0.4.1
+version: 0.4.2
 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:35f3be2b466a5ba07591d64040bc5780fdd843b9b08737f8ea8a2fccb2102832
+  pair: sha256:2e66103c43fce5eab05f897682ba943f394743c1ad47bf439be3ce529f1b2058
   chi-peer-SKILL.md: sha256:e991a91139a127a60f9a216043eb5864945fb211952a1e3c8db2068c6cc254f1
 # 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

@@ -8,7 +8,9 @@
 # is this session's inbox socket (chi's claude_send tool writes there), and
 # claude-outbox, where Claude's answers go. Again after a Claude restart, it
 # only refreshes the socket: the push carries the new hint. CHI names the chi
-# command (default: chi on the PATH).
+# command (default: chi on the PATH). Through a remote (CHI_REMOTE, or
+# --remote NAME in CHI) chi there can't reach this machine's socket: it
+# attaches claude-outbox only, and says so.
 set -eu
 
 usage() {
@@ -33,6 +35,23 @@ if [ -z "$sock" ]; then
 fi
 chi=${CHI:-chi}
 
+# The remote, as SessionAccess::Dispatch names it: a --remote NAME (or
+# --remote=NAME) word in CHI, the last one, beats CHI_REMOTE (trimmed; blank:
+# local). An empty or dash-led name is still a remote: chi refuses it.
+remote=$(printf '%s\n' "${CHI_REMOTE:-}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+via= take=
+[ -z "$remote" ] || via=env
+for word in $chi; do
+  if [ -n "$take" ]; then
+    remote=$word take=
+    continue
+  fi
+  case "$word" in
+    --remote) remote= via=chi take=1 ;;
+    --remote=*) remote=${word#--remote=} via=chi ;;
+  esac
+done
+
 # A JSON string: backslashes, quotes, tabs and newlines escaped.
 json() {
   printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' |
@@ -51,6 +70,16 @@ attach() {
   fi
 }
 
+if [ -n "$via" ]; then
+  attach claude-outbox --why "Claude's answers to what you sent it (claude-peer); Claude runs on another machine: claude_send can't reach it" \
+    --hint "latest Claude reply"
+  ask=$chi
+  [ "$via" = chi ] || ask="CHI_REMOTE=$remote $chi"
+  printf '%s\n' "pair: chi is on $remote, so chi can't send to this Claude session (claude_send needs its socket on chi's machine): paired with chi $id, claude-outbox only. Answer chi with $ask context push claude-outbox $id; chi's replies reach you only when the user relays them (or asks you to run $ask send --wait $id)"
+  $chi context ls "$id"
+  exit 0
+fi
+
 attach claude-inbox --why "the Claude Code session paired with you: send it parts with claude_send" --hint "$sock"
 text="Claude Code peer inbox
 socket: $sock

data/lib/samagotchi/bundles/codex-peer/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: codex-peer
-version: 0.3.2
+version: 0.3.3
 scope: system
 description: "Pair this session with an OpenAI Codex CLI session you work with: the codex_send tool and /codex send it a part of the work (a plan step, a diff, a finding) to validate or as context, with codex queue, and Codex's answer comes back as the codex-outbox context; /codex install-skill installs Codex's chi-peer skill, which pairs"
 trust_level: reviewed
@@ -12,7 +12,7 @@ plugin:
   file: plugin.rb
   sha256: sha256:b03465566272891237ac1906980ff6956579a4703d3a42c414ce50a81de551f6
 scripts:
-  pair: sha256:251448a31959b5c916400eff7909e85c696855d5c16b6b10973ada40915c8051
+  pair: sha256:0830dcb856debea0e4a2a0eb0da8a73b9e9ac2444da957d2928ec734280186a1
   chi-peer-SKILL.md: sha256:7c392ac04c115ea1e762ad562b5c4c44c3eca71558ba5d9dfeaeabdd533b6a82
 # 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/codex-peer/scripts/pair

@@ -9,12 +9,15 @@
 # `codex queue --thread <id>` with it), and codex-outbox, where Codex's
 # answers go. Again later, it only refreshes the thread id: the push carries
 # the new hint. CHI names the chi command (default: chi on the PATH).
+# Through a remote (CHI_REMOTE, or --remote NAME in CHI) chi there can't
+# queue to this machine's Codex: it attaches codex-outbox only, and says so.
 #
 # chi writes the session's context under its state folder, which Codex's
 # default sandbox doesn't let it write: ~/.codex/config.toml needs
 #   [sandbox_workspace_write]
 #   writable_roots = ["<state>/samagotchi/context"]
-# and a write refused says so.
+# and a write refused says so. Through a remote chi talks HTTP instead,
+# which the sandbox may refuse (no network): a connection that fails says so.
 set -eu
 
 usage() {
@@ -39,14 +42,46 @@ if [ -z "$thread" ]; then
 fi
 chi=${CHI:-chi}
 
-# Prints chi's error, and the writable_roots line when the sandbox refused.
+# The remote, as SessionAccess::Dispatch names it: a --remote NAME (or
+# --remote=NAME) word in CHI, the last one, beats CHI_REMOTE (trimmed; blank:
+# local). An empty or dash-led name is still a remote: chi refuses it.
+remote=$(printf '%s\n' "${CHI_REMOTE:-}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+via= take=
+[ -z "$remote" ] || via=env
+for word in $chi; do
+  if [ -n "$take" ]; then
+    remote=$word take=
+    continue
+  fi
+  case "$word" in
+    --remote) remote= via=chi take=1 ;;
+    --remote=*) remote=${word#--remote=} via=chi ;;
+  esac
+done
+
+config='~/.codex/config.toml'
+[ -z "${CODEX_HOME:-}" ] || config=$CODEX_HOME/config.toml
+
+# Prints chi's error, and the config line when the sandbox may have refused:
+# writable_roots here, network_access through a remote.
 fail() {
   printf '%s\n' "$1" >&2
+  if [ -n "$via" ]; then
+    case "$1" in
+      *"connection broke"* | *"can't find host"* | *"host unreachable"* | *"no answer within"*)
+        cat >&2 <<MSG
+pair: Codex's sandbox may be keeping chi from reaching $remote (workspace-write has no network by default): if so, add to $config
+  [sandbox_workspace_write]
+  network_access = true
+then restart Codex and pair again.
+MSG
+        ;;
+    esac
+    exit 1
+  fi
   case "$1" in
     *"Operation not permitted"* | *"Read-only file system"* | *"Permission denied"*)
       state=${XDG_STATE_HOME:-$HOME/.local/state}
-      config='~/.codex/config.toml'
-      [ -z "${CODEX_HOME:-}" ] || config=$CODEX_HOME/config.toml
       cat >&2 <<MSG
 pair: Codex's sandbox can't write chi's state: add to $config
   [sandbox_workspace_write]
@@ -75,6 +110,16 @@ attach() {
   fi
 }
 
+if [ -n "$via" ]; then
+  attach codex-outbox --why "Codex's answers to what you sent it (codex-peer); Codex runs on another machine: codex_send can't reach it" \
+    --hint "latest Codex reply"
+  ask=$chi
+  [ "$via" = chi ] || ask="CHI_REMOTE=$remote $chi"
+  printf '%s\n' "pair: chi is on $remote, so chi can't send to this Codex session (codex_send runs codex queue on chi's machine): paired with chi $id, codex-outbox only. Answer chi with $ask context push codex-outbox $id; chi's replies reach you only when the user relays them (or asks you to run $ask send --wait $id)"
+  $chi context ls "$id"
+  exit 0
+fi
+
 attach codex-inbox --why "the Codex session paired with you: send it parts with codex_send" --hint "$thread"
 text="Codex peer inbox
 thread: $thread

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -154,10 +154,12 @@ rules:
   # code). add NAME --push and chi context push don't run anything. Quoted
   # words ("context", '--cmd=…') and backslash-newline continuations still
   # match; xargs chi context add asks whatever it is fed (its arguments
-  # aren't in the command).
+  # aren't in the command). chi's global flag --remote NAME (the only one
+  # that goes before a subcommand) may stand between chi and context;
+  # CHI_REMOTE=NAME leaves the words as they are.
   - id: chi-context-cmd
     tool: shell
-    command: '\bchi["'']?[\s\\]+["'']?context["'']?[\s\\]+["'']?add\b(?:[^\n]|\\\n)*[\s"''\\]--cmd(?:[\s="''\\]|$)|\bxargs\b[^;&|\n]*\bchi["'']?[\s\\]+["'']?context["'']?[\s\\]+["'']?add\b'
+    command: '\bchi["'']?(?:[\s\\]+["'']?--remote(?:=|["'']?[\s\\]+["'']?)[^\s"''\\;&|]+["'']?)*[\s\\]+["'']?context["'']?[\s\\]+["'']?add\b(?:[^\n]|\\\n)*[\s"''\\]--cmd(?:[\s="''\\]|$)|\bxargs\b[^;&|\n]*\bchi["'']?(?:[\s\\]+["'']?--remote(?:=|["'']?[\s\\]+["'']?)[^\s"''\\;&|]+["'']?)*[\s\\]+["'']?context["'']?[\s\\]+["'']?add\b'
     verdict: ask
     scopes: [once]
     reason: attaches a command chi will run every few minutes, outside the guardrails
@@ -165,10 +167,11 @@ rules:
   # ── chi broadcast: for the user, not an agent ─────────────────────────
   # chi broadcast refuses to run inside a session (SAMAGOTCHI_PARENT_SESSION
   # is set there), but an agent can unset that; this asks every time, and
-  # only the user may allow it. Quoted words and continuations still match.
+  # only the user may allow it. Quoted words, continuations and --remote
+  # NAME before the word still match.
   - id: chi-broadcast
     tool: shell
-    command: '\bchi["'']?[\s\\]+["'']?broadcast\b'
+    command: '\bchi["'']?(?:[\s\\]+["'']?--remote(?:=|["'']?[\s\\]+["'']?)[^\s"''\\;&|]+["'']?)*[\s\\]+["'']?broadcast\b'
     verdict: ask
     scopes: [once]
     reason: shares a note with every session it may concern; chi broadcast is for the user, not an agent

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

@@ -1,6 +1,6 @@
 ---
 name: guardrails
-version: 0.9.2
+version: 0.9.3
 scope: system
 description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, chi broadcast, answering chi around chi answer, removing a memory, writing a memory that reaches the system prompt (identity, model notes) or a model overlay; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed

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

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

data/lib/samagotchi/chi_invocation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # How the follow-up commands chi prints (ParentReport's chi answer and
+  # chi send --wait, a stop's chi --resume, the attached TUI's re-attach
+  # lines) are spelled so that they work when pasted: on this machine plain
+  # chi, against a remote (chi --remote NAME, CHI_REMOTE=NAME alike) chi
+  # --remote NAME. A remote's chi web is named where the page is meant.
+  # @!attribute remote [String, nil] the remote's name; nil: this machine
+  ChiInvocation = Data.define(:remote) do
+    def remote? = !remote.nil?
+
+    # The command word: "chi", or "chi --remote NAME".
+    def chi = remote? ? "chi --remote #{remote}" : "chi"
+
+    # +words+ after #chi: command("answer ID …").
+    def command(words) = "#{chi} #{words}"
+
+    # chi --attach ID (chi --remote NAME --attach ID).
+    def attach(id) = command("--attach #{id}")
+
+    # chi --resume ID (chi --remote NAME --resume ID).
+    def resume(id) = command("--resume #{id}")
+
+    # What shows the session ("… shows it"): its attach.
+    def shows(id) = attach(id)
+
+    # Where the user opens it ("open it: …"): its attach, or the web (the
+    # remote's chi web).
+    def open_it(id) = "#{attach(id)} or #{remote? ? web : "the web"}"
+
+    # The remote's chi web, by name.
+    def web = "chi web on #{remote}"
+  end
+
+  class ChiInvocation
+    # This machine's: plain chi.
+    HERE = new(remote: nil)
+  end
+end

data/lib/samagotchi/cli/command.rb

@@ -26,9 +26,10 @@ module Samagotchi
         @stderr.puts(text)
       end
 
+      # @param usage [String, nil] what follows the line (nil: "(see …
+      #   --help)" on it); a one-line error whose fix the line says passes nil
       # @return [Integer] the usage exit status
-      def usage_error(message)
-        usage = usage_on_error
+      def usage_error(message, usage: usage_on_error)
         error_line("#{command_name}: #{message}#{" (see #{command_name} --help)" unless usage}")
         @stderr.puts(usage) if usage
         Exit::USAGE

data/lib/samagotchi/cli/flags.rb

@@ -68,6 +68,11 @@ module Samagotchi
         add(names, Flag.new(refusal: message))
       end
 
+      # Each declared flag's names, in the order declared ([["-m",
+      # "--message"], ["--new"]]); refused flags too.
+      # @return [Array<Array<String>>]
+      def names = @flags.keys.group_by { |name| @flags[name].object_id }.values
+
       # @param defaults [Hash] the options before any flag (not changed)
       # @return [Result]
       def parse(argv, defaults = {})