samagotchi 0.121.0 → 0.121.1

data/docs/internals/web-push.md

@@ -66,10 +66,11 @@ files, one per machine, never in config.yml:
 `Store#add` checks what `pushManager.subscribe` gave, one message per refusal (the route answers it as 400
 `invalid_subscription`): an endpoint and both keys; https on port 443 without userinfo, at most 2048 bytes; a host in
 `Store::PUSH_SERVICES` (Apple, Google's FCM, Mozilla, `*.notify.windows.com`; a `services:` seam for specs, not
-config): chi web POSTs to that URL, so it never takes an arbitrary host; `p256dh` a 65-byte uncompressed point,
-`auth` 16 bytes. The same endpoint again replaces the old entry. `replaces:` (the device's id from its last
-subscribe, which the page keeps) drops that entry on this origin too, before the `MAX_SUBS` cap is counted, and
-yields it (the route logs `push_replaced`); its own endpoint is never dropped that way, and an unknown id is ignored.
+config): chi web POSTs to that URL, so it never takes an arbitrary host; `p256dh` a 65-byte uncompressed point
+on P-256 (built as `Crypto.ec_public` builds it), `auth` 16 bytes. The same endpoint again replaces the old entry.
+`replaces:` (the device's id from its last subscribe, which the page keeps) drops that entry on this origin too,
+before the `MAX_SUBS` cap is counted, and yields it (the route logs `push_replaced`); its own endpoint is never
+dropped that way, and an unknown id is ignored.
 That is how a subscription iOS revoked silently (Apple keeps answering 201, so `:gone` never comes) leaves the store:
 the user turns the bell off and on, the page has no live subscription to delete, and the new one replaces it. Every write is a read-change-write under
 `store.lock` (chi web's request threads and the sender thread both write). A `subscriptions.json` that doesn't read
@@ -85,7 +86,9 @@ tailnet leaves the old ones stale (never sent to: a tap would open an origin tha
 `Client#deliver(sub, payload, ttl:, urgency:)` encrypts the payload's JSON, POSTs it over TLS (open 5 s, read 10 s,
 no redirects, no retry of its own) with `Content-Encoding: aes128gcm`, `TTL`, `Urgency` and the VAPID header, and
 answers a `Client::Result`: `:ok` (200/201/202), `:gone` (404/410: the device dropped it), `:bad_jwt` (403 with
-`BadJwtToken`), `:failed` (anything else; a connection error as its class name or `timeout`, never its message).
+`BadJwtToken`), `:failed` (anything else; a connection error as its class name or `timeout`, never its message;
+any other error too, so a key off the curve on disk fails that device alone, never the Notifier's flush or the test
+push).
 A 429 or 5xx also carries `retry_after`: its `Retry-After` delta-seconds up to `RETRY_MAX` 60, else (missing, an
 HTTP date) `RETRY_DEFAULT` 10; nil for anything else, a connection error too (it may have been delivered). The
 transport is injectable: `spec/web/push/client_spec.rb` runs a fake push service (WEBrick, plain http through the
@@ -206,7 +209,8 @@ public URL, or `web.push.enabled: false`):
 - `POST /api/push/subscriptions {subscription: {endpoint, keys}, replaces?: id}` → 201 `{id, label}`; the label is
   chi's own ("iPhone · <date>", from the User-Agent's device class: iPhone, iPad, Mac, else Browser); `replaces`
   drops the device's earlier entry (`Store#add`).
-- `DELETE /api/push/subscriptions {endpoint}` → 204: this device's bell turned off.
+- `DELETE /api/push/subscriptions {endpoint}` → 204: this device's bell turned off (`Store#remove(endpoint, origin:)`:
+  only a device on this origin goes, as with the other device routes).
 - `DELETE /api/push/subscriptions/ID` → 204, 404 `unknown_device` (another origin's, or not a short id); logs
   `push_removed`. The devices sheet's Remove for another device; this device's own row never uses it (its switch is
   the bell, so the page's state and the store stay one).
@@ -245,9 +249,13 @@ Screen app the bell (`notifications.js`) registers `/sw.js`, asks `GET /api/push
 and is "push to this phone" when chi web pushes: on while chi web has this device. A tap asks permission from the tap
 (iOS asks only from a user gesture), subscribes, posts it (with `replaces`: the id chi web answered last time,
 kept in localStorage as `chi_push_device`, `PUSH_DEVICE_KEY`; a storage that throws only loses the replace) and sends
-a test push; a tap when on unsubscribes and deletes, and forgets the id, unless there was no subscription left to
-delete (revoked meanwhile): then the id stays for the next subscribe to replace. The tab's own OS notification is left to the push there; the title count stays. In a browser tab, or with
-chi web not pushing, the bell is the in-tab one, unchanged (no duplicate desktop pushes).
+a test push; a tap when on deletes, then unsubscribes (a DELETE that fails changes nothing local: the bell stays on
+and says the error), and forgets the id, unless there was no subscription left to delete (revoked meanwhile): then
+the id stays for the next subscribe to replace. The tab's own OS notification is left to the push there; the title
+count stays. A `GET /api/push` (or `register()`) that fails at launch (chi web restarting, a phone just woken) leaves
+the bell the in-tab one until the page next comes back in front (`backInFront` → `retryPush`, one at a time, no
+timer); chi web answering that it doesn't push is not asked again. In a browser tab, or with chi web not pushing,
+the bell is the in-tab one, unchanged (no duplicate desktop pushes).
 
 **The devices sheet** (`public/push_devices.js`, `createPushDevices` on `chip_popover.js`'s shell: a bottom sheet
 under 600 px, else a popover at the bell; made once chi web says it pushes, so a tab never gets one): in push mode
@@ -273,8 +281,11 @@ page's `byId` (`push.js openPushKeys`: `Attention.open_keys`'s rule), and sets o
 badge (`navigator.setAppBadge` / `clearAppBadge`); the bell turned off clears it. It runs once push is known, when
 the page comes back in front, and after each hub frame while visible (so answering on the Mac with the app open
 clears it at once), one at a time with one rerun. Never before the first snapshot (an empty `byId` would close
-everything) and never on a project's page (`createNotifications({scoped})`, app.js passes `!!scope.dir`: its
-`/api/events?dir=` leaves out the other projects' sessions).
+everything). The device's notifications are every project's, so on a project's page (`?dir=`, or the bare page on
+chi web's start project: `createNotifications({scoped})`, app.js passes `!!scope.dir`) the tidy-up goes by a stream
+of every session of its own (`watchAll`, through `allEvents`: data.js `openEvents` without a dir), not the page's
+`/api/events?dir=` frames, which leave out the other projects' sessions. That stream is open only with the bell on
+(turning it off closes it), one at a time, and one that ended is opened again when the page next comes back in front.
 
 Accepted staleness: an approval answered elsewhere keeps its banner until the app opens (the worker's cleanup on the next push doesn't work on iOS yet: see iOS facts)
 (or a swipe), and the icon badge may be too high until then; a show already handed to Apple just before its answer

data/docs/plugins.md

@@ -587,7 +587,8 @@ config or bundle toolkit) with `add` declared and `remove` left out, and
 inherits the base's, `""` clears it; at most 2000 characters, and one that
 isn't a String or is longer is a load error). `groups` selects the source
 groups the toolkit reaches (names or globs, sorted and deduplicated; nil
-inherits the base's, `[]` reaches none, and `:all` reaches every group).
+inherits the base's, `[]` reaches none, and `:all` reaches every group; anything
+else, a map say, is a load error).
 Groups match against the tool index's load-time names. Users pick
 it like chi's own (`chi --toolkit NAME`, `toolkit.default`, `/toolkit NAME`),
 and the plugin with `ctx.use_toolkit` (below). Names are `a-z`, `0-9`, `_` and
@@ -597,7 +598,7 @@ tool (full) until it comes back, with a warning at its first turn. See
 [Toolkits](configuration.md#toolkits). `prompt:` needs chi 0.72.0 (an older
 chi refuses the keyword, a load error: a bundle that passes it sets
 `requires_chi: ">= 0.72.0"`). `groups:` needs chi 0.121.0: an older chi refuses that keyword
-too, so a bundle passing it sets `requires_chi: ">= 0.121.0"`.
+too, so a bundle passing it sets `requires_chi: ">= 0.121.0"` (`chi bundle check` warns on a lower one).
 
 ```ruby
 chi.toolkit "review", base: "lean", add: %w[delegate delegate_result]
@@ -1014,6 +1015,9 @@ ctx.sessions.review(subjects: ["docs/plan.md"], seed: handoff)  # => a review se
     `/title` of its own (see [Session titles](sessions.md#session-titles)).
   - An image a message names is copied into the child. One whose file is
     gone is dropped, with `[image x.png was not copied]` in its message.
+  - A child chi won't start raises `Error` with chi's reason: the session's
+    model is gone from the config, or its toolkit is a config kit with an
+    invalid `groups:` (`toolkit.kits`, `Toolkit.check_new!`).
 - `review(subjects: [], seed: nil, recap_wait: 0)` starts a review session of
   this one, as `chi review --from` does (see [Review sessions](sessions.md#review-sessions)):
   a new session in this session's folder, on its model and setup, seeded with

data/docs/sessions.md

@@ -377,3 +377,18 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - **A child asks before it changes anything outside its folder** (the work tree top of the folder it started in): a write or edit there, mutating git in another checkout, a command that isn't read-only run from outside it or naming the main checkout or a sibling worktree. It's a core guardrail, on in every mode and without the guardrails bundle, and answered once or for the child's session ([Guardrails](guardrails.md#a-delegate-childs-boundary)); the approval relays to the parent's user as any other.
 - Limits: a child cannot `delegate` (depth 1; the tool refuses), and one session may have at most `session.max_children` (default `4`, env `SAMAGOTCHI_SESSION_MAX_CHILDREN`) children running at a time, counted from the session files (a finished or idle-exited child does not count; one whose worker is still starting does, for 15 s). A refused call creates no session. Nothing stops children with the parent: `chi sessions stop ID` does.
 - The link is the session's `parent_id`, written before the worker starts, so a respawn keeps it (and `delegate: true`, which a fork's `parent_id` doesn't come with; a child saved before that field is known by its `system/delegated` memory); `GET /api/sessions`, `/api/sessions/:id` and the web hub's `session` frames carry it and `delegate` (a fork is `false`; the web parent's children chip counts delegates only); `SessionManager.children_of` lists a parent's children.
+## Restart fallback
+
+If `chi sessions restart ID` cannot ask its worker (the Bridge is unreachable
+or refuses its secret, the worker speaks a newer protocol, or its start is
+stuck), chi sends TERM without writing the stop marker, waits up to
+`SessionManager::FALLBACK_STOP_WAIT` (40 s: the worker writes its recap on
+leave) for the owner lock, and resumes the session; a worker that doesn't let
+go in time is reported as "didn't take the restart" and nothing is resumed. A
+worker that took the lock meanwhile (the old one handed over after all) is
+not touched. It refuses first if disk shows a running turn, pending
+question or approval, queued input, or a running background task started by
+the session; the message directs the user to `chi sessions stop ID`, then any prompt.
+Reminders, a running `/btw`, and other in-memory worker state cannot be
+checked and may be lost in this fallback. The web restart route behaves the
+same way.

data/docs/testing.md

@@ -163,9 +163,44 @@ A session's Bridge answers only a request that names its secret (`X-Chi-Bridge`,
 see [architecture.md](architecture.md)). A spec that writes its own request to a real Bridge (`Net::HTTP`, a raw
 socket) names it too: `include BridgeAuth` (spec/support/bridge_auth.rb, required by the spec that needs it) gives
 `bridge_auth(session_dir_or_sidecar)`, the header as a Hash, and `bridge_auth_line(...)` for a raw request; or read
-`port` and `secret` from the sidecar in one go, as `BridgeClient.discover` does. A client made with `BridgeClient.new`
+`port` and `secret` from the sidecar in one go, as `WorkerLink.client` does. A client made with `BridgeClient.new`
 takes `secret:` (nil for a fake Bridge that doesn't check it).
 
+### Support files
+
+`spec/spec_helper.rb` loads the suite-wide helpers (marked *helper*: every example group gets them); a spec that needs
+any other file requires it, so a spec file run alone still finds its requires. Each file's header says more.
+
+| File | What it gives |
+|---|---|
+| `bounded_capture.rb` | `BoundedCapture.capture3`: `Open3.capture3` with a deadline, in its own process group killed on expiry |
+| `bridge_auth.rb` | `BridgeAuth`: the Bridge secret's header for a hand-written request (above) |
+| `chi_cli.rb` | *helper*: `run_chi` (bin/chi in a child process), `fork_chi` (in a fork: no Ruby boot), `isolated_chi_env` |
+| `effective_model_configs.rb` | `EffectiveModelConfigs`: one config.yml holding every host the effective-model characterization pins, and its goldens |
+| `env.rb` | *helper*: `with_env` sets ENV for a block and puts it back (nil unsets) |
+| `failing_saves.rb` | shared context "failing session saves": `Session#save` raising ENOSPC while `saves_fail`, and the worker's `save_failed` records |
+| `fake_chat_adapter.rb` | `FakeChatAdapter`: an `LLM::OpenAIChat` stand-in answering `#chat` with queued steps, recording each request |
+| `fake_executables.rb` | `FakeExecutables`: fake commands (`gh`, `git`) for a spec's PATH, symlinks to one launcher (macOS's first-exec check is paid once) |
+| `fake_provider_server.rb` | `FakeProviderServer`: an in-process HTTP provider replaying spec/fixtures/providers, recording requests |
+| `fake_tailscale.rb` | A fake `tailscale` for `Web::Tunnel::Tailscale` (status, serve, lock from JSON files; argv.log) |
+| `git_repo.rb` | *helper*: `git_repo`, a temp folder with `git init`, removed after the example |
+| `integration_server.rb` | *helper*: the live model server `:integration` examples use, from `SAMAGOTCHI_INTEGRATION_*` ([Integration specs](#integration-specs)) |
+| `mcp_bundle.rb` | The shipped mcp bundle's path and the fake MCP server its specs start (`MCP_FAKE_COMMAND`, no RubyGems) |
+| `no_console.rb` | Loaded first (`ruby -r`) by spawned bin/chi children: `IO.console` is nil, so output never wraps at a terminal's width |
+| `recording_surface.rb` | `RecordingSurface`: a `TerminalUI::Surface` that records commits and slots instead of drawing |
+| `remote_backend.rb` | `RemoteBackend`: `SessionAccess::Remote` against chi web's Rack app in this process (no socket, LAN token gate) |
+| `reply_wait_looks.rb` | `ReplyWaitLooks`: counts a `ReplyWait`'s polls, so a step waits for the looks instead of a delay |
+| `stamps.rb` | *helper*: `next_stamp`, distinct ordered times for the lib's `now:` seams; the pinned history clock |
+| `task_dirs.rb` | `with_task_dir`: a tasks' folder of its own, every task stopped and its recorders joined after |
+| `test_kernel.rb` | `TestKernel`: `test_kernel` (a real `KernelLoop` to stub `#run` on) and `test_client` for Engine specs |
+| `thinking_off.rb` | shared context "thinking off": `SAMAGOTCHI_THINKING_LEVEL=off` for the example |
+| `virtual_terminal.rb` | `VirtualTerminal`: just enough VT100 to check what a Screen leaves on the terminal |
+| `waiting.rb` | *helper*: `SpecWaiting` (`wait_for`, `wait_until`, `join!`, `pop!`, …), the test kit's helpers ([Waiting and time](#waiting-and-time)) |
+| `web_push_receiver.rb` | `WebPushReceiver`: a device's key pair and auth secret, decrypting what chi web pushed (RFC 8291) |
+| `web_server.rb` | `WebServer`: chi web's `Web::App` served for real on a free port in a thread, for specs a Rack mock can't serve |
+| `worker_links.rb` | `WorkerLinks`: `live_link(sidecar)` / `none_link`, the `WorkerLink` outcomes a stub of `WorkerLink.resolve` / `.await` (or chi web's `#worker_link`) returns |
+| `worker_loop_rounds.rb` | `WorkerLoopRounds`: counts a worker's idle loop passes, for "nothing happens" checks |
+
 ## Bundle specs: the test kit
 
 A shipped bundle's plugin and hook files are tested through the bundle test kit (`samagotchi/testing`,
@@ -357,3 +392,8 @@ kept with the build id `/status` shows (`identity.cache.build_id`); when that ch
 the version and record it again. This step goes once a Splash release carries its version in `/status`.
 
 The code is `script/deps/deps_check.rb`; its spec stubs every request and command (`spec/deps_check_spec.rb`).
+
+`script/dead-code` (a tech-debt audit round runs it too) lists the methods defined under lib/ that nothing in the repo
+names (Prism; `be_foo`/`have_foo` count for `foo?`/`has_foo?`), as `path:line name [notes]` with a count; a note says
+what may explain a row (a doc, a name built at run time, a framework hook). Advisory: it always exits 0, CI doesn't
+run it. Its spec is `spec/script/dead_code_spec.rb`.

data/lib/samagotchi/answer_command.rb

@@ -196,7 +196,7 @@ module Samagotchi
               end
       return failure(worker_gone(id)) unless reply
 
-      return failure(BridgeSecret::REFUSED) if reply.secret_refused?
+      return failure(BridgeSecret.refused(id, via: @access.invocation)) if reply.secret_refused?
 
       case reply.status
       when 200 then nil

data/lib/samagotchi/bridge.rb

@@ -32,6 +32,7 @@ require_relative "log"
 require_relative "proxy_trace"
 require_relative "version"
 require_relative "worker_sidecar"
+require_relative "worker_link"
 require_relative "relay_verifier"
 require_relative "relay_watcher"
 require_relative "reply_wait"
@@ -75,9 +76,6 @@ module Samagotchi
     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)
     # @param state_dir [String] the session state directory root
@@ -484,7 +482,7 @@ module Samagotchi
           break
         elsif !secret_ok?(headers)
           note_refused(:secret, "secret_refused", request[:path])
-          write_json(io, 403, nil, { error: BridgeSecret::ERROR, detail: SECRET_REFUSED })
+          write_json(io, 403, nil, { error: BridgeSecret::ERROR, detail: BridgeSecret.refused(@session_id) })
           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
@@ -1500,17 +1498,19 @@ module Samagotchi
       # 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, secret: @secret).write(session_dir)
+                        epoch: @epoch, secret: @secret, pid: Process.pid,
+                        protocol: WorkerLink::PROTOCOL).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
 
-    # Only while it still names this bridge: a racing worker for the same
-    # session may have written its own since.
+    # Only while it still carries this bridge's epoch: a racing worker for the
+    # same session may have written its own since (a file without an epoch
+    # is only ever an older worker's).
     def remove_sidecar
       return unless @server
 
-      File.unlink(WorkerSidecar.path(session_dir)) if WorkerSidecar.read(session_dir)&.port == @port
+      File.unlink(WorkerSidecar.path(session_dir)) if WorkerSidecar.read(session_dir)&.epoch == @epoch.to_s
     rescue StandardError
       nil
     end

data/lib/samagotchi/bridge_client/event_stream.rb

@@ -158,16 +158,18 @@ module Samagotchi
 
       # One connection: :events when it yielded any, else why it failed.
       def read_connection
-        sock, status, headers = @client.connect_stream(query: @query, last_event_id: @last_event_id, timeout: HEADER_TIMEOUT)
-        return :unreachable unless sock
-
-        unless attach(sock)
-          sock.close rescue nil
-          return :closed
+        sock = nil
+        outcome = @client.open_stream(query: @query, last_event_id: @last_event_id, header_timeout: HEADER_TIMEOUT,
+                                      attempts: 1) do |opened_sock|
+          sock = opened_sock if attach(opened_sock)
         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
+        return :closed if closed?
+        return :unreachable if outcome.is_a?(StreamOpen::Unreachable)
+        return :unknown_session if outcome.is_a?(StreamOpen::Refused) && outcome.reason == :unknown_session
+        return :secret_refused if outcome.is_a?(StreamOpen::Refused) && outcome.reason == :bridge_secret
+        return :unreachable unless outcome.is_a?(StreamOpen::Opened)
+
+        sock = outcome.sock
 
         # Back as soon as the stream answers: a replay may bring nothing
         # (the session was quiet), and the next frame could be minutes away.
@@ -194,24 +196,6 @@ 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/stream_open.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../bridge_secret"
+
+module Samagotchi
+  class BridgeClient
+    # The result of opening an SSE connection. Only Opened owns a socket the
+    # caller may read; refused sockets are consumed for their detail and closed.
+    module StreamOpen
+      Opened = Data.define(:sock, :status, :headers)
+      Refused = Data.define(:reason, :detail, :status)
+      Unreachable = Data.define(:attempts)
+
+      BODY_LIMIT = 16_384
+      BODY_TIMEOUT = 5.0
+
+      module_function
+
+      # The one place a stream's response status is interpreted. Through chi
+      # web, its mapped bridge-secret and not-live responses have their own
+      # status codes (502 and 503).
+      def classify(sock, status, headers)
+        return Unreachable.new(attempts: 0) unless sock
+        return Opened.new(sock: sock, status: 200, headers: headers) if status.to_i == 200
+        return Unreachable.new(attempts: 1) if status.to_i == 503
+
+        body = refusal_body(sock, headers)
+        json = parse(body)
+        detail = json&.[]("detail") || (body unless body.empty?)
+        code = status.to_i
+        error = json&.[]("error")
+        outcome = if code == 404
+                    Refused.new(reason: :unknown_session, detail: detail, status: code)
+                  elsif BridgeSecret.refused?(code, json || body)
+                    Refused.new(reason: :bridge_secret, detail: detail, status: code)
+                  elsif code == 403 && error == "proxied"
+                    Refused.new(reason: :proxied, detail: detail, status: code)
+                  elsif code == 403 && error == "cross_origin"
+                    Refused.new(reason: :cross_origin, detail: detail, status: code)
+                  elsif code == 502 && error == BridgeSecret::ERROR
+                    Refused.new(reason: :bridge_secret, detail: detail, status: code)
+                  else
+                    Refused.new(reason: :other, detail: detail, status: code)
+                  end
+        outcome
+      ensure
+        sock&.close unless (status || 0).to_i == 200
+      end
+
+      # A refusal body is bounded and interruptible by closing its socket.
+      # Content-Length replies stop at their declared size; older Bridges
+      # without it are read through EOF.
+      def refusal_body(sock, headers)
+        length = headers.to_h["content-length"]&.to_i
+        limit = length&.between?(0, BODY_LIMIT) ? length : BODY_LIMIT
+        body = +""
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + BODY_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.force_encoding(Encoding::UTF_8).scrub
+      rescue IOError, SystemCallError
+        body.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      def parse(body)
+        json = JSON.parse(body)
+        json if json.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+      private_class_method :parse
+    end
+  end
+end

data/lib/samagotchi/bridge_client/stream_request.rb

@@ -32,8 +32,14 @@ module Samagotchi
       # @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
+      # @raise [Errno::ETIMEDOUT] a connected server didn't finish its headers
       def open(host:, port:, path:, last_event_id: nil, headers: {}, timeout: nil)
-        sock = TCPSocket.new(host, port, connect_timeout: timeout || CONNECT_TIMEOUT)
+        begin
+          sock = TCPSocket.new(host, port, connect_timeout: timeout || CONNECT_TIMEOUT)
+        rescue SystemCallError, SocketError, IOError
+          return nil
+        end
+
         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
@@ -47,7 +53,7 @@ module Samagotchi
         [sock, status, received]
       rescue SystemCallError, SocketError, IOError
         sock&.close rescue nil
-        nil
+        raise
       end
 
       # The request's bytes.

data/lib/samagotchi/bridge_client.rb

@@ -8,6 +8,7 @@ require_relative "worker_sidecar"
 require_relative "bridge_secret"
 require_relative "delivery"
 require_relative "chi_invocation"
+require_relative "bridge_client/stream_open"
 require_relative "bridge_client/sse_parser"
 require_relative "bridge_client/event_stream"
 require_relative "bridge_client/stream_request"
@@ -15,8 +16,8 @@ require_relative "bridge_client/stream_request"
 module Samagotchi
   # Client side of a session worker's Bridge: the 127.0.0.1 HTTP + SSE server
   # each SessionManager worker runs for its Engine (see Bridge). Discovery goes
-  # through the worker's `bridge.json` sidecar (WorkerSidecar) in the session
-  # directory.
+  # through WorkerLink (the worker's `bridge.json` sidecar, WorkerSidecar, in
+  # the session directory); .for_sidecar makes the client.
   #
   # Requests are raw one-shot HTTP/1.1 over a TCPSocket (`Connection: close`),
   # exactly what the Bridge's minimal server expects.
@@ -27,7 +28,7 @@ module Samagotchi
     # 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:
+    # Seconds #open_stream waits for the Bridge's response headers:
     # a worker that took the connection and froze must not hold the web's
     # proxy thread (as EventStream::HEADER_TIMEOUT for the TUI's).
     STREAM_HEADER_TIMEOUT = 5.0
@@ -49,7 +50,7 @@ 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).
+      # 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
@@ -75,14 +76,6 @@ module Samagotchi
       "this session's worker runs an older chi and can't #{cant}; restart it: #{restart} (its turns still work)"
     end
 
-    # 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 [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.
@@ -94,24 +87,11 @@ module Samagotchi
       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, 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
     # one stat, and a 0.1 s step cost a create up to 0.1 s (the web's
     # create landed on 0.53/0.63/0.73 s).
     SPAWN_POLL_INTERVAL = 0.02
 
-    # Wait for a freshly spawned worker to publish its Bridge.
-    # @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)
-      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
     # or +timeout+ seconds have passed (it is always called at least once).
     # @return [Object, nil] the block's first truthy value
@@ -314,22 +294,26 @@ module Samagotchi
     # @return [Array(Integer, Object)] the status and the parsed JSON body
     #   (nil when it isn't JSON); [nil, nil] when no reply came
     def get(path)
+      response = get_response(path)
+      [response.status, response.json]
+    rescue StandardError
+      [nil, nil]
+    end
+
+    # GET /session/:id/<path>, preserving the raw response and raising on I/O.
+    # @return [Response]
+    def get_response(path)
       sock = TCPSocket.new(@host, @port)
       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.
       status = response && response[STATUS_LINE, 1]
-      return [nil, nil] unless status
+      raise IOError, "bridge #{path}: invalid response status" unless status
 
       body = response.split("\r\n\r\n", 2)[1] || ""
-      [status.to_i, begin
-        JSON.parse(body)
-      rescue JSON::ParserError
-        nil
-      end]
-    rescue StandardError
-      [nil, nil]
+      Response.new(status: status.to_i, body: body)
+    ensure
+      sock&.close rescue nil
     end
 
     # Monotonic SSE cursor of the live Engine, from GET /session/:id/state.
@@ -342,46 +326,49 @@ module Samagotchi
       nil
     end
 
-    # GET /session/:id/stream: yield the raw SSE body bytes as they arrive
-    # until the Bridge closes the stream.
-    # @param query [String] "" or "?from_seq=N"
-    # @param last_event_id [String, nil] reconnect cursor; the Bridge prefers it
-    #   over ?from_seq
-    # @param running [#call, nil] asked before every read, and every
-    #   STREAM_POLL seconds of silence: the stream ends once it returns
-    #   false. A quiet stream is never cut otherwise.
+    # Open GET /session/:id/stream and classify the response before the
+    # caller answers its own request.
     # @param header_timeout [Float] see STREAM_HEADER_TIMEOUT
-    def stream(query: "", last_event_id: nil, running: nil, header_timeout: STREAM_HEADER_TIMEOUT)
-      sock = nil
-      # Absorb the probe→connect race around a resumed worker's bridge:
-      # the sidecar probe can succeed a moment before the worker dies (or
-      # 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, 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
+    # @param attempts [Integer] retries for connection failures only
+    # @yield [sock] called after response headers arrive, before classifying a
+    #   refusal; EventStream uses it to publish the socket for #close
+    # @return [StreamOpen::Opened, StreamOpen::Refused, StreamOpen::Unreachable]
+    def open_stream(query: "", last_event_id: nil, header_timeout: STREAM_HEADER_TIMEOUT,
+                    attempts: STREAM_CONNECT_ATTEMPTS)
+      count = 0
+      while count < attempts
+        count += 1
+        connection = connect_stream(query: query, last_event_id: last_event_id, timeout: header_timeout)
+        if connection
+          sock, status, headers = connection
+          unless !block_given? || yield(sock)
+            sock.close rescue nil
+            return StreamOpen::Unreachable.new(attempts: count)
+          end
+          return StreamOpen.classify(sock, status, headers)
+        end
+        sleep(0.15 * count) if count < attempts
       end
+      StreamOpen::Unreachable.new(attempts: count)
+    rescue Errno::ETIMEDOUT
+      StreamOpen::Unreachable.new(attempts: [count, 1].max)
+    rescue SystemCallError, SocketError, IOError
+      StreamOpen::Unreachable.new(attempts: [count, 1].max)
+    end
 
+    # Read a successful stream opened by #open_stream.
+    # @param opened [StreamOpen::Opened]
+    # @param running [#call, nil] checked before every read and every
+    #   STREAM_POLL seconds of silence
+    def read_stream(opened, running: nil)
+      sock = opened.sock
       begin
         loop do
           if running
             break unless running.call
             next unless sock.wait_readable(STREAM_POLL)
           end
-          chunk = sock.readpartial(4096)
-          yield chunk
+          yield sock.readpartial(4096)
         rescue IOError, Errno::ECONNRESET, Errno::ECONNREFUSED # EOFError is an IOError
           break
         end

data/lib/samagotchi/bridge_secret.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "chi_invocation"
 
 module Samagotchi
   # A session Bridge's secret, as both sides name it: the request header
@@ -12,16 +13,17 @@ module Samagotchi
     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
 
+    # What every client shows when a worker refuses its secret.
+    def refused(session_id, via: ChiInvocation::HERE)
+      web = via.remote? ? via.web : "chi web"
+      "session #{session_id}'s worker refused this chi's request (it didn't name its secret): a chi web or " \
+        "terminal started before chi was updated can't reach it; restart #{web}, re-attach with " \
+        "#{via.attach(session_id)}, or restart the worker with #{via.command("sessions restart #{session_id}")}"
+    end
+
     # Whether a Bridge reply (+status+, raw +body+) is this refusal.
     def refused?(status, body)
       return false unless status.to_i == 403