samagotchi 0.20.0 → 0.22.0

data/lib/samagotchi/llm/prompt_cache.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module LLM
+    # Prompt-cache breakpoints for Claude models behind an OpenAI-compatible
+    # host (OpenRouter, a gateway). Anthropic caches a prompt only up to a
+    # content part marked with cache_control, in the order tools → system →
+    # messages, so two marks cover a chat request:
+    # - the first system message (with it, the tool list), and
+    # - the last non-system message with content, so the next request (the
+    #   same prefix plus new messages) reads everything up to it.
+    # Mid and tail system messages (reminders, turn notes) never take the
+    # second mark. Other models' messages pass through untouched.
+    module PromptCache
+      CONTROL = { type: "ephemeral" }.freeze
+
+      module_function
+
+      # Whether +model+ (the bare id a host is asked for) names a Claude model.
+      def claude?(model) = model.to_s.match?(/claude/i)
+
+      # +messages+ (wire messages: symbol keys, content a String or an Array
+      # of parts) with the breakpoints set when +model+ is a Claude model;
+      # the given messages as they are otherwise. The marked messages and
+      # parts are copies: the caller's are never changed.
+      # @return [Array<Hash>]
+      def mark(messages, model:)
+        return messages unless claude?(model)
+
+        indexes = [system_index(messages), last_index(messages)].compact.uniq
+        return messages if indexes.empty?
+
+        messages.each_with_index.map { |message, index| indexes.include?(index) ? marked(message) : message }
+      end
+
+      # Whether any message in +messages+ carries a breakpoint.
+      def marked?(messages)
+        Array(messages).any? do |message|
+          content = message[:content]
+          content.is_a?(Array) && content.any? { |part| part.is_a?(Hash) && control?(part) }
+        end
+      end
+
+      def system_index(messages)
+        index = messages.index { |message| message[:role].to_s == "system" }
+        index if index && content?(messages[index][:content])
+      end
+
+      # The last message that isn't a system message and has content (an
+      # assistant tool_calls message has nil or "").
+      def last_index(messages)
+        messages.rindex { |message| message[:role].to_s != "system" && content?(message[:content]) }
+      end
+
+      def content?(content)
+        case content
+        when String then !content.empty?
+        when Array then content.any? { |part| part.is_a?(Hash) }
+        else false
+        end
+      end
+
+      # A String becomes one text part; an Array gets the mark on its last
+      # text part (the last part when none is text).
+      def marked(message)
+        content = message[:content]
+        return message.merge(content: [{ type: "text", text: content, cache_control: CONTROL }]) if content.is_a?(String)
+
+        target = content.rindex { |part| part.is_a?(Hash) && (part[:type] || part["type"]).to_s == "text" } ||
+                 content.rindex { |part| part.is_a?(Hash) }
+        part = content[target]
+        key = part.key?("type") ? "cache_control" : :cache_control
+        parts = content.dup
+        parts[target] = part.merge(key => CONTROL)
+        message.merge(content: parts)
+      end
+
+      def control?(part) = part.key?(:cache_control) || part.key?("cache_control")
+
+      private_class_method :system_index, :last_index, :content?, :marked, :control?
+    end
+  end
+end

data/lib/samagotchi/log_subscriber.rb

@@ -82,7 +82,8 @@ module Samagotchi
     end
 
     def on_turn_canceled(event)
-      log(:info, :turn_canceled, ms: since(@turn_started_at), reason: event[:cancellation_reason], **origin(event))
+      log(:info, :turn_canceled, ms: since(@turn_started_at), reason: event[:cancellation_reason], by: event[:cancelled_by],
+                                 **origin(event))
     end
 
     def on_turn_failed(event)
@@ -100,7 +101,8 @@ module Samagotchi
     def on_generation_completed(event)
       ms = since(@generation_started_at.delete(event[:iteration]))
       log(:info, :generation_completed, iteration: event[:iteration], ms: ms,
-                                        served_model: event[:served_model], requested_model: event[:requested_model],
+                                        served_model: event[:served_model], provider: event[:served_provider],
+                                        requested_model: event[:requested_model],
                                         content_length: event[:content_length],
                                         thinking_chars: event[:thinking_chars], finish_reason: event[:finish_reason],
                                         stopped_by: event[:stopped_by])

data/lib/samagotchi/parent_report.rb

@@ -70,8 +70,10 @@ module Samagotchi
 
     # @param session_id [String]
     # @param timeout [Numeric, nil] the wait's --timeout (for the running detail)
+    # @param extra [Hash] more keys for the object (chi answer's
+    #   answered_here: false)
     # @return [Hash] the --format json object
-    def json(result, session_id:, timeout: nil)
+    def json(result, session_id:, timeout: nil, extra: {})
       report = { status: status(result), session_id: session_id }
       case report[:status]
       when "answered" then report[:text] = result.text.to_s
@@ -79,24 +81,39 @@ module Samagotchi
         question = question(result.question)
         report[:question] = question
         report[:answer_with] = answer_with(session_id, question)
-      else report[:detail] = detail(result, session_id: session_id, timeout: timeout)
+      else
+        report.merge!(stop_facts(result))
+        report[:detail] = detail(result, session_id: session_id, timeout: timeout)
+      end
+      report.merge(extra)
+    end
+
+    # Why a failed or canceled turn stopped, as far as last_turn knows
+    # (ReplyWait::Result): error_kind and retryable, cancel_reason and
+    # stopped_by; absent when unknown.
+    # @return [Hash]
+    def stop_facts(result)
+      case status(result)
+      when "failed" then { error_kind: result.error_kind, retryable: result.retryable }.compact
+      when "canceled" then { cancel_reason: result.cancel_reason, stopped_by: result.stopped_by }.compact
+      else {}
       end
-      report
     end
 
     # @return [String] the JSON object as one line
-    def json_line(result, session_id:, timeout: nil)
-      JSON.generate(json(result, session_id: session_id, timeout: timeout))
+    def json_line(result, session_id:, timeout: nil, extra: {})
+      JSON.generate(json(result, session_id: session_id, timeout: timeout, extra: extra))
     end
 
     # Print a wait's end the way the commands do: the JSON object on
     # stdout, or the reply on stdout and anything else on stderr (a
     # question in full) after "chi send: ".
     # @param command [String] "chi send", "chi answer"
+    # @param extra [Hash] more keys for the JSON object (#json)
     # @return [Integer] the exit status
-    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil)
+    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil, extra: {})
       if json
-        stdout.puts(json_line(result, session_id: session_id, timeout: timeout))
+        stdout.puts(json_line(result, session_id: session_id, timeout: timeout, extra: extra))
       elsif result.status == :done
         stdout.puts(result.text)
       else

data/lib/samagotchi/question_desk.rb

@@ -455,7 +455,7 @@ module Samagotchi
     def settle_standing(standing, answer, client_id)
       clear_saved_question
       emit({ type: :question_answered, id: answer[:id], answer: answer })
-      standing[:on_answer].call(answer.except(:by), client_id: client_id)
+      standing[:on_answer].call(answer, client_id: client_id)
     rescue StandardError => e
       Log.warn(:turn, "standing_answer_failed", error: e.class.name, message: e.message)
     end
@@ -472,12 +472,6 @@ module Samagotchi
       raise ArgumentError, "invalid selection: #{invalid.join(', ')} (valid: #{opts.join(', ')})" unless invalid.empty?
       raise ArgumentError, "single-select question: got #{sel.size} selections" if !pending[:multi_select] && sel.size > 1
       raise ArgumentError, "selection required" if pending[:multi_select] == false && sel.empty? && fm.nil?
-      # A step-limit question: Continue resumes the turn as it was; a text
-      # goes with Stop (steering a continue is not a thing).
-      if pending[:kind].to_s == CONTINUE_KIND && sel == [CONTINUE_OPTION] && fm
-        raise ArgumentError, "Continue takes no text (a text goes with Stop)"
-      end
-
       indices = sel.map { |v| opts.index(v) }
       # The one whose answer settles the approval (Approval.settle, by index).
       if parent_setting

data/lib/samagotchi/reply_wait.rb

@@ -33,7 +33,16 @@ module Samagotchi
     #   "failed", text is the failure's summary when the turn note has one.
     # @!attribute limit [Integer, nil] the iteration limit an "exhausted"
     #   turn ran out at
-    Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, keyword_init: true)
+    # @!attribute error_kind [String, nil] a "failed" turn's provider error
+    #   kind (credits, server, auth, …), from last_turn
+    # @!attribute retryable [Boolean, nil] whether that error may pass on a
+    #   retry
+    # @!attribute cancel_reason [String, nil] a "canceled" turn's reason
+    #   (user, hook, ctrl_c, manual)
+    # @!attribute stopped_by [String, nil] the hook that canceled it
+    #   (loop-guard)
+    Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, :error_kind, :retryable, :cancel_reason,
+                        :stopped_by, keyword_init: true)
 
     module_function
 
@@ -151,7 +160,8 @@ module Samagotchi
       return Result.new(status: :no_reply, outcome: "exhausted", limit: last["limit"]) if fresh && last["exhausted"]
 
       text = outcome == "failed" ? failure_summary(session.messages) : nil
-      Result.new(status: :no_reply, outcome: outcome, text: text)
+      why = fresh ? last.slice("error_kind", "retryable", "cancel_reason", "stopped_by").transform_keys(&:to_sym) : {}
+      Result.new(status: :no_reply, outcome: outcome, text: text, **why)
     end
 
     # The summary in the failed-turn note at the conversation's tail, nil

data/lib/samagotchi/session_manager.rb

@@ -24,6 +24,7 @@ require_relative "installed_gem"
 require_relative "installed_versions"
 require_relative "recap_store"
 require_relative "archive_store"
+require_relative "continue_offer"
 require_relative "image_store"
 require_relative "plugin_session_state"
 require_relative "terminal_ui"
@@ -105,6 +106,10 @@ module Samagotchi
         case @reason
         when :scratch then "a scratch session is deleted when you leave; nothing to archive"
         when :busy_child then "its delegate #{@busy_id[0, 8]} is running a turn; wait for it or stop it first"
+        when :queued then "a prompt is queued, which a resume would run; let it run first"
+        when :queued_child then "its delegate #{@busy_id[0, 8]} has a prompt queued, which a resume would run; let it run first"
+        when :offer then "the step-limit question waits for an answer; answer Continue or Stop first"
+        when :offer_child then "its delegate #{@busy_id[0, 8]} waits for an answer to its step-limit question; answer it first"
         else "a turn is running; wait for it or cancel it first"
         end
       end
@@ -309,8 +314,9 @@ module Samagotchi
     #   discarded: empty sessions their stopping worker deleted
     # @raise [ArgumentError] unknown id (Session::AmbiguousId for a prefix of several)
     # @raise [OwnedByTUI] a chi REPL owns it or one of its children
-    # @raise [ArchiveRefused] a turn runs in it or in a child, or it is a
-    #   scratch session
+    # @raise [ArchiveRefused] a turn runs in it or in a child, a prompt is
+    #   queued in one (a later resume would run it), a live one offers to
+    #   continue past the step limit, or it is a scratch session
     def self.archive_session(id_or_prefix, state_dir: nil, wait: 5)
       sd = state_dir || Session.default_state_dir
       id = archive_target(id_or_prefix, sd)
@@ -319,13 +325,8 @@ module Samagotchi
       tree = [id, *descendant_ids(id, sd)]
       owners = tree.to_h { |sid| [sid, session_owner(sid, state_dir: sd)] }
       tree.each do |sid|
-        owner = owners[sid]
-        next unless owner
-
-        raise OwnedByTUI, sid if owner.tui?
-        next unless Session.load(sid, state_dir: sd).status == Session::STATUS_RUNNING
-
-        raise ArchiveRefused.new(id, sid == id ? :busy : :busy_child, busy_id: sid)
+        refusal = archive_refusal(sid, owners[sid], sd)
+        raise ArchiveRefused.new(id, sid == id ? refusal : :"#{refusal}_child", busy_id: sid) if refusal
       end
 
       stopped = tree.select { |sid| owners[sid] }
@@ -334,6 +335,22 @@ module Samagotchi
       { id: id, archived: archived, stopped: stopped, discarded: discarded }
     end
 
+    # What keeps +sid+ (in an archive's tree) from being archived: :busy (a
+    # turn runs), :queued (input/ holds a prompt, which outlives the stop and
+    # runs on a resume, live worker or not), :offer (a live worker's continue
+    # offer, which the stop would drop), or nil.
+    # @raise [OwnedByTUI] a chi REPL owns it
+    def self.archive_refusal(sid, owner, state_dir)
+      raise OwnedByTUI, sid if owner&.tui?
+
+      session = owner && Session.load(sid, state_dir: state_dir)
+      return :busy if session&.status == Session::STATUS_RUNNING
+      return :queued unless SessionInbox.find_new_input_files(Session.session_dir(sid, state_dir: state_dir)).empty?
+
+      :offer if session&.waiting_question(live: true)&.dig(:kind) == ContinueOffer::KIND
+    end
+    private_class_method :archive_refusal
+
     # Unarchive a session and its delegated children.
     # @return [Hash] {id:, unarchived: [ids that were archived]}
     # @raise [ArgumentError] unknown id

data/lib/samagotchi/session_metrics.rb

@@ -277,7 +277,7 @@ module Samagotchi
       when :turn_completed
         end_turn(status: "completed")
       when :turn_canceled
-        end_turn(status: "canceled", reason: event[:cancellation_reason])
+        end_turn(status: "canceled", reason: event[:cancellation_reason], by: event[:cancelled_by])
       when :turn_failed
         end_turn(status: "failed")
       end
@@ -457,9 +457,10 @@ module Samagotchi
       end
     end
 
-    # A canceled turn's record keeps why (+reason+: "user", "ctrl_c", ...), so
-    # a reloaded web history can show the cancel line the live one did.
-    def end_turn(status: "completed", reason: nil)
+    # A canceled turn's record keeps why (+reason+: "user", "ctrl_c", ...)
+    # and who stopped it (+by+: a hook's bundle), so a reloaded web history
+    # can show the cancel line the live one did.
+    def end_turn(status: "completed", reason: nil, by: nil)
       @mutex.synchronize do
         if @turn
           # A turn that failed mid-stream never saw its generation end:
@@ -478,6 +479,7 @@ module Samagotchi
             duration_ms: elapsed_ms(@turn.started_monotonic)
           }
           record[:cancellation_reason] = reason.to_s unless reason.nil? || reason.to_s.empty?
+          record[:cancelled_by] = by.to_s unless by.nil? || by.to_s.empty?
           record.merge!(turn_token_fields(@turn))
           @turn_records << record
           count_turn(record)

data/lib/samagotchi/steer.rb

@@ -80,7 +80,7 @@ module Samagotchi
     # :pending_input_merged. After a cancel the input stays queued: it runs
     # as the next turn instead of dying with this one. +answer+ (a String,
     # or a Proc called only on a merge) is the answer the merge follows, for
-    # the UIs; given, the drain is told it is the after-answer site (plugin
+    # the TUI's line (the web has it as the step's streamed text); given, the drain is told it is the after-answer site (plugin
     # steers are dropped there). A blank answer is none.
     # @return [Boolean] whether anything was injected
     def inject!(conversation, pending_input, iteration:, emit:, cancel_controller:, answer: nil)

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -47,6 +47,10 @@ module Samagotchi
       DETACH_HINT = "Ctrl-D to detach, /exit stops the worker"
       # Why a request the Bridge read after its deadline didn't go through.
       LATE = "worker not answering in time"
+      # An exit the worker agreed to in an empty session. Said before it has
+      # left: it checks again once it lets go, and a note or prompt arriving
+      # first keeps the session (SessionManager.discard_left_session).
+      EMPTY_EXIT = "Detached; the session is empty: it will be discarded if nothing arrives before its worker stops."
       # Why the worker stayed up after /exit, by the reason it gave.
       HELD_REASONS = {
         "turn_running" => "a turn is running", "input_queued" => "prompts are queued",
@@ -420,7 +424,9 @@ module Samagotchi
           return detach("#{line} Not deleted.")
         end
         # An empty session: the worker deletes it as it leaves.
-        @delete_session.call(id) unless discards?(reply)
+        return detach(EMPTY_EXIT) if discards?(reply)
+
+        @delete_session.call(id)
         detach("Detached; deleted session #{id}.")
       rescue SystemCallError, IOError => e
         detach("#{exit_failed_line(e.message)} Not deleted.")
@@ -429,14 +435,15 @@ module Samagotchi
       end
 
       # /archive: the worker is asked to exit as for /exit, then the session
-      # is archived. A worker staying up for another UI (or reminders, a
-      # queued prompt) is stopped by the archive, as the web's archive
-      # stops it; a turn running refuses it. An empty session: the worker
+      # is archived. A worker staying up for another UI (or reminders) is
+      # stopped by the archive, as the web's archive stops it; a turn
+      # running, a queued prompt or an open continue offer refuses it
+      # (SessionManager.archive_session). An empty session: the worker
       # deletes it as it leaves.
       def exit_and_archive
         reply = @client.request_exit(client_id: @client_id)
         id = @client.session_id
-        return detach("Detached; the session was empty, so it is discarded.") if reply.status == 200 && discards?(reply)
+        return detach(EMPTY_EXIT) if reply.status == 200 && discards?(reply)
         return detach("#{exit_line(reply)} Not archived.") unless [200, 409].include?(reply.status)
 
         result = @archive_session.call(id)
@@ -454,15 +461,14 @@ module Samagotchi
         error = reply.json&.fetch("error", nil)
         case reply.status
         when 200
-          # Said as the worker agreed to leave; a note coming in before it
-          # does keeps the session after all (rare, left as is).
-          return "Detached; the session was empty, so it is discarded." if discards?(reply)
+          return EMPTY_EXIT if discards?(reply)
 
           "Detached; the session's worker is stopping. Resume with: chi --resume #{id}"
         when 409
           reason = reply.json&.fetch("reason", nil).to_s
           "Detached; the session keeps running (#{HELD_REASONS.fetch(reason, reason)}). Re-attach with: chi --attach #{id}"
         when 0 then exit_failed_line("no reply")
+        when 408 then exit_failed_line(LATE)
         else
           # A worker from before the route answers the Bridge's plain 404.
           return "Detached; this worker runs an older chi and can't be stopped from here: chi sessions stop #{id}" if error == "not_found"
@@ -1029,7 +1035,8 @@ module Samagotchi
         exchange = messages.select { |m| %w[user model assistant].include?(m[:role].to_s) }
         # The id stays findable: the detach line and chi sessions list show it.
         Log.session_id = @client.session_id
-        Log.info(:attached, "joined", session: @client.session_id, messages: exchange.size)
+        Log.info(:attached, "joined", session: @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)
         return unless last_user
@@ -1166,6 +1173,8 @@ module Samagotchi
         running_tool = nil
         Bridge::TurnAccumulator.replay_events(turn).each do |event|
           case event[:type]
+          # A new step starts its line over, as live (a join during a hold).
+          when :generation_started then tail, lane = nil, :writing
           when :generation_chunk
             tail, lane = event[:thinking].to_s.empty? ? [event[:text], :writing] : [event[:thinking], :thinking]
           when :tool_call_started

data/lib/samagotchi/terminal_ui/event_renderer.rb

@@ -84,7 +84,7 @@ module Samagotchi
           render_turn_summary(event[:turn_summary]) if event[:turn_summary]
         when :turn_canceled
           @view.finish_thinking_spinner
-          @view.print_line(@view.turn_canceled_line(event[:cancellation_reason], event[:duration_ms]))
+          @view.print_line(@view.turn_canceled_line(event[:cancellation_reason], event[:duration_ms], by: event[:cancelled_by]))
           @view.print_line(@view.turn_end_hint(Formatting::ROLLBACK_HINT)) unless @turn_continues
         when :turn_failed
           # A provider error's one-line summary, else the message (an image

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -203,8 +203,13 @@ module Samagotchi
       # started): its partial progress stays in the conversation.
       ROLLBACK_HINT = "partial progress kept; !rollback restores the pre-turn state"
 
-      # "✕ turn canceled (Ctrl-C) · 3.1s"
-      def turn_canceled_line(reason, duration_ms)
+      # "✕ turn canceled (Ctrl-C) · 3.1s"; a hook's stop that names who
+      # (+by+, turn_canceled's cancelled_by): "✕ turn stopped by loop-guard"
+      def turn_canceled_line(reason, duration_ms, by: nil)
+        if reason.to_s == "hook" && !by.to_s.empty?
+          return "#{paint("✕", 33)} turn stopped by #{by}#{turn_duration_suffix(duration_ms)}"
+        end
+
         label = reason.to_s.empty? ? nil : CANCEL_REASONS.fetch(reason.to_s, reason.to_s)
         "#{paint("✕", 33)} turn canceled#{" (#{label})" if label}#{turn_duration_suffix(duration_ms)}"
       end

data/lib/samagotchi/terminal_ui/live_region.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "io/console"
 require_relative "screen"
 require_relative "reline_seam"
 
@@ -22,10 +23,48 @@ module Samagotchi
         screen
       end
 
-      # Hand Reline its own drawing back, then close the surface.
-      def close(surface)
+      # How long #drain_input waits for input still on its way.
+      DRAIN_WINDOW = 0.05
+      # How long Reline waits for the reply to its cursor query (Reline::ANSI#cursor_pos).
+      CURSOR_REPLY_WAIT = 0.5
+      CURSOR_REPLY = /\e\[\d+;\d+R/
+
+      # Hand Reline its own drawing back, close the surface, then drop the
+      # input nobody read (#drain_input).
+      def close(surface, input: $stdin)
         RelineSeam.detach(surface)
         surface.close
+        query_at = RelineSeam.unanswered_query_at
+        RelineSeam.unanswered_query_at = nil
+        drain_input(input, query_at: query_at) if surface.is_a?(Screen)
+      end
+
+      # Reline asks the terminal for the cursor row (ESC[6n) as each read
+      # starts; the reply to one cut short at exit, read by nobody, would
+      # land at the shell's prompt. What came, or comes within DRAIN_WINDOW,
+      # is read and dropped (keys typed in that moment too), in raw mode, so
+      # a reply with no newline is readable. With a query left unanswered
+      # (RelineSeam.unanswered_query_at), until its reply, up to as long as
+      # Reline would have waited for it.
+      def drain_input(input, query_at: nil)
+        return unless input.is_a?(IO) && input.tty?
+
+        now = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        deadline = now.call + DRAIN_WINDOW
+        deadline = [deadline, query_at + CURSOR_REPLY_WAIT].max if query_at
+        dropped = +""
+        input.raw do
+          while (left = deadline - now.call).positive? && input.wait_readable(left)
+            read = input.read_nonblock(1024, exception: false)
+            break if read.nil?
+
+            dropped << read if read.is_a?(String)
+            # The reply came: no need to wait out the rest.
+            deadline = [now.call + DRAIN_WINDOW, deadline].min if query_at && dropped.match?(CURSOR_REPLY)
+          end
+        end
+      rescue IOError, SystemCallError
+        nil
       end
 
       def available?(out:, input:, env:)

data/lib/samagotchi/terminal_ui/reline_seam.rb

@@ -66,6 +66,12 @@ module Samagotchi
         # @api private
         attr_writer :reading
 
+        # Monotonic time a read's cursor query went out (#reset) when the read
+        # was stopped before Reline took the reply: the reply is still on its
+        # way, and LiveRegion.close waits for it. nil with none.
+        # @return [Float, nil]
+        attr_accessor :unanswered_query_at
+
         # @return [Boolean] this Reline has every method the seam relies on
         def supported?
           defined?(Reline::LineEditor::RenderedScreen) &&
@@ -107,7 +113,11 @@ module Samagotchi
       end
 
       def reset(...)
+        # Reline's reset asks the terminal for the cursor row and waits for
+        # the reply: a Stop raised meanwhile leaves this set.
+        RelineSeam.unanswered_query_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         super
+        RelineSeam.unanswered_query_at = nil
         RelineSeam.reading = true
         @rendered_screen.base_y = 0 if RelineSeam.screen
       end

data/lib/samagotchi/turn_state.rb

@@ -23,6 +23,7 @@ module Samagotchi
       @controller = nil
       @sink = nil
       @steers = []
+      @carried_steers = []
     end
 
     # ── Activity clock ──────────────────────────────────────────────────
@@ -69,6 +70,8 @@ module Samagotchi
         @running = true
         @controller = controller
         @sink = sink
+        @steers.concat(@carried_steers)
+        @carried_steers = []
       end
     end
 
@@ -118,6 +121,25 @@ module Samagotchi
       true
     end
 
+    # Queue +text+ for the next turn that begins: it is a steer of that turn
+    # from its first boundary on (a continue turn's answer text, which has
+    # no turn running yet to steer). Taken by #begin!.
+    # @return [Boolean] whether it was queued (false: blank)
+    def steer_next_turn(text, source:)
+      text = text.to_s.strip
+      return false if text.empty?
+
+      @lock.synchronize { @carried_steers << { text: text, source: source.to_s } }
+      true
+    end
+
+    # Drop what #steer_next_turn queued and no turn began with (a no-op
+    # once #begin! took it).
+    # @return [Array<Hash>] the steers dropped ({text:, source:})
+    def drop_carried_steers
+      @lock.synchronize { @carried_steers.tap { @carried_steers = [] } }
+    end
+
     # @return [Array<Hash>] the steers queued so far ({text:, source:}), taken
     def take_steers
       @lock.synchronize { @steers.tap { @steers = [] } }

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.20.0"
+  VERSION = "0.22.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end