samagotchi 0.152.0 → 0.154.0

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -13,14 +13,19 @@ require_relative "../launch_mode"
 require_relative "live_region"
 require_relative "plain_surface"
 require_relative "attached_loop"
+require_relative "log_tail"
+require_relative "formatting"
 
 module Samagotchi
   class TerminalUI
-    # `chi --attach ID` and `chi --shared [--resume ID]`: find or start the
+    # `chi`, `chi --attach ID` and `chi --resume ID`: find or start the
     # session's worker, then run the TUI as a client of its Bridge
     # (AttachedLoop). It takes no OwnerLock and builds no Engine: the worker
     # owns the session, and any number of UIs can attach to it.
     module AttachLauncher
+      # #paint, for the -v records.
+      extend Formatting
+
       # Why attaching failed, worded for the terminal.
       class Error < StandardError; end
 
@@ -28,6 +33,13 @@ module Samagotchi
       # A connector that answered no session (its own failures raise Error
       # with their words).
       NOTHING_CONNECTED = "could not attach: no session was found or started"
+      # `chi scratch`'s first line, and its last once the session is gone.
+      SCRATCH_BANNER = "Scratch session: nothing is kept, it is deleted when you leave."
+      SCRATCH_DELETED = "Scratch session deleted."
+      # chi -v on a worker that was running before this launch (%s: the
+      # debug log): its level is its own.
+      VERBOSE_RUNNING = "(--verbose: this worker was already running and logs at the level it started with; " \
+                        "its records show here only if it writes to %s: one chi web started may log elsewhere)"
 
       module_function
 
@@ -62,6 +74,13 @@ module Samagotchi
       #   own guardrails.parent_answers; an existing session keeps its own
       #   (never sent as a /parent-answers command: that would be a
       #   loosening route from a command line)
+      # @param scratch [Boolean] `chi scratch`: a new scratch session (its
+      #   worker's Engine saves nothing), stopped and deleted however the
+      #   attach ends; its worker deletes it too once no client is left
+      # @param verbose [Boolean] -v: the session's debug records in the
+      #   debug log (Log.path), shown above the live region as they come
+      #   (LogTail); a worker this launch spawns logs at debug (bin/chi's
+      #   log.level override reaches it through Config.cli_env)
       # @param state_dir [String, nil] where the sessions are (the default
       #   state dir by default): the worker's, for the attached loop too
       # @param connector [#connect, nil] finds or starts the session
@@ -73,19 +92,23 @@ module Samagotchi
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :removed / :unanswered
       #   (AttachedLoop#run)
-      def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
+      def run(attach: nil, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
               memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
-              toolkit_flags: [], settings: nil, parent_answers: nil, state_dir: nil, connector: nil)
+              toolkit_flags: [], settings: nil, parent_answers: nil, scratch: false, verbose: false, state_dir: nil,
+              connector: nil)
         state_dir ||= Session.default_state_dir
+        running_before = verbose && !connector && worker_running?(attach || resume, state_dir)
         link = connector && (connector.connect || raise(Error, NOTHING_CONNECTED))
         client = if connector
                    link.client
                  else
-                   connect(attach: attach, shared: shared, resume: resume, model: model, state_dir: state_dir,
+                   connect(attach: attach, resume: resume, model: model, state_dir: state_dir,
                            memories: memories, muted_memories: muted_memories, llm_context: llm_context,
                            thinking: thinking, appended_prompt_files: appended_prompt_files, toolkit: toolkit,
-                           toolkit_flags: toolkit_flags, settings: settings, parent_answers: parent_answers)
+                           toolkit_flags: toolkit_flags, settings: settings, parent_answers: parent_answers,
+                           scratch: scratch)
                  end
+        $stdout.puts(SCRATCH_BANNER) if scratch
         commands = []
         # --yes on /model and /thinking: typing the flag is the choice (no
         # confirm step); its applied reply ends the launch's command.
@@ -93,11 +116,13 @@ module Samagotchi
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
         commands << "#{ThinkingCommand::NAME} #{thinking} --yes" if (attach || resume) && thinking
         first_command = commands.size > 1 ? commands : commands.first
+        $stderr.puts(format(VERBOSE_RUNNING, Log.path)) if running_before
         surface = open_surface
+        tail = (start_log_tail(surface, client.session_id) if verbose && Log.path)
         options = { screen: surface, client_id: client_id(connector), first_prompt: prompt,
                     first_command: first_command, no_interrupt: no_interrupt,
                     default_input: default_input && !prompt && !attach && !resume,
-                    wait_at_eof: !$stdin.tty?,
+                    wait_at_eof: !$stdin.tty?, scratch: scratch,
                     as_parent: Guardrails::ParentApprovals.parent_process? }
         attached = if connector
                      AttachedLoop.new(link: link, **options)
@@ -107,6 +132,7 @@ module Samagotchi
         ended = begin
           attached.run
         ensure
+          tail&.stop
           close_surface(surface)
         end
         if ended == :unanswered && attached.unanswered
@@ -119,6 +145,34 @@ module Samagotchi
         ended
       ensure
         link&.close
+        # Every way out (Ctrl-D, /exit, the worker gone, an error, Ctrl-C or
+        # a signal): only kill -9 leaves it to its worker (and the sweep).
+        end_scratch(client.session_id, state_dir: state_dir, quiet: !$!.nil?) if scratch && client
+      end
+
+      # Whether +session_id+'s worker runs now (nil: a new session).
+      def worker_running?(session_id, state_dir)
+        return false unless session_id && Session.valid_id?(session_id)
+
+        WorkerLink.resolve(Session.session_dir(session_id, state_dir: state_dir), unlink: false).live?
+      end
+
+      # The session's debug records, dim, above the live region.
+      def start_log_tail(surface, session_id)
+        LogTail.new(path: Log.path, session_id: session_id, on_record: lambda { |record|
+          surface.commit(paint(LogLine.format(record).chomp, 2))
+        }).start
+      end
+
+      # Stop the scratch session's worker and delete the session; its worker
+      # may have deleted it first (it found no client left).
+      def end_scratch(session_id, state_dir:, quiet: false, out: $stdout, err: $stderr)
+        SessionManager.delete_session(session_id, state_dir: state_dir, stop: true, wait: LocalLink::DELETE_WAIT)
+        out.puts(SCRATCH_DELETED) unless quiet
+      rescue ArgumentError
+        out.puts(SCRATCH_DELETED) unless quiet
+      rescue SessionManager::DeleteRefused, SystemCallError => e
+        err.puts("Scratch session #{session_id} was not deleted (#{e.message}): chi sessions delete #{session_id}")
       end
 
       # This TUI's client id: tui:PID, or the connector's own (a remote one
@@ -185,10 +239,11 @@ module Samagotchi
 
       # @return [BridgeClient] a client for the live Bridge of the session
       # @raise [Error]
-      def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
+      def connect(attach: nil, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
                   memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
-                  toolkit_flags: [], settings: nil, parent_answers: nil, err: $stderr)
+                  toolkit_flags: [], settings: nil, parent_answers: nil, scratch: false, err: $stderr)
         sd = state_dir || Session.default_state_dir
+        connected = false
         if attach || resume
           warn_memory_flags_ignored(attach || resume, memories, muted_memories, err, appended_prompt_files: appended_prompt_files,
                                                                                      toolkit_flags: toolkit_flags)
@@ -211,14 +266,21 @@ module Samagotchi
                                                                          thinking: Thinking.session_level(thinking),
                                                                          appended_prompt_files: appended_prompt_files,
                                                                          toolkit: toolkit, settings: settings,
-                                                                         parent_answers: parent_answers))
+                                                                         parent_answers: parent_answers),
+                                                 scratch: scratch)
                   end
         link = WorkerLink.await(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
-        link.live? ? link.client(session.id) : raise(Error, format(LaunchMode::BRIDGE_LATE, session.id))
+        raise(Error, format(LaunchMode::BRIDGE_LATE, session.id)) unless link.live?
+
+        connected = true
+        link.client(session.id)
       rescue SessionManager::OwnedByTUI => e
         raise Error, e.message
       rescue ArgumentError => e
         raise Error, e.message
+      ensure
+        # A scratch session whose Bridge never came (or Ctrl-C meanwhile).
+        end_scratch(session.id, state_dir: sd, quiet: true, err: err) if scratch && session && !connected
       end
 
       # The session's previous worker may still be leaving: its Bridge

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