samagotchi 0.120.0 → 0.121.1

data/docs/internals/prompt-caching.md

@@ -79,11 +79,13 @@ right-hand column happens.
   `Toolkit::Resolved` the Registry holds, so a switch that changes only the text is a toolkit change
   (`apply_toolkit!` → `reset!`). `full` and kits without one send the bytes they sent before.
 - find_tools' description is a function of the toolkit and the source groups **at load**: `ToolIndex#declare`
-  snapshots the MCP groups' lines (name, summary, callable count) and `ToolIndex#refresh!` (from
-  `ToolkitBinding#apply!`) rebuilds only the `chi` line, the built-ins the toolkit reaches. An MCP server that
-  finishes booting between load and the first turn changes search answers only, so two sessions on the same
-  toolkit with the same MCP cache send the same bytes. Whether find_tools/call_tool are declared at all reads the
-  same two things (`Registry#index_needed?`), never live groups.
+  snapshots source group names and description lines (name, summary, callable count). `ToolIndex#refresh!` (from
+  `ToolkitBinding#apply!`) filters that snapshot by the new toolkit and rebuilds the `chi` line from the built-ins
+  it reaches; it never consults live group names. The same group filter drives searches, deferred MCP tools and
+  whether `find_tools`/`call_tool` are declared (`Registry#index_needed?`). An MCP server that finishes booting
+  between load and the first turn changes search answers only, so two sessions on the same toolkit with the same
+  MCP cache send the same bytes. Kits that omit `groups:` keep their previous request bytes; switching only
+  groups changes the prompt key and asks `/toolkit` to confirm the cache cost once the session has history.
 - A worker's `execute` and `task_create` descriptions carry the finish wake's sentence ("if you end your turn before
   it finishes, chi tells you when it does"; `Engine.new(task_finish_notes:)`, set once as the worker builds its
   Engine); the `--no-shared` REPL's, and a worker's under `session.task_wakes: off`, don't. A session that moves
@@ -240,4 +242,3 @@ is prefilled once. The native and the chat loop use the same plan.
   `cache_prompt: true` on every native request.
 - **OpenRouter / Anthropic:** the default cache TTL is 5 minutes (`cache.ttl: 1h` for an hour, see above).
   Provider routing (which upstream serves a request) also decides whether a cache is there to hit.
-

data/docs/internals/remote-sessions.md

@@ -289,11 +289,11 @@ bin/chi ── RunOptions.parse ── a remote, run flags ──> RemoteAttachC
 ### The plumbing
 
 **chi web's routes** (tabled in [architecture.md](../architecture.md)): `POST …/wake` (`Local#wake`: the live worker
-as is, else `SessionManager.resume_session` and `BridgeClient.wait_for`, at most `WAKE_MAX_WAIT` 10 s, the attach's
+as is, else `SessionManager.resume_session` and `WorkerLink.await`, at most `WAKE_MAX_WAIT` 10 s, the attach's
 `BRIDGE_WAIT` here, after waiting for a worker still leaving to let go of its lock, `OwnerLock.await_release`: its
 recap on leave's timeout plus 5 s; a leftover scratch session is refused in `LaunchMode::SCRATCH_LEFTOVER`'s words, a late Bridge
-in `LaunchMode::BRIDGE_LATE`'s) and `GET …/worker` (`Local#worker`: live, the stop marker, the owner, `leaving` and `leave_seconds` when its worker
-is leaving, `WorkerState#leaving?`; it never starts one; it also names that machine's `default_model`), both answering the worker as `{epoch, started_at, version,
+in `LaunchMode::BRIDGE_LATE`'s; a worker on a newer sidecar protocol is refused, 409 `worker_newer`, never resumed over) and `GET …/worker` (`Local#worker`: live, the stop marker, the owner, `leaving` and `leave_seconds` when its worker
+is leaving, `WorkerState#leaving?`, `stuck` for a worker that never published its Bridge, `skew` for a newer protocol; it never starts one; it also names that machine's `default_model`), both answering the worker as `{epoch, started_at, version,
 features}`; `POST …/exit` (the worker's exit, `client_id` passed on only when it is a `tui:` one), `POST …/recap`,
 `GET …/stats` (the stats, else an older worker's state metrics), `GET …/children/counts` (`ChildrenStatus.counts`)
 and `GET …/turns/:turn_id/records` (`SessionMetrics`' saved tool records and turn record), every refusal with
@@ -309,7 +309,7 @@ builtin the worker lacks names it (`command`). `/api/info`'s feature `remote_att
 **`SessionAccess::WebBridgeClient`** (`session_access/web_bridge_client.rb`, built by `Remote#attach_client(id,
 worker:)` from a wake's or worker read's `worker`): `post_turn` (`no_interrupt`, `history: false`), `post_command`,
 `answer`, `dismiss_question`, `dequeue`, `cancel`, `request_exit`, `request_recap`, `stats`, `children_counts`,
-`turn_records`, `follow`, `connect_stream`, `session_id`, `worker_key`, `port` (nil). One-shots go through
+`turn_records`, `follow`, `open_stream`, `session_id`, `worker_key`, `port` (nil). One-shots go through
 `Remote#route_request` (the server check, the auth and missing-route mapping), a new connection each, with a 45 s
 read timeout (chi web's 30 s Bridge read plus its wait for a waking Bridge; 75 s for answer and dismiss, which chi web
 sends twice on a 408; 5 s, `JOIN_READ_TIMEOUT`, for the join's reads: the children counts and a turn's records, L9). Every reply goes through **one status mapper**,
@@ -318,6 +318,7 @@ sends twice on a 408; 5 s, `JOIN_READ_TIMEOUT`, for the join's reads: the childr
 | chi web's answer | What the loop gets |
 |---|---|
 | 503 `not_live`, 404 `not_found` | raises `Unreachable` (< `IOError`): "no live worker for session ID on NAME" (`NO_WORKER`) |
+| 502 `bridge_secret` (stream) | `Refused(:bridge_secret)`; `EventStream` ends with `stream_closed bridge_secret` |
 | 504 (any) | `Response(408, {error: deadline_passed})`: the loop's late line |
 | 501 with `command` (`/command`) | `Response(400, {error: unknown_command, command})`: the loop names the command |
 | any other 501 | `Response(404, {error: not_found})`: the stale-worker line |
@@ -326,7 +327,7 @@ sends twice on a 408; 5 s, `JOIN_READ_TIMEOUT`, for the join's reads: the childr
 Every `RemoteFailed` (a transport failure, `RemoteTooOld`, a 401 or a 403 `forbidden`) becomes `Unreachable` with its
 message, so a loop that rescues `IOError` around Bridge calls never crashes on one mid-session.
 
-**The stream.** `connect_stream` writes `GET /api/sessions/:id/stream…` through `BridgeClient::StreamRequest` (the
+**The stream.** `open_stream` writes `GET /api/sessions/:id/stream…` through `BridgeClient::StreamRequest` (the
 GET a local stream writes, with `Authorization: Bearer` and `Last-Event-ID`; `Host` is the entry's host and port).
 An IPv6 entry (`http://[::1]:4567`) connects on the bare address (`URI#hostname`, as `HTTPTransport` does) and keeps
 the brackets in `Host`.
@@ -335,7 +336,9 @@ SYN isn't waited on for the OS's minutes on every reconnect.
 chi web proxies the Bridge's bytes unchanged (under WEBrick a hijacked body is raw, `Connection: close`). No chunked
 decoding in v1: a `Transfer-Encoding: chunked` reply (a proxy in between) and an https entry are logged
 (`stream_refused`, `chunked_unsupported` / `tls_unsupported`) and read as unreachable; decoding and TLS plug into
-`StreamRequest`. `follow` starts `EventStream` with three options a local stream never sets (`BridgeClient#follow`
+`StreamRequest`. `WebBridgeClient#open_stream` returns typed outcomes: chi web's 502 `bridge_secret` is a refusal
+(`stream_closed bridge_secret`), 503 is unreachable and retried with rediscovery, and 404 is an unknown-session
+refusal. `follow` starts `EventStream` with three options a local stream never sets (`BridgeClient#follow`
 passes none):
 - `idle_timeout:` 40 s (`STREAM_IDLE_TIMEOUT`: two of the Bridge's 15 s pings plus margin): no byte for that long is a
   half-open connection (Wi-Fi gone, a sleeping laptop), reconnected with the cursor.
@@ -343,8 +346,9 @@ passes none):
   `worker_changed {"port" => nil, "epoch" => new}` comes before it (the `reset` the new Bridge sends), and the
   client's `worker_key` is updated in place. A restart reaches the stream this way because `Bridge#stop` removes its
   sidecar before it ends the open streams: the reconnect finds no sidecar, chi web waits for the next worker's
-  (`await_bridge_port`) and proxies the cursor to it. A sidecar still naming the dead port would get an empty 200
-  (the proxy's connects refused), and the stream would move by rediscovery (`worker_changed`, then a `snapshot`).
+  (`await_worker_link`) and proxies the cursor to it. A sidecar still naming a dead port now gets 503 `not_live`;
+  a secret refusal gets 502 `bridge_secret`, and no refusal is sent as SSE frames. The stream moves by rediscovery
+  (`worker_changed`, then a `snapshot`).
 - `announce_retries:` `stream_retrying` once a reconnect fails and rediscovery neither moved the stream nor ended it
   (a stop prints its stopped line alone), `stream_resumed` once a stream answers again (a replay may bring no frame).
 
@@ -421,9 +425,9 @@ the closing line reads `stopped` as `unreachable`, the words it always had.
     TUI (`tui:PID` otherwise). `report_unanswered` takes the link's `strategy:` and `via:`.
   - The client the loop and `BridgeClient::EventStream` use: `follow`, `post_turn`, `post_command`, `answer`,
     `dismiss_question`, `dequeue`, `cancel`, `request_exit`, `request_recap`, `session_id`, and for the stream
-    `connect_stream(query:, last_event_id:, timeout:)` and `worker_key` (a new worker is a client with another key;
-    a Bridge's is its port). `BridgeClient::StreamRequest` writes the stream's GET (host, port, path, extra headers)
-    and reads its headers, for a stream through chi web too.
+    `open_stream(query:, last_event_id:, header_timeout:, attempts:)` and `worker_key` (a new worker is a client with
+    another key; a Bridge's is its port). `EventStream` reads the opened socket; `BridgeClient::StreamRequest`
+    writes the stream's GET (host, port, path, extra headers) and reads its headers, for a stream through chi web too.
   - `RunOptions.parse(argv)` is bin/chi's one run-flag parser (`RunOptions.switches` lists its flags), so a remote
     branch can take the parsed options before bin/chi's local checks; `LaunchMode.attached_conflict` and
     `LaunchMode::SCRATCH_LEFTOVER` / `BRIDGE_LATE` are the words both would print.

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

@@ -579,13 +579,17 @@ end
 - Each task runs once per session start. A `-p … --non-interactive` run
   starts them with its turn and shows nothing but the answer.
 
-### `chi.toolkit(name, base:, add: [], remove: [], prompt: nil)`
+### `chi.toolkit(name, base:, add: [], remove: [], prompt: nil, groups: nil)`
 
 A toolkit sessions can be put on: `base`'s tools (`full`, `lean`, `child`, a
 config or bundle toolkit) with `add` declared and `remove` left out, and
 `prompt`: text the sessions on it get in their system prompt, verbatim (nil
 inherits the base's, `""` clears it; at most 2000 characters, and one that
-isn't a String or is longer is a load error). Users pick
+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; 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
 `-`; one chi has (`full`, `lean`, `child`) or another bundle declared is a
@@ -593,11 +597,13 @@ load error. A session saved on a toolkit whose bundle is gone declares every
 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"`).
+`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"` (`chi bundle check` warns on a lower one).
 
 ```ruby
 chi.toolkit "review", base: "lean", add: %w[delegate delegate_result]
 chi.toolkit "coding", base: "child", prompt: "- Be concise in your responses"
+chi.toolkit "web", base: "lean", groups: %w[chrome db*]
 ```
 
 ### `chi.tool_source(call:, acts_as:, label:, wait:, prefix:)`
@@ -611,12 +617,19 @@ first source's `label`). The index has one group of its own, **`chi`**: the
 built-ins the session's toolkit leaves out but doesn't remove
 ([toolkits](configuration.md#toolkits)), each with its registered schema.
 The two tools are registered once, after the plugins load, and declared per
-toolkit: when a plugin registered a source then, or when the toolkit has a
-reachable built-in (`full` with no source declares neither). Nothing a
+toolkit when it reaches a source group or has a reachable built-in (`full`
+with no source declares neither). Nothing a
 source publishes later changes the request's tools, only what a search
 answers, so the prompt cache keeps: the search tool's description lists the
 source groups as they were at load, and a `chi` line first, per toolkit.
-The mcp bundle is the only source so far (a group per server). A source's
+The mcp bundle is the only source so far (a group per server). `groups:`
+filters the groups find_tools searches, the source descriptions in the
+request, and the MCP tools `call_tool` can reach. Its group snapshot is
+filtered again at each toolkit change; new groups published after load do
+not alter that prompt description. An unreached MCP tool call is refused
+before the guardrails without starting the server; a deferred stub says to
+switch to a toolkit that reaches its group. `/mcp` marks servers outside the
+session's toolkit. A source's
 group named `chi`, or named like an earlier group, is left out of search,
 lookup and the description, with one warning per name.
 
@@ -1002,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
@@ -1377,8 +1393,12 @@ bundles:
   its tools as `(failed: …)`. The saved list stays: the next session tries
   again.
 - **`start: eager`** on a server starts it with every session (in an init
-  task, after the Bridge is up), for a server whose start does something
-  you want at once.
+  task, after the Bridge is up), even when that session's toolkit does not
+  reach its group. A first-run init task still blocks the first turn until
+  it finishes, even for an unreached group. A stale-cache refresh likewise
+  starts its short-lived server regardless of the toolkit. Switching away
+  from a group refuses its calls without starting a lazy cached server, and
+  does not stop a server already running; switching back reuses it.
 - **`npx -y …@latest` checks the npm registry on every start** (~3.4 s for
   `chrome-devtools-mcp`, against ~0.9 s for the installed binary). The cache
   hides it from new sessions, but not from the first call. For a faster first

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`,
@@ -230,7 +265,9 @@ A builder runs these while working, not the full suite: the specs the change tou
 files it changed (`lib/samagotchi/foo/bar.rb` → `spec/foo/bar_spec.rb`, `bar_*_spec.rb`…), the specs that read
 docs or source as text (its `RULES`: add one when a full run catches what the names missed) and the golden of a changed
 file's layer (any `terminal_ui/*.rb` → `spec/terminal_ui_golden_spec.rb`; `turn_flow.rb` and `turn_note.rb`, whose
-words the REPL prints, pick it by a rule), then the other name matches (a spec named after several changed files first, e.g. `engine_toolkit_spec.rb` for `engine.rb` and
+words the REPL prints, pick it by a rule). Changes to `tool_declarations.rb` and `system_prompt.rb` also pick the
+effective-model, request, prompt-snapshot and full system-prompt goldens because they hash the request's prompt and
+tools. Then come the other name matches (a spec named after several changed files first, e.g. `engine_toolkit_spec.rb` for `engine.rb` and
 `toolkit.rb`; then one beside the file, so `plugin/context.rb` picks `spec/samagotchi/plugin/*context*` before
 `spec/guardrails/context_spec.rb`), then the specs that name a method the change touches (the innermost `def` around a
 changed line, read with Prism; one `git grep` for up to 12 names; names under 4 characters, `initialize`, `to_s`,
@@ -355,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.