samagotchi 0.153.0 → 0.154.0

data/lib/samagotchi/terminal_ui/attached_loop/composer.rb

@@ -12,10 +12,11 @@ module Samagotchi
       # Input composition and Ctrl-C handling for the attached loop.
       # Reads @client, @clock, @command_registry, @continue_offer, @exit_ask,
       # @gaps, @link, @prefilled, @question, @queue, @queued_ids, @reader,
-      # @running, @screen; writes @prefilled, @last_idle_interrupt_at.
+      # @running, @scratch, @screen; writes @prefilled, @last_idle_interrupt_at.
       # Calls the loop helpers #answer_continue, #answer_exit_ask, #answer_question,
       # #archive_after_turn, #command_registry, #detach, #echo_answer, #exit_and_archive,
-      # #exit_and_delete, #exit_worker, #gap_divider, #participant_commands, #persist_recent_history,
+      # #end_scratch, #exit_and_delete, #exit_worker, #refuse_scratch_archive, #gap_divider,
+      # #participant_commands, #persist_recent_history,
       # #queue_input_prefill, #read_prompt_line, #send_command, #send_prompt,
       # #show_recap, #show_stats, #submit_delivery, #unqueue_newest, #via, and
       # #worker_down.
@@ -46,6 +47,7 @@ module Samagotchi
             return answer_exit_ask(line)
           end
 
+          return end_scratch if line.nil? && @scratch
           return detach("Detached; the session keeps running. Re-attach with: #{via.attach(@client.session_id)}") if line.nil?
 
           text = line.strip
@@ -104,11 +106,12 @@ module Samagotchi
           route = ComposerRoute.call(text, running: @running, registry: command_registry)
           return submit_delivery(route) if route.choice
 
-          # The terminal's own commands (SessionCommands registers them, the
-          # REPL reads the same words). Before the continue offer: the
+          # The terminal's own commands (SessionCommands registers them). Before the continue offer: the
           # leaving ones are no answer to it.
           local = route.local
           return submit(nil) if local == :detach
+          return end_scratch if local == :exit && @scratch
+          return refuse_scratch_archive if local == :archive && @scratch
           return SessionCommands.delete_on_exit?(text) ? exit_and_delete : exit_worker if local == :exit
           return archive_after_turn if local == :archive && (@running || !@queued_ids.empty?)
           return exit_and_archive if local == :archive
@@ -130,7 +133,7 @@ module Samagotchi
           elsif %i[share participants].include?(local)
             @screen.commit(participant_commands.run(text))
           elsif route.kind == :command
-            # The history keeps !cmds, as the REPL's does (prompts: #send_prompt).
+            # The history keeps !cmds (prompts: #send_prompt).
             persist_recent_history(text) if PromptHistory.shell_line?(text)
             send_command(text)
           elsif route.kind == :typo
@@ -142,7 +145,7 @@ module Samagotchi
           nil
         end
 
-        # One read on the reader thread: the REPL's multiline read with Tab
+        # One read on the reader thread: a multiline read with Tab
         # completion at the main prompt, a plain line for a question's choice
         # or the continue offer's answer.
         def read_input_line(prompt, prefill)
@@ -169,7 +172,7 @@ module Samagotchi
 
         # The session's commands as its worker's snapshot names them (its
         # plugins' too); the built-ins until one arrives, or from a worker too
-        # old to name them. An unknown /foo is a prompt, as in the REPL.
+        # old to name them. An unknown /foo is a prompt.
         def command_registry = @command_registry || SessionCommands.builtin_registry
 
         # Ctrl-C cancels the running turn (whoever started it). At an idle
@@ -197,13 +200,13 @@ module Samagotchi
           return submit(nil) if @last_idle_interrupt_at && now - @last_idle_interrupt_at <= DETACH_WINDOW
 
           @last_idle_interrupt_at = now
-          @screen.commit(DETACH_HINT)
+          @screen.commit(@scratch ? SCRATCH_DETACH_HINT : DETACH_HINT)
           nil
         end
 
         # On the reader thread, from Reline's Ctrl-C: what the line held, and
         # when. During a turn the press goes to the loop (it cancels the turn)
-        # and the read goes on with the typed text still in it, as in the REPL;
+        # and the read goes on with the typed text still in it;
         # otherwise it is noted for the Interrupt the LineReader queues next.
         # @return [Boolean] true: handled, the read goes on; false: Reline ends
         #   the read with Interrupt

data/lib/samagotchi/terminal_ui/attached_loop/exit_commands.rb

@@ -19,6 +19,22 @@ module Samagotchi
           :detach
         end
 
+        # A scratch session's way out (Ctrl-D, /detach, /exit, a second
+        # Ctrl-C): the loop ends with no line; its AttachLauncher stops the
+        # worker and deletes the session, and says so.
+        # @return [Symbol] :detach
+        def end_scratch
+          @view.finish_thinking_spinner
+          :detach
+        end
+
+        # /archive in a scratch session: nothing to archive (ArchiveRefused's words).
+        # @return [nil]
+        def refuse_scratch_archive
+          @screen.commit(SessionManager::ArchiveRefused.new(@client.session_id, :scratch).message)
+          nil
+        end
+
         # Detach, and ask the worker to exit now. The worker decides: it stays
         # up while anything still needs it (a turn, queued input, a continue
         # offer, another UI, reminders), and the line says which. When the only

data/lib/samagotchi/terminal_ui/attached_loop/questions.rb

@@ -27,8 +27,7 @@ module Samagotchi
           nil
         end
 
-        # A bare answer at the continue prompt, as the REPL reads it (an empty
-        # one is yes).
+        # A bare answer at the continue prompt (an empty one is yes).
         def continue_line(text)
           text.empty? ? SessionCommands::CONTINUE_COMMAND : "#{SessionCommands::CONTINUE_COMMAND} #{text}"
         end
@@ -149,7 +148,7 @@ module Samagotchi
           nil
         end
 
-        # An empty answer dismisses the question, as in the REPL: the tool
+        # An empty answer dismisses the question: the tool
         # returns unanswered (an approval: denied) and the turn goes on. The
         # :question_cancelled every UI gets finds it already closed here.
         def dismiss_question

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -52,7 +52,7 @@ module Samagotchi
     # #handle_event turns the worker's event stream into terminal output:
     # the snapshot a join starts with (the last exchange, queued prompts,
     # the turn so far), prompts other clients sent, and each turn through the
-    # same EventRenderer the local REPL uses, drawn by an AttachedView.
+    # EventRenderer, drawn by an AttachedView.
     class AttachedLoop
       include Formatting
       include InputSupport
@@ -63,9 +63,14 @@ module Samagotchi
       include Sending
 
       PROMPT = "> "
+      # The prompt while a question or a continue offer waits for its answer
+      # (its choices are in the notes slot).
+      QUESTION_PROMPT = "? "
       # A second Ctrl-C at an empty idle prompt within this many seconds detaches.
       DETACH_WINDOW = 2.0
       DETACH_HINT = "Ctrl-D to detach, /exit stops the worker"
+      # A `chi scratch` session's: every way out ends it.
+      SCRATCH_DETACH_HINT = "Ctrl-D or /exit ends the scratch session (nothing is kept)"
       attr_reader :client_id
 
       # @return [String, nil] the model the worker's turns run on, as the
@@ -92,7 +97,7 @@ module Samagotchi
       #   through, the launch stops
       # @param no_interrupt [Boolean] post every turn with no_interrupt
       # @param default_input [Boolean] type SAMAGOTCHI_DEFAULT_INPUT into
-      #   the first read (a new session with no -p, as the REPL)
+      #   the first read (a new session with no -p)
       # @param clock [#call] monotonic seconds (the Ctrl-C detach window)
       # @param now [#call] the wall clock, a Time (the gap dividers)
       # @param delete_session [#call] session id -> deletes it (/exit --delete)
@@ -107,8 +112,11 @@ module Samagotchi
       #   session folder (@path images, saved records) is under it
       # @param link [AttachLink, nil] where the session is, instead of
       #   +client+ and the keywords that make a LocalLink
+      # @param scratch [Boolean] a `chi scratch` session: Ctrl-D, /detach,
+      #   /exit and a second Ctrl-C all end it (its AttachLauncher deletes
+      #   it), /archive is refused, and typed lines stay out of the history
       def initialize(screen:, client_id:, client: nil, first_prompt: nil, first_command: nil, no_interrupt: false,
-                     default_input: false, wait_at_eof: false, as_parent: false,
+                     default_input: false, wait_at_eof: false, as_parent: false, scratch: false,
                      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, now: -> { MessageTime.now },
                      delete_session: ->(id) { SessionManager.delete_session(id, stop: true, wait: LocalLink::DELETE_WAIT) },
                      archive_session: ->(id) { SessionManager.archive_session(id, wait: LocalLink::DELETE_WAIT) },
@@ -119,6 +127,7 @@ module Samagotchi
                                       archive_session: archive_session, installed_version: installed_version,
                                       children_counts: children_counts)
         @client = @link.client
+        @scratch = scratch
         @screen = screen
         @client_id = client_id
         # A parent agent drives this attach (AttachLauncher:
@@ -285,7 +294,7 @@ module Samagotchi
           @gaps.touch
           refresh_children
           own_turn_ended(event)
-        # The renderer says how it ended (the REPL's words too).
+        # The renderer says how it ended (a one-shot's words too).
         when :turn_canceled, :turn_failed
           @status.take_event(event)
           @renderer.call(event)
@@ -413,7 +422,7 @@ module Samagotchi
 
         # Here a stopped session has always read as unreachable.
         reason = "unreachable" if reason == "stopped"
-        "Lost the session's worker (#{reason}). Resume it with: #{via.command("--shared --resume #{id}")}"
+        "Lost the session's worker (#{reason}). Resume it with: #{via.command("--resume #{id}")}"
       end
 
       # Each reason in its own words (the remote's name, its chi web's
@@ -478,7 +487,7 @@ module Samagotchi
       end
 
       # The saved recap, and a new one asked for at once (it arrives as
-      # :recap_ready), with the REPL's words.
+      # :recap_ready), in Formatting's /recap words.
       def show_recap
         reply = @client.request_recap
         answer = reply.status == 200 ? reply.json : nil
@@ -504,11 +513,11 @@ module Samagotchi
       end
 
       # The worker rolled a failed turn back and handed its prompt back: ours
-      # goes back into the input, as the REPL restores it for a retry.
+      # goes back into the input for a retry.
       def restore_prompt(event)
         origin = origin_of(event[:origin])
         return unless own?(origin.client_id) && @own_turns.sent?(origin.enqueued_id)
-        # Lines from a pipe: nobody to retry it (the REPL's rule).
+        # Lines from a pipe: nobody to retry it.
         return if @wait_at_eof
 
         if @reader&.prefill(event[:prompt].to_s)

data/lib/samagotchi/terminal_ui/attached_view.rb

@@ -10,7 +10,7 @@ require_relative "thinking_line"
 
 module Samagotchi
   class TerminalUI
-    # EventRenderer's view in both TUIs (attached mode and the REPL), drawn
+    # EventRenderer's view in the attached TUI, drawn
     # on a Screen: the thinking feedback is the activity slot, one row right
     # above the prompt (spinner frame, then the running tool or the newest
     # sentence of the model's thinking or text, ThinkingLine), and every
@@ -60,8 +60,7 @@ module Samagotchi
         @screen.commit(text)
       end
 
-      # Draw on +surface+ from now on (the REPL swaps in its live region
-      # after the view is built, and back when it ends): what the slot shows
+      # Draw on +surface+ from now on (no caller since the REPL went): what the slot shows
       # moves there.
       def surface=(surface)
         @lock.synchronize do

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -8,9 +8,8 @@ module Samagotchi
     # Renders one UI's view of Engine turn events: the thinking spinner while
     # the model generates, a `tool>` line per completed tool call, and the
     # answer (with any tool activity not already shown) from :turn_completed's
-    # turn_summary, and how a turn ended. It is the `on_event:` sink the REPL
-    # hands Engine#run_turn, and renders what attached mode gets over the
-    # Bridge.
+    # turn_summary, and how a turn ended. It renders what attached mode gets
+    # over the Bridge.
     #
     # Drawing is delegated to a +view+ (an AttachedView in both TUIs). The
     # renderer keeps
@@ -158,8 +157,7 @@ module Samagotchi
       end
 
       # Start a turn's bookkeeping and reset the view's per-turn feedback.
-      # Also called directly by REPL paths that drive the kernel without
-      # Engine#run_turn (so no :turn_started).
+      # Also called from #call on a :turn_started.
       def begin_turn
         @streamed_tool_activity = Hash.new(0)
         @tool_started_at = {}

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -17,14 +17,14 @@ require_relative "model_segments_text"
 
 module Samagotchi
   class TerminalUI
-    # Line formatting shared by the REPL and the attached view: colour, the
+    # Line formatting shared by the attached view and a one-shot: colour, the
     # `tool>` line, elapsed durations. Pure apart from reading whether
     # $stdout is a colour terminal.
     module Formatting
       include ModelSegmentsText
 
-      # The /stats text for a metrics snapshot, for the REPL and attached
-      # views (an instance includes the module) and for `chi sessions stats`
+      # The /stats text for a metrics snapshot, for the attached view (an
+      # instance includes the module) and for `chi sessions stats`
       # (no UI: the same text from the CLI).
       # @return [String] "(no metrics yet)" without a snapshot
       def self.format_session_metrics(snapshot)
@@ -420,7 +420,7 @@ module Samagotchi
         text.strip.empty? ? [] : lines
       end
 
-      # ── Turn ends: one set of words for the REPL, attached mode and the
+      # ── Turn ends: one set of words for a one-shot, attached mode and the
       # web (timing.js cancelLineText, format.js failedTurnText) ──────────
 
       # A cancel's reason as the UIs name it (anything else as it is);
@@ -552,7 +552,7 @@ module Samagotchi
       # Off by the session's own recap.enabled (/recap off, --set recap.enabled=false).
       RECAP_SESSION_OFF_TEXT = "recap is off for this session (/recap on turns it on, /recap default goes back to config.yml)"
 
-      # What /recap says (the REPL's words, attached mode's too): the saved
+      # What /recap says (attached mode's words): the saved
       # recap, then what came of asking for a new one.
       # @param saved [Hash, nil] {text:, turns_since:}
       # @param request [Symbol, String, nil] IdleRecap#request_now's answer
@@ -573,7 +573,7 @@ module Samagotchi
         lines.compact.join("\n")
       end
 
-      # ── The status line (the REPL's, and attached mode's idle one) ────────
+      # ── The status line (attached mode's idle one) ───────────────────────
 
       # status.line: off hides it.
       STATUS_LINE_OFF = "off"
@@ -662,7 +662,7 @@ module Samagotchi
       end
 
       # Render the analytics snapshot as a compact, user-facing report. Raw event
-      # logs (debug-only) are intentionally excluded; this surface is for the REPL
+      # logs (debug-only) are intentionally excluded; this surface is for /stats
       # and `chi sessions stats` (the module function above).
       def format_session_metrics(snapshot)
         return "(no metrics yet)" unless snapshot.is_a?(Hash)

data/lib/samagotchi/terminal_ui/input_support.rb

@@ -14,7 +14,7 @@ require_relative "reline_history_hook"
 
 module Samagotchi
   class TerminalUI
-    # Input the REPL and the attached TUI share: the persistent prompt
+    # The attached TUI's input: the persistent prompt
     # history, Tab completion (/commands, @path in the cwd, #memory, which
     # inserts #name and the model reads it as typed), multiline reads at the
     # main prompt, and a one-shot prefill of the next read (the default
@@ -29,12 +29,6 @@ module Samagotchi
 
       private
 
-      # The /commands Tab offers: the session's registry, the REPL's own
-      # among them.
-      def slash_commands = command_registry.completions(:repl)
-
-      def command_registry = @commands&.registry || SessionCommands.builtin_registry
-
       # Whether a new session's first read gets the default input
       # (SAMAGOTCHI_DEFAULT_INPUT); --no-default-input says no.
       def default_input_wanted? = !@no_default_input

data/lib/samagotchi/terminal_ui/line_reader.rb

@@ -6,8 +6,8 @@ module Samagotchi
   class TerminalUI
     # Reads input lines on its own thread, so output keeps rendering while
     # the user types, and hands each line (nil = Ctrl-D) or Ctrl-C to a sink
-    # (anything with #<<, such as a Thread::Queue); the attached loop and the
-    # REPL both read this way. #reprompt makes it drop the open read and start
+    # (anything with #<<, such as a Thread::Queue); the attached loop reads
+    # this way. #reprompt makes it drop the open read and start
     # again with the current prompt (a question opened or closed); #prefill
     # starts it again with text already typed in (a failed prompt).
     class LineReader

data/lib/samagotchi/terminal_ui/live_region.rb

@@ -7,8 +7,8 @@ require_relative "reline_seam"
 module Samagotchi
   class TerminalUI
     # Opens and closes a live region: a Screen with Reline drawing into it
-    # through RelineSeam. The REPL and attached mode both use one when the
-    # terminal can show it, and fall back to their own plain output otherwise.
+    # through RelineSeam. Attached mode uses one when the terminal can show
+    # it, and falls back to a PlainSurface otherwise.
     module LiveRegion
       module_function
 

data/lib/samagotchi/terminal_ui/log_tail.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "../log"
+require_relative "../log_line"
+require_relative "../degrade"
+
+module Samagotchi
+  class TerminalUI
+    # `chi -v` attached: the debug log's new records of one session (its
+    # sid), followed from where the file ends as it starts, each handed to
+    # +on_record+ (AttachLauncher commits it above the live region). The
+    # worker writes to the file this chi spawned it with
+    # (SAMAGOTCHI_LOG_FILE); a rotation (DebugLog renames the file to .1) is
+    # seen as another inode or a shorter file, and the new one is read from
+    # its start.
+    class LogTail
+      POLL_INTERVAL = 0.2
+
+      # @param path [String] the debug log (Log.path)
+      # @param session_id [String] whose records are shown (its first
+      #   Log::SID_LENGTH chars are the records' sid)
+      # @param on_record [#call] LogLine::Record ->, on the tail's thread
+      def initialize(path:, session_id:, on_record:, poll_interval: POLL_INTERVAL)
+        @path = path
+        @sid = session_id.to_s[0, Log::SID_LENGTH]
+        @on_record = on_record
+        @poll_interval = poll_interval
+        @io = nil
+        @ino = nil
+        @buffer = +""
+        @record = nil
+        @stopping = false
+        @wake = Thread::Queue.new
+      end
+
+      # Start following from the file's current end.
+      # @return [self]
+      def start
+        open_at(:end)
+        @thread = Thread.new { follow }
+        @thread.report_on_exception = false
+        self
+      end
+
+      # How long #stop waits for the record being handed on.
+      STOP_WAIT = 1
+
+      # The records written since the last look are shown first. The tail
+      # ends after the look it is in (a record half committed is finished);
+      # one stuck past STOP_WAIT is killed.
+      def stop
+        if @thread
+          @stopping = true
+          @wake << :stop
+          @thread.kill unless @thread.join(STOP_WAIT)
+          Degrade.call(:attached, "log_tail_failed") { poll }
+        end
+        @io&.close
+        @io = nil
+      end
+
+      # One look: the lines written since the last (tests call it directly).
+      def poll
+        reopen_if_rotated
+        return unless @io
+
+        drain
+        take_lines
+      end
+
+      private
+
+      def follow
+        until @stopping
+          Degrade.call(:attached, "log_tail_failed") { poll }
+          @wake.pop(timeout: @poll_interval)
+        end
+      end
+
+      # What the open file holds past the last read, into the buffer.
+      def drain
+        chunk = @io.read_nonblock(1 << 16, exception: false)
+        while chunk.is_a?(String)
+          @buffer << chunk
+          chunk = @io.read_nonblock(1 << 16, exception: false)
+        end
+      end
+
+      def open_at(where)
+        @io = File.open(@path, "rb")
+        @ino = @io.stat.ino
+        @io.seek(0, IO::SEEK_END) if where == :end
+      rescue SystemCallError
+        @io = nil # not there yet: the next look opens it
+      end
+
+      def reopen_if_rotated
+        return open_at(:start) unless @io
+
+        stat = File.stat(@path)
+        return if stat.ino == @ino && stat.size >= @io.pos
+
+        # Renamed: what the worker wrote to it since the last look is still
+        # there, read before the new file (a truncated one has nothing left).
+        drain if stat.ino != @ino
+        @io.close
+        open_at(:start)
+      rescue SystemCallError
+        nil # renamed and not written again yet
+      end
+
+      # Whole lines only; a payload line joins the record above it. DebugLog
+      # writes a record and its payload in one write, so a look ends on a
+      # whole record: each one is handed on by the end of the look.
+      def take_lines
+        while (cut = @buffer.index("\n"))
+          line = LogLine.clean(@buffer.slice!(0, cut + 1)).chomp
+          if LogLine.payload_line?(line)
+            @record.payload = [@record.payload, line.delete_prefix(LogLine::INDENT)].compact.join("\n") if @record
+            next
+          end
+          flush
+          @record = LogLine.parse(line)
+        end
+        flush
+      end
+
+      def flush
+        record = @record
+        @record = nil
+        @on_record.call(record) if record && record.sid == @sid
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/one_shot_sink.rb

@@ -10,7 +10,7 @@ module Samagotchi
     # stderr. stdout is the answer's alone, printed after the turn: a
     # script or a parent agent reads it.
     #
-    # It prints the retry lines the REPL shows: the loop asking again after
+    # It prints the retry lines the attached terminal shows: the loop asking again after
     # an empty answer (:empty_answer_retry), and a generation retried after
     # a failed request (:generation_retrying). And the hooks' notices
     # (:hook_notice): one during the turn as it comes, one the after_turn
@@ -18,7 +18,7 @@ module Samagotchi
     # #flush, which the caller runs after it has printed the answer. And
     # the load warnings the first turn announces (:guardrail_warning: the
     # guardrails, the plugins, an orphaned project memory folder), as the
-    # REPL's "<label>> …" lines.
+    # attached terminal's "<label>> …" lines.
     class OneShotSink
       include Formatting
 

data/lib/samagotchi/terminal_ui/plain_surface.rb

@@ -12,7 +12,7 @@ module Samagotchi
     # print as lines. The activity slot is dropped, because redrawing it in
     # place needs cursor movement (the turn's lines still print as they end).
     # The prompt is Reline's own, so output may cross it; the editor slot
-    # prints the prompt of a plain read (the REPL's ? off a terminal).
+    # prints the prompt of a plain read (a question's ? off a terminal).
     class PlainSurface
       include Surface
 

data/lib/samagotchi/terminal_ui/question_prompt.rb

@@ -11,8 +11,7 @@ module Samagotchi
     # slot content (#slot), the line it leaves (#summary) and the parsing of
     # a typed answer ("2", "1,3", "1 3; text", option labels). No I/O:
     # callers draw the slot and print the messages, and
-    # record the answer (the REPL on its Engine, an attached UI over the
-    # Bridge). An approval (kind "approval") takes only a number, an exact
+    # record the answer (an attached UI over the Bridge). An approval (kind "approval") takes only a number, an exact
     # label, y (the first option, Allow once) or n (the last, Deny), plus
     # an optional "; reason"; a substring would pick the wrong one ("y" is
     # in "Deny"). The step-limit question (kind "continue") reads the
@@ -86,8 +85,8 @@ module Samagotchi
       end
 
       # The line a question dismissed in a --non-interactive run leaves (no
-      # one could answer it there): the REPL's own, and an attached UI's on
-      # its cancel (QuestionDesk::UNANSWERABLE_REASON).
+      # one could answer it there): the one-shot's own, and an attached UI's
+      # on its cancel (QuestionDesk::UNANSWERABLE_REASON).
       UNANSWERABLE_TEXT = "(dismissed: no one to answer in a non-interactive run)"
 
       # What a question closed with no answer here says: a relayed approval
@@ -220,7 +219,7 @@ module Samagotchi
       end
 
       # The continue words, or an option's number. Empty is Continue (Enter
-      # alone, as at the REPL's continue prompt).
+      # alone).
       def parse_continue(raw)
         text = raw.to_s.strip
         if text.match?(/\A\d+\z/)

data/lib/samagotchi/terminal_ui/reline_seam.rb

@@ -39,13 +39,13 @@ module Samagotchi
         attr_reader :screen
 
         # Asked first on Ctrl-C during a read, with or without a screen: a
-        # truthy answer means it handled the key (the REPL cancelled a running
-        # turn) and the read goes on with the typed text as it is.
+        # truthy answer means it handled the key (the attached loop cancelled a
+        # running turn) and the read goes on with the typed text as it is.
         # @return [#call, nil]
         attr_accessor :interrupt_handler
 
         # Called with no arguments for each key a read takes (typing is
-        # activity for the REPL's idle clock).
+        # activity for an idle clock; nobody sets it now).
         # @return [#call, nil]
         attr_accessor :key_handler
 

data/lib/samagotchi/terminal_ui/status_row.rb

@@ -6,8 +6,8 @@ module Samagotchi
   class TerminalUI
     # The status row under the prompt, the same for both TUIs:
     # `status> Title | model=… | ↳ parent | ⑂ 2 running · 1 waiting | 2 participants | ctx=12.3% (under20) | mem: … | muted: …`.
-    # A UI feeds it what it learns (attached mode from the Bridge's events,
-    # the REPL from its Engine's) through #update, and the row is redrawn in
+    # The attached TUI feeds it what it learns from the Bridge's events
+    # through #update, and the row is redrawn in
     # the surface's status slot only when its text changes.
     class StatusRow
       include Formatting
@@ -54,7 +54,7 @@ module Samagotchi
         @shown = nil
       end
 
-      # The surface it draws on (the REPL swaps in a live region): the row
+      # The surface it draws on (no caller since the REPL went): the row
       # is drawn there at the next change.
       def surface=(surface)
         @surface = surface
@@ -72,8 +72,8 @@ module Samagotchi
         refresh
       end
 
-      # Take a session's state: the REPL's Engine#session_state_snapshot, or
-      # the one a worker sends an attached TUI when it joins. A key the state
+      # Take a session's state: the one a worker sends an attached TUI when
+      # it joins (Engine#session_state_snapshot). A key the state
       # lacks (an older worker's) leaves its field as it was; the served pair
       # is cleared without one, and the model is kept without a name.
       # @param default_model [String, nil] the config's default, named beside
@@ -94,8 +94,7 @@ module Samagotchi
       STATE_LISTS = { used_memories: :used_memory_names, preloaded: :preloaded_memory_names,
                       muted: :muted_memory_names }.freeze
 
-      # Take what a turn event says about the row (the Engine's events in
-      # the REPL, the Bridge's in attached mode): ctx, the memories used,
+      # Take what a turn event says about the row (the Bridge's events): ctx, the memories used,
       # the model the server served, whether a turn runs (the steer
       # hint). Other events change nothing.
       def take_event(event)
@@ -178,7 +177,7 @@ module Samagotchi
       end
 
       # `⑂ 2 running · 1 waiting`, the counts there are; "" with neither (no
-      # children, or all ended). Not "not reported": a REPL parent is never
+      # children, or all ended). Not "not reported": a one-shot parent is never
       # given its children's replies (no wakes there), and a worker moves
       # the cursors only after the turn_completed a terminal refreshes on.
       def children_text(counts)