samagotchi 0.153.0 → 0.154.1

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,16 +60,6 @@ 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
-      # moves there.
-      def surface=(surface)
-        @lock.synchronize do
-          @screen = surface
-          redraw_status if status_text
-        end
-      end
-
       # A new turn: its tally starts over too.
       def reset_turn_feedback
         @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

@@ -5,6 +5,7 @@ require "fileutils"
 require "reline"
 
 require_relative "../config"
+require_relative "../degrade"
 require_relative "../memory_paths"
 require_relative "../prompt_history"
 require_relative "../tools/memory"
@@ -14,7 +15,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 +30,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
@@ -96,20 +91,18 @@ module Samagotchi
         fragment = slash_fragment.to_s.strip
         return [] unless fragment.start_with?("/")
 
-        begin
+        # Only at the line's start: "/x" mid-line is a path, not a command.
+        Degrade.call(:attached, "completion_line_unreadable") do
           buf = Reline.line_buffer.to_s
-          if !buf.empty? && !buf.lstrip.start_with?("/")
-            return []
-          end
-        rescue StandardError
-          nil
+          return [] if !buf.empty? && !buf.lstrip.start_with?("/")
         end
 
         lowered = fragment.downcase
         return slash_commands.dup if lowered == "/"
 
         slash_commands.select { |cmd| cmd.start_with?(lowered) }
-      rescue StandardError
+      rescue StandardError => e
+        Degrade.note(:attached, "slash_completion_failed", e)
         []
       end
 
@@ -140,7 +133,8 @@ module Samagotchi
           relative_path = "#{relative_path}/" if File.directory?(absolute_path)
           "#{AT_PATH_COMPLETION_PREFIX}#{relative_path}"
         end
-      rescue StandardError
+      rescue StandardError => e
+        Degrade.note(:attached, "path_completion_failed", e)
         []
       end
 
@@ -196,7 +190,8 @@ module Samagotchi
             yield scope, name
           end
         end
-      rescue StandardError
+      rescue StandardError => e
+        Degrade.note(:attached, "memory_completion_failed", e)
         []
       end
 
@@ -213,8 +208,8 @@ module Samagotchi
         @history_signature = PromptHistory.signature
         @history_seen = PromptHistory.entries
         @history_seen.last(PromptHistory::LIMIT).each { |entry| Reline::HISTORY << entry }
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Degrade.note(:attached, "history_load_failed", e)
       end
 
       # A scratch session keeps nothing, its typed lines neither.
@@ -229,8 +224,8 @@ module Samagotchi
           history_lock.synchronize { forget_own_line(own) } if own
           raise
         end
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Degrade.note(:attached, "history_append_failed", e)
       end
 
       # Before a main-prompt read, and on the first ↑ of a walk at an open
@@ -261,8 +256,8 @@ module Samagotchi
           @history_signature = signature
           @history_seen = entries
           history_lock.synchronize { add_others_lines(fresh) }
-        rescue StandardError
-          nil
+        rescue StandardError => e
+          Degrade.note(:attached, "history_pickup_failed", e)
         end
       end
 

data/lib/samagotchi/terminal_ui/join_replay.rb

@@ -77,8 +77,11 @@ module Samagotchi
         Log.session_id = @link.client.session_id
         Log.info(:attached, "joined", session: @link.client.session_id, messages: exchange.size,
                                       notes: messages.count { |m| ContextNote.note?(m) })
-        last_user = exchange.rindex { |m| Steer.prompt?(m) }
-        render_join_notes(messages)
+        # The last turn's own prompt (Steer.turn_prompt?, as the page's
+        # turns): not Qwen's recovery line, nor input merged into the turn.
+        last_user = exchange.rindex { |m| Steer.turn_prompt?(m) }
+        from = last_user && messages.index { |m| m.equal?(exchange[last_user]) }
+        render_join_notes(messages, from)
         return unless last_user
 
         @screen.commit(join_prompt_line(exchange[last_user]))
@@ -86,7 +89,6 @@ module Samagotchi
         unless ImageRef.placeholder_only?(exchange[last_user][:content])
           Array(exchange[last_user][:images]).each { |ref| @screen.commit(format_image_line(ref)) }
         end
-        from = messages.index { |m| m.equal?(exchange[last_user]) }
         render_join_steps(messages, from, durations: join_tool_records(exchange[last_user]))
         record = @link.saved_turn_record(exchange[last_user][:turn_id] || exchange[last_user]["turn_id"])
         failed = join_failed_record(record)
@@ -114,19 +116,21 @@ module Samagotchi
                                              .find { |text| !text.empty? }
           @screen.commit(last_lines(answer)) if answer
         end
-        render_join_notes(messages, after_exchange: true)
+        render_join_notes(messages, from, after_exchange: true)
       end
 
       # What the last exchange did, as the live turn drew it: each saved
       # call's tool row (action, params, status from its result, and its
       # duration from +durations+, the turn's saved tool records) and a
-      # plugin's steer where it came. The step texts stay out, as live (the
-      # ticker's).
+      # plugin's steer and the user's input merged into the turn where they
+      # came. The step texts stay out, as live (the ticker's).
       def render_join_steps(messages, from, durations: [])
         records = durations.dup
         messages.each_with_index.drop(from + 1).each do |m, i|
           if Steer.steer?(m)
             @screen.commit(format_steer_line(source: m[:source], text: m[:content]))
+          elsif Steer.input?(m) && !Steer.turn_prompt?(m)
+            @screen.commit("input> #{m[:content]}")
           elsif %w[model assistant].include?(m[:role].to_s)
             responses = messages.drop(i + 1).take_while { |r| r[:role].to_s == "tool_response" }
             Array(MessageParts.for_message(m, responses)&.dig(:tools)).each do |part|
@@ -209,13 +213,13 @@ module Samagotchi
         format_tool_guardrail_suffix({ decided_by: "system one", p: saved["p"] || saved[:p] })
       end
 
-      # The context notes that came since the last prompt (all of them in a
-      # session with none), after the exchange the header shows.
-      def render_join_notes(messages, after_exchange: false)
-        last_user = messages.rindex { |m| Steer.prompt?(m) }
-        return if after_exchange != !last_user.nil?
+      # The context notes that came since the last prompt (+from+, its index
+      # in +messages+; all of them in a session with none), after the
+      # exchange the header shows.
+      def render_join_notes(messages, from, after_exchange: false)
+        return if after_exchange != !from.nil?
 
-        messages[(last_user ? last_user + 1 : 0)..].select { |m| ContextNote.note?(m) }.each do |m|
+        messages[(from ? from + 1 : 0)..].select { |m| ContextNote.note?(m) }.each do |m|
           @screen.commit(context_note_line(ContextNote.label_of(m), ContextNote.text_of(m)))
         end
       end

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