samagotchi 0.153.0 → 0.154.1

data/docs/testing.md

@@ -30,6 +30,11 @@ stage's hand-off dwell in stage.spec.js); a pause that is the behaviour outside
 route) carries `// eslint-disable-line no-restricted-syntax -- why`. And in the seven
 modules that hold the owner page's session state, one more: no write into `current`, `store.current` or `state()`
 in place (`samagotchi/session-writes`; the store is the write path, see internals/web-frontend.md, The session store).
+In `spec/web/public/`, one rule only (`samagotchi/dom-null-asserts`): no `assert.equal(domNode, null)`. When it fails,
+node's assert formats the happy-dom node, whose graph (its document, its window) takes minutes and gigabytes, so
+`npm test` hangs instead of failing (`--test-timeout` doesn't end it). Write `assert.ok(x === null)` (or `=== undefined`),
+which names the expression and fails at once. The rule sees a DOM lookup by its shape (`querySelector`, `closest`,
+`parentElement`…); a helper that returns a node (`h.input()`) isn't seen, so the same form goes there by hand.
 
 CI's e2e job keeps the tests, chi and the fake model on the runner but runs Chromium in Playwright's image
 (`mcr.microsoft.com/playwright:v<version>-noble`, `playwright run-server` on the host network); the tests connect
@@ -39,7 +44,9 @@ moves the image too (`spec/ci_playwright_image_spec.rb` keeps a pinned tag out o
 that way locally: `npx playwright run-server --port 3333`, then `PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:3333/ npm run e2e`.
 
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
-clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
+clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock). `TMPDIR` is a folder of the
+run's own (`SPEC_TMPDIR`, removed at the end), so a spec's bare `Dir.mktmpdir` or `Dir.tmpdir`, and what chi writes or
+sweeps beside it, never touches your real `$TMPDIR`. A spec can't assume that path's length: it is your `$TMPDIR`'s plus one folder.
 It also clears what tells git which repo to act on (`GIT_DIR`, `GIT_WORK_TREE`, the rest of
 `git rev-parse --local-env-vars`: `GitEnv`), first thing in `spec_helper.rb` and as the bundle test kit's
 adapters load, so a run from `git rebase --exec`, `bisect run` or a hook can't reach the real repo through a spec's git.
@@ -53,6 +60,21 @@ paths (replace them with placeholders), no PATH tools (the suite pins `rg` as fo
 that sets PATH to test the lookup is tagged `:real_rg`), no Ruby-version-dependent `inspect` (a Hash's or an
 exception's text changes between Ruby versions: write the string yourself).
 
+The whole-turn goldens (`spec/engine_turn_golden_spec.rb`, `spec/fixtures/turn_goldens/`) run a real
+`Engine#run_turn` (its own KernelLoop, ChatLoop, ToolRunner, Gate and GuardrailWiring) over `FakeProviderServer` on
+the native (llama.cpp `/completion`, Qwen tool calls), `api: openai` and `api: anthropic` wires: a turn of two tool
+iterations (a muted `memory_read` and a `read`, then a `write` a config rule asks about, allowed through the question
+flow), a `before_turn` hook switching the model (the request names the new model with the old one's sampling), and a
+review participant's turn whose `write` the review boundary refuses. Each golden pins every request (the chi-set
+headers, the body in its key order, the native prompt as text), the turn's events (keys sorted; the context-status
+estimates and clock values masked), each `before_tool_call` payload, the approval asked and the session's messages.
+System 1, the toolkit suggestion, the context judge, the recap and the warm-up are off by config, so the order is the
+turn's own. The arch P3 refactors (TurnContext, turn stages, ToolSurface) keep them byte-identical: a phase that
+changes one stops and asks. An intended change elsewhere: `UPDATE_PROMPTS=1 bundle exec rspec
+spec/engine_turn_golden_spec.rb`, then read `git diff spec/fixtures/turn_goldens/`; a failure writes what the run got
+to `tmp/turn_goldens/<golden>.actual` and names the `diff` to run. Changes to the turn path (engine, kernel loop, chat loop,
+tool runner, gate, guardrail wiring, system prompt, tool declarations, registry) pick it in `script/affected-specs`.
+
 The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_block.js`,
 `turn_html.js`, `card.js`, `copy.js`, `images.js`, `scope.js`, `command_view.js`, `diff_view.js`, `read_view.js`,
 `question_cards.js`, `stream_handlers.js`, `stage_view.js`, `bubbles.js`, `cards_place.js`, the chips, `info_bar.js`, `info_bar_model.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
@@ -74,11 +96,11 @@ back (`t.mock` restores itself). A test that sets off a module's timer (a flash,
 node running until it fires (a 4 s one made the run 6 s for 2 s of work). One file:
 `node --test spec/web/public/NAME.test.js`.
 
-Where a composer line goes is decided twice, in Ruby (`ComposerRoute`, both terminals) and in the web
+Where a composer line goes is decided twice, in Ruby (`ComposerRoute`, the attached terminal) and in the web
 (`composer.js#routeComposerLine`). `spec/fixtures/composer_routes.json` holds the cases both answer: rspec
 (`spec/composer_route_spec.rb`) and `npm test` (`spec/web/public/composer.test.js`) run every row. A change to
-either router adds its row there; a row where a UI differs on purpose (or a found divergence) carries a `web` or
-`repl` override and a `note`. The Ruby side runs each row with every core command (a new one fails its
+either router adds its row there; a row where a UI differs on purpose (or a found divergence) carries a `web`
+override and a `note`. The Ruby side runs each row with every core command (a new one fails its
 `CORE_ROUTES` check until listed there); a row's names that core lacks stand for plugin commands.
 
 ## Levels
@@ -174,6 +196,9 @@ whose value is dropped, an example's last line included, `expect(wait_until {
 `Timeout.timeout`, or a statement `thread.join(N)`, whose N is unscaled and whose nil is dropped: use `join!`) live in `rubocop/` and run in `rake lint`, so CI fails on them. RSpec counts `wait_for`,
 `eventually`, `join!` and `pop!` as an example's expectation (`RSpec/NoExpectationExample`), so a wait can be an
 example's last line. What the cops can't see, `script/affected-specs` hints at (`timing:`, below).
+One lib cop sits beside them: `Samagotchi/SilentRescue` (a `rescue` of StandardError whose body is only a literal,
+`nil`, `[]`…: use `Degrade`, or tag a right silence `# degrade-ok: why`; docs/internals/engine.md, Degrading). The
+files that had such rescues when it came are excluded in `.rubocop.yml`: that list only shrinks.
 
 ### Flakes
 
@@ -308,8 +333,8 @@ 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`…;
 `lib/samagotchi/foo/bar/baz.rb` → `spec/foo/bar_baz_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). Changes to `tool_declarations.rb` and `system_prompt.rb` also pick the
+file's layer (any `foo/*.rb` → `spec/foo_golden_spec.rb` when there is one; `turn_flow.rb` and `turn_note.rb`, whose
+words the attached TUI prints, pick its `event_renderer` and `attached_loop` specs 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

data/lib/samagotchi/answer_text.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "model_profile"
+require_relative "output_formatter"
+require_relative "tool_call_parser"
+
+module Samagotchi
+  # What the user saw of a model entry's text: the one rule for the continue
+  # note's last answer (SessionChain.last_answer), a check's record of the
+  # agent's own words (ObjectivesCheck) and a bundle's ctx.last_answer. A chat
+  # entry's content is that already (its reasoning is the separate :thinking,
+  # its calls :tool_calls); a native entry's is the raw response, with its
+  # thoughts and call markup inline: both hosts' thoughts come out, a thought
+  # cut off before it closed too, then the calls and the wire tokens.
+  module AnswerText
+    # The template opened the block, so the text starts inside it.
+    TEMPLATE_OPENED_THINK = %r{\A.*?</think>}m
+
+    module_function
+
+    # @param text [String, nil]
+    # @return [String] "" when nothing was visible
+    def visible(text)
+      text = text.to_s.scrub
+      template_opened = !text.include?("<think>")
+      gemma = ToolCallParser::Gemma.new(ModelProfile.gemma4)
+      text = gemma.strip_thought(text).gsub(OutputFormatter::QWEN_THINK_RE, "")
+      text = text.sub(TEMPLATE_OPENED_THINK, "") if template_opened
+      text = ToolCallParser.strip_calls(gemma.strip_tool_calls(text), "<tool_call>", "</tool_call>")
+      OutputFormatter.strip_markup(text) # drops a thought cut off before it closed
+    end
+  end
+end

data/lib/samagotchi/bridge/card_places.rb

@@ -9,16 +9,22 @@ module Samagotchi
     # the recap share (Steer.turn_opening?); the store's turn log only orders
     # the ids. So a turn with no opening (a reminder, a Continue, a failed or
     # rolled-back one, a prompt stopped before the model) counts nothing, and
-    # an opening with no id (/continue no's reason, Qwen's recovery line) counts
-    # as it does on the page. Nothing orders such an opening against an entry, so
-    # an entry says how many it came after (+past_idless+, #idless_after). Pure:
-    # no Engine, no file.
+    # an opening with no turn id (/continue no's reason) counts as it does on
+    # the page. Nothing orders such an opening against an entry, so
+    # an entry says how many it came after (+past_idless+, #idless_after), and
+    # which one that is when it has an id (+after_opening+, #after_opening).
+    #
+    # The same place as a stamp (#opening_of): the id of the opening the entry
+    # comes after (a prompt's turn_id, a line's opening_id), which the page
+    # finds by its bubble, not by counting. Pure: no Engine, no file.
     class CardPlaces
       # @param turn_log [Array<String>] the turn ids, oldest first
       # @param messages [Array<Hash>] the messages the page draws
       def initialize(turn_log, messages)
         positions = turn_log.each_with_index.to_h
-        @ids = Array(messages).select { |message| Steer.turn_opening?(message) }.map { |message| message[:turn_id] || message["turn_id"] }
+        openings = Array(messages).select { |message| Steer.turn_opening?(message) }
+        @ids = openings.map { |message| message[:turn_id] || message["turn_id"] }
+        @stamps = openings.map { |message| stamp_of(message) }
         @openings = @ids.size
         @opened = @ids.compact.to_set
         @places = @ids.map { |id| positions[id] }
@@ -45,13 +51,44 @@ module Samagotchi
         entry[:base_since].to_i + since
       end
 
+      # The opening +entry+ comes after, as #turns_since counts: its id (a
+      # prompt's turn_id, a line's opening_id), the page's stamp. nil when it
+      # comes before every opening, when that opening has no id (a line an
+      # older chi wrote), or for an entry from an older file (+base_since+):
+      # the page counts those (turns_since).
+      # @param entry [Hash] a store's entry: :turn_id, :past_idless, :after_opening, :base_since
+      # @return [String, nil]
+      def opening_of(entry)
+        return nil if entry[:base_since]
+
+        at_or_before = counted_from(entry[:turn_id])
+        return nil unless at_or_before
+
+        run = at_or_before..(at_or_before + idless_run(at_or_before))
+        # The line it saved it came after, while that line is in the run (as
+        # the count past it, the two save together); else the count's.
+        after = entry[:after_opening] && @stamps.index(entry[:after_opening])
+        @stamps[after && run.cover?(after) ? after : [at_or_before + entry[:past_idless].to_i, run.end].min]
+      end
+
+      # The id of the last opening with no turn id right after the one
+      # +turn_id+ counts from (#idless_after's run), nil when there is none or
+      # it has no id either.
+      # @return [String, nil]
+      def after_opening(turn_id)
+        at_or_before = counted_from(turn_id)
+        return nil unless at_or_before
+
+        run = idless_run(at_or_before)
+        run.positive? ? @stamps[at_or_before + run] : nil
+      end
+
       # The openings with no id right after the one +turn_id+ counts from: what
       # an entry shown now has come after. A rollback can only shorten the run, so
       # a count read back against it never eats a later turn.
       # @return [Integer]
       def idless_after(turn_id)
-        position = @positions.fetch(turn_id, -1)
-        at_or_before = position >= 0 ? @last_at_or_before[position] : nil
+        at_or_before = counted_from(turn_id)
         at_or_before ? idless_run(at_or_before) : 0
       end
 
@@ -70,6 +107,18 @@ module Samagotchi
 
       private
 
+      # The last opening whose turn is at or before +turn_id+'s in the log
+      # (an index into the openings), nil for none.
+      def counted_from(turn_id)
+        position = @positions.fetch(turn_id, -1)
+        position >= 0 ? @last_at_or_before[position] : nil
+      end
+
+      def stamp_of(message)
+        id = message[:turn_id] || message["turn_id"] || message[:opening_id] || message["opening_id"]
+        id.is_a?(String) && !id.empty? ? id : nil
+      end
+
       def idless_run(opening)
         @ids.drop(opening + 1).take_while(&:nil?).size
       end

data/lib/samagotchi/bridge/card_store.rb

@@ -26,7 +26,9 @@ module Samagotchi
     # holds the id of the turn it belongs to or follows (+turn_id+: the running
     # turn's, else the last one's, nil before any) and lists with +turns_since+,
     # the turns drawn after it, counted from the messages the page draws
-    # (CardPlaces, with the turn log the store keeps), and +current+ for a card
+    # (CardPlaces, with the turn log the store keeps), +opening_id+, the same
+    # place as a stamp (the id of the opening it comes after, which the page
+    # finds by its bubble; none where only the count can say), and +current+ for a card
     # of the turn running now. A card that isn't the turn's but comes while one
     # runs (an anytime command's, such as /btw) goes after that turn: its prompt
     # is already in the history. Listed against messages, an in-turn entry of a
@@ -70,7 +72,7 @@ module Samagotchi
       SAVED_ON = (%i[turn_started card hook_notice empty_answer_retry steer_cut llm_context_edited question_requested question_answered
                      question_cancelled question_relay] + Events::TURN_END).freeze
       # What only the store reads: never listed.
-      INTERNAL_FIELDS = %i[turn_id continued base_since past_idless during after_failed command].freeze
+      INTERNAL_FIELDS = %i[turn_id continued base_since past_idless after_opening during after_failed command].freeze
 
       # What a session's saved file lists, as a store started from it lists
       # (no turn running): the web's cards for a session no worker runs.
@@ -118,7 +120,8 @@ module Samagotchi
       #   them (a body re-read, a trace): no turns_since:, nothing to tell a turn
       #   that left nothing by.
       # @return [Array<Hash>] oldest first: the card's (or notice's) fields
-      #   plus current:, turns_since: with +messages+, earlier: true for one an
+      #   plus current:, turns_since: and opening_id: (CardPlaces#opening_of,
+      #   when it has one) with +messages+, earlier: true for one an
       #   earlier worker saved, during: true for a card that came while the
       #   running turn runs but isn't that turn's (it goes after the running
       #   turn's prompt), and after_failed: true for one shown after the last
@@ -141,6 +144,8 @@ module Samagotchi
 
         out = shown.except(*INTERNAL_FIELDS)
         out[:turns_since] = places.turns_since(entry) if places
+        stamp = places&.opening_of(entry)
+        out[:opening_id] = stamp if stamp
         out[:current] = current
         out[:during] = true if entry[:during]
         out[:after_failed] = true if entry[:after_failed] && entry[:turn_id] == @failed_turn
@@ -255,7 +260,7 @@ module Samagotchi
       # A hand-edited or foreign file's entry goes, rather than break every later
       # listing of the session.
       def sound_place?(entry)
-        return false unless entry[:turn_id].nil? || entry[:turn_id].is_a?(String)
+        return false unless [entry[:turn_id], entry[:after_opening]].all? { |id| id.nil? || id.is_a?(String) }
 
         entry.values_at(:base_since, :past_idless).compact.all? { |count| count.is_a?(Integer) && !count.negative? }
       end
@@ -315,8 +320,8 @@ module Samagotchi
         shown = @entries.select { |entry| entry[:turn_id] == @running_turn && !entry[:in_turn] }
         return if shown.empty? || !@messages
 
-        run = CardPlaces.new(@turn_log, @messages.call).idless_after(@running_turn)
-        shown.each { |entry| entry[:past_idless] = run if run.positive? }
+        places = CardPlaces.new(@turn_log, @messages.call)
+        shown.each { |entry| note_idless(entry, places) }
       end
 
       # The entry's anchor: the running turn, else the last one.
@@ -331,7 +336,7 @@ module Samagotchi
           # button's command replaced, which nobody typed).
           old = @entries[index]
           @entries[index] = card.except(:command).merge(updated: true, **old.slice(:in_turn, :turn_id, :during, :continued, :base_since,
-                                                                                   :past_idless, :after_failed, :command))
+                                                                                   :past_idless, :after_opening, :after_failed, :command))
         else
           entry = card.merge(in_turn: event[:in_turn] ? true : false, turn_id: anchor)
           entry[:during] = true if @running_turn && !event[:in_turn]
@@ -393,8 +398,18 @@ module Samagotchi
       def note_past_idless(entry)
         return unless @messages
 
-        run = CardPlaces.new(@turn_log, @messages.call).idless_after(entry[:turn_id])
-        entry[:past_idless] = run if run.positive?
+        note_idless(entry, CardPlaces.new(@turn_log, @messages.call))
+      end
+
+      # How many openings with no turn id +entry+ came after, and the last
+      # one's own id when it has one (+after_opening+: its stamp, #list).
+      def note_idless(entry, places)
+        run = places.idless_after(entry[:turn_id])
+        return unless run.positive?
+
+        entry[:past_idless] = run
+        after = places.after_opening(entry[:turn_id])
+        entry[:after_opening] = after if after
       end
 
       # Which cap +entry+ counts against: :notice, :llm_context or :card.

data/lib/samagotchi/bridge.rb

@@ -9,6 +9,7 @@ require "openssl"
 require "time"
 require_relative "atomic_file"
 require_relative "bridge_secret"
+require_relative "degrade"
 require_relative "delivery"
 require_relative "session_inbox"
 require_relative "turn_anchors"
@@ -156,6 +157,9 @@ module Samagotchi
       # Open streams by the client_id a stream named (`?client_id=`); web
       # tabs, through the `chi web` proxy, name none.
       @streams_by_client = Hash.new(0)
+      # Streams served since the start, open or closed (a scratch worker
+      # leaves once its terminal's has gone: Worker#scratch_unattended?).
+      @streams_served = 0
       @last_client_activity_at = monotonic_now
     end
 
@@ -178,6 +182,11 @@ module Samagotchi
       @mutex.synchronize { @open_streams }
     end
 
+    # @return [Integer] SSE streams served since the Bridge started
+    def streams_served
+      @mutex.synchronize { @streams_served }
+    end
+
     # Streams held by anyone but +client_id+: a client's own stream (or two,
     # while it reconnects and the old one isn't noticed dead yet) doesn't
     # count. A closed stream stops counting once its writer reads the
@@ -187,6 +196,15 @@ module Samagotchi
       @mutex.synchronize { @open_streams - (client_id ? @streams_by_client[client_id] : 0) }
     end
 
+    # Streams held by the clients whose id starts with +prefix+
+    # (ClientId::TUI_PREFIX: the attached terminals, which a scratch worker
+    # counts, Worker#scratch_unattended?). A stream that named no client
+    # (a web tab's, through the chi web proxy) is none of them.
+    # @return [Integer]
+    def open_streams_of(prefix)
+      @mutex.synchronize { @streams_by_client.sum { |client_id, count| client_id.start_with?(prefix) ? count : 0 } }
+    end
+
     # Monotonic time of the last request, stream open or stream close. The
     # worker's idle exit counts from it. A connect that sends no request (the
     # sidecar liveness probe) doesn't count.
@@ -236,7 +254,7 @@ module Samagotchi
       @mutex.synchronize { @stopped = true }
       begin
         @server&.close
-      rescue StandardError
+      rescue StandardError # degrade-ok: stopping: a server socket already closed is fine
         nil
       end
       wake_acceptor
@@ -254,7 +272,7 @@ module Samagotchi
       @mutex.synchronize { @stopped = true }
       begin
         @server&.close
-      rescue StandardError
+      rescue StandardError # degrade-ok: stopping: a server socket already closed is fine
         nil
       end
       wake_acceptor
@@ -268,13 +286,13 @@ module Samagotchi
       # the web, which then queues the prompt again from the input file.
       await_answers(REQUEST_GRACE_SECONDS)
       remove_sidecar
-      @connection_threads.each { |t| t.kill rescue nil }
+      @connection_threads.each { |t| t.kill rescue nil } # degrade-ok: stopping: a thread already gone is fine
       @connection_threads.clear
       # Its relay watchers (RelayWatcher) end with it.
       watchers = @mutex.synchronize { (@relay_watchers || []).tap { @relay_watchers = [] } }
       watchers.each { |thread| thread.kill.join(RELAY_WATCHER_JOIN_SECONDS) }
       @accept_thread&.join(2)
-      [@wake_reader, @wake_writer].each { |io| io&.close rescue nil }
+      [@wake_reader, @wake_writer].each { |io| io&.close rescue nil } # degrade-ok: stopping: a closed pipe is fine
       nil
     end
 
@@ -399,9 +417,10 @@ module Samagotchi
     # O(1) and non-blocking.
     def capture_observer
       @capture_proc ||= proc do |event|
-        @ring.push(seq: event[:event_seq], data: event)
-      rescue StandardError
-        nil
+        # Per event: the first failure warns, the rest log at debug.
+        Degrade.call(:bridge, "event_capture_failed") do
+          @ring.push(seq: event[:event_seq], data: event)
+        end
       end
     end
 
@@ -527,7 +546,7 @@ module Samagotchi
       Thread.current[:bridge_answering] = false
       begin
         io.close
-      rescue StandardError
+      rescue StandardError # degrade-ok: the client may be gone already; closing is all that's left
         nil
       end
     end
@@ -555,6 +574,7 @@ module Samagotchi
       )
       @mutex.synchronize do
         @open_streams += 1
+        @streams_served += 1
         @streams_by_client[client_id] += 1 if client_id
       end
       begin
@@ -860,7 +880,7 @@ module Samagotchi
       end
     end
 
-    # Dismiss the pending question (an empty answer, as in the REPL): the
+    # Dismiss the pending question (an empty answer at a terminal): the
     # tool returns without an answer and every UI gets :question_cancelled.
     # Only the question the client saw, and only while nobody has answered
     # it: Engine#cancel_question checks both under the question lock. A past
@@ -1425,44 +1445,44 @@ module Samagotchi
     # else fall back to the explicit `?from_seq=` query param used by clients
     # that remember their own cursor.
     def reconnect_cursor(headers, query)
-      cursor = headers["last-event-id"]
-      return cursor if cursor && !cursor.empty?
+      Degrade.call(:bridge, "sse_cursor_unparsable") do
+        cursor = headers["last-event-id"]
+        return cursor if cursor && !cursor.empty?
 
-      return nil unless query
+        return nil unless query
 
-      URI.decode_www_form(query).to_h["from_seq"]
-    rescue StandardError
-      nil
+        URI.decode_www_form(query).to_h["from_seq"]
+      end
     end
 
     # `?snapshot=1`: join with a snapshot frame instead of a replay.
     def snapshot_requested?(query)
-      return false unless query
+      Degrade.call(:bridge, "snapshot_query_unparsable", fallback: false) do
+        return false unless query
 
-      URI.decode_www_form(query).to_h["snapshot"].to_s == "1"
-    rescue StandardError
-      false
+        URI.decode_www_form(query).to_h["snapshot"].to_s == "1"
+      end
     end
 
     # `?raw=1`: events as the engine emitted them (a chunk's provider
     # payload), not as clients get them (ClientEvent). For debugging on the
     # worker's port: chi web never passes it on.
     def raw_requested?(query)
-      return false unless query
+      Degrade.call(:bridge, "raw_query_unparsable", fallback: false) do
+        return false unless query
 
-      URI.decode_www_form(query).to_h["raw"].to_s == "1"
-    rescue StandardError
-      false
+        URI.decode_www_form(query).to_h["raw"].to_s == "1"
+      end
     end
 
     # `?client_id=`: whose stream it is (see #open_streams_except).
     def stream_client_id(query)
-      return nil unless query
+      Degrade.call(:bridge, "client_id_query_unparsable") do
+        return nil unless query
 
-      id = URI.decode_www_form(query).to_h["client_id"].to_s
-      id.empty? ? nil : id
-    rescue StandardError
-      nil
+        id = URI.decode_www_form(query).to_h["client_id"].to_s
+        id.empty? ? nil : id
+      end
     end
 
     def close_after_request?(headers)
@@ -1534,11 +1554,11 @@ module Samagotchi
     # 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
+      Degrade.call(:bridge, "sidecar_remove_failed") do
+        return unless @server
 
-      File.unlink(WorkerSidecar.path(session_dir)) if WorkerSidecar.read(session_dir)&.epoch == @epoch.to_s
-    rescue StandardError
-      nil
+        File.unlink(WorkerSidecar.path(session_dir)) if WorkerSidecar.read(session_dir)&.epoch == @epoch.to_s
+      end
     end
 
     def session_dir

data/lib/samagotchi/bridge_client.rb

@@ -4,6 +4,7 @@ require "digest"
 require "json"
 require "socket"
 
+require_relative "degrade"
 require_relative "worker_sidecar"
 require_relative "bridge_secret"
 require_relative "delivery"
@@ -308,12 +309,16 @@ module Samagotchi
     # older worker's 404 for a route it lacks from a refused connect, a
     # timeout or a 500.
     # @return [Array(Integer, Object)] the status and the parsed JSON body
-    #   (nil when it isn't JSON); [nil, nil] when no reply came
+    #   (nil when it isn't JSON); [nil, nil] when no reply came (a refused
+    #   connect, a timeout, a cut or garbled reply), and when anything else
+    #   failed, which is logged
     def get(path)
-      response = get_response(path)
-      [response.status, response.json]
-    rescue StandardError
-      [nil, nil]
+      Degrade.call(:bridge, "get_failed", fallback: [nil, nil], path: path) do
+        response = get_response(path)
+        [response.status, response.json]
+      rescue SystemCallError, IOError
+        [nil, nil]
+      end
     end
 
     # GET /session/:id/<path>, preserving the raw response and raising on I/O.
@@ -329,17 +334,17 @@ module Samagotchi
       body = response.split("\r\n\r\n", 2)[1] || ""
       Response.new(status: status.to_i, body: body)
     ensure
-      sock&.close rescue nil
+      sock&.close rescue nil # degrade-ok: done with the socket; one already closed is fine
     end
 
     # Monotonic SSE cursor of the live Engine, from GET /session/:id/state.
     # @return [Integer, nil]
     def event_seq
-      state = get_json("state")
-      seq = state && state.dig("session_state_snapshot", "event_seq")
-      seq.nil? ? nil : seq.to_i
-    rescue StandardError
-      nil
+      Degrade.call(:bridge, "event_seq_unreadable") do
+        state = get_json("state")
+        seq = state && state.dig("session_state_snapshot", "event_seq")
+        seq.nil? ? nil : seq.to_i
+      end
     end
 
     # Open GET /session/:id/stream and classify the response before the
@@ -358,7 +363,7 @@ module Samagotchi
         if connection
           sock, status, headers = connection
           unless !block_given? || yield(sock)
-            sock.close rescue nil
+            sock.close rescue nil # degrade-ok: the stream is given up; a socket already closed is fine
             return StreamOpen::Unreachable.new(attempts: count)
           end
           return StreamOpen.classify(sock, status, headers)
@@ -389,7 +394,7 @@ module Samagotchi
           break
         end
       ensure
-        sock&.close rescue nil
+        sock&.close rescue nil # degrade-ok: done with the socket; one already closed is fine
       end
     end
 
@@ -435,7 +440,7 @@ module Samagotchi
       body = read_body ? reply.split("\r\n\r\n", 2)[1] : nil
       Response.new(status: reply[STATUS_LINE, 1].to_i, body: body)
     ensure
-      sock&.close rescue nil
+      sock&.close rescue nil # degrade-ok: done with the socket; one already closed is fine
     end
 
     # The reply up to the Bridge's close (or its first line only), within

data/lib/samagotchi/broadcast/recipients.rb

@@ -12,7 +12,7 @@ module Samagotchi
     # A session a broadcast may concern.
     # @!attribute project [String, nil] its git project's root
     # @!attribute live [Boolean] a worker runs it now
-    # @!attribute owner [String, nil] "worker", "tui" (a chi REPL, which
+    # @!attribute owner [String, nil] "worker", "tui" (a one-turn chi run, which
     #   takes no notes) or nil
     Recipient = Data.define(:id, :short_id, :project, :cwd, :desc, :live, :owner) do
       def repl? = owner == "tui"
@@ -20,7 +20,7 @@ module Samagotchi
 
     # Who a broadcast goes to: the user's own sessions, not delegate
     # children (their parent relays what concerns them) and not scratch
-    # ones, that a worker or a chi REPL runs now or that ended a turn in
+    # ones, that a worker or a one-turn chi run runs now or that ended a turn in
     # the last +active_hours+. Forks count: they are the user's sessions.
     # Archived sessions don't; test runs only when chi runs as one.
     module Recipients

data/lib/samagotchi/broadcast/triage.rb

@@ -23,7 +23,7 @@ module Samagotchi
       # @!attribute by [String] who decided: "tags" (a shared tag),
       #   "model", "fallback" (delivered unchecked: deadline, error, an
       #   answer that is no yes or no), "scope" (the note's first line
-      #   names another project), "all" (--all) or "repl" (a chi REPL owns
+      #   names another project), "all" (--all) or "repl" (a one-turn chi run owns
       #   it: no notes)
       # @!attribute match [Match, nil] the shared tag (by "tags")
       Verdict = Data.define(:relevant, :p, :reason, :by, :match) do

data/lib/samagotchi/broadcast_command.rb

@@ -46,7 +46,7 @@ module Samagotchi
         note from "broadcast": background the model sees on its next turn,
         not a prompt. It starts no turn.
         Recipients: your own sessions (not delegate children, not scratch
-        ones) that a worker or a chi REPL runs now, or that ended a turn in
+        ones) that a worker or a one-turn chi run runs now, or that ended a turn in
         the last broadcast.active_hours (8). One gets the note when it shares
         a tag with it: a ticket id (PAY-123) in its branch or your prompts
         there, a pull request (PR #42, its URL) attached to it, a link in
@@ -190,13 +190,13 @@ module Samagotchi
                                                    corrections: []), decisions, cards)
     end
 
-    # Every recipient's verdict: a chi REPL takes no notes, --all takes the
+    # Every recipient's verdict: a one-turn chi run takes no notes, --all takes the
     # rest, else Broadcast::Triage (tags, the scope line, the model).
     # @return [Array<Decision>] in +recipients+' order
     def decide(text, recipients, cards, note_tags, all:)
       fixed = recipients.to_h do |r|
         verdict = if r.repl?
-                    Broadcast::Triage::Verdict.new(relevant: false, p: nil, reason: "open in a chi REPL", by: "repl")
+                    Broadcast::Triage::Verdict.new(relevant: false, p: nil, reason: OwnerLock::TUI_BUSY, by: "repl")
                   elsif all
                     Broadcast::Triage::Verdict.new(relevant: true, p: nil, reason: "--all", by: "all")
                   end
@@ -254,7 +254,7 @@ module Samagotchi
 
         result = NoteDelivery.deliver(d.recipient.id, text: body(broadcast.text, d.verdict), source: SOURCE,
                                                       state_dir: @state_dir)
-        next [d, "skipped", "open in a chi REPL"] unless result.delivered?
+        next [d, "skipped", OwnerLock::TUI_BUSY] unless result.delivered?
 
         [d, "delivered", "#{d.verdict.reason}#{"; waits for its next start" if result.status == :waits}"]
       rescue SessionInbox::NoteRejected, SystemCallError => e
@@ -369,7 +369,7 @@ module Samagotchi
 
       result = NoteDelivery.deliver(id, text: passed_on_body(record), source: SOURCE, state_dir: @state_dir)
       unless result.delivered?
-        @stdout.puts(line_for(id, "skipped", "open in a chi REPL"))
+        @stdout.puts(line_for(id, "skipped", OwnerLock::TUI_BUSY))
         return Broadcast::TriageLog::Delivery.new(session: id, result: "refused")
       end
 

data/lib/samagotchi/bundle_command/try/command.rb

@@ -42,7 +42,7 @@ module Samagotchi
           f.switch "--json"
           f.switch "--keep"
           f.value "--timeout"
-          f.refuse "--attach", "--shared", "chi bundle try can't use --attach or --shared"
+          f.refuse "--attach", "chi bundle try can't use --attach"
         end
         DEFAULT_TIMEOUT = 300
         # The sandbox's cost-cap bundle setting (--set cost-cap.cap=N).