samagotchi 0.59.0 → 0.61.0

data/lib/samagotchi/continue_offer.rb

@@ -111,13 +111,15 @@ module Samagotchi
     end
 
     # The continue offer was answered yes: resume the conversation without a
-    # user message, with the iteration limit the offer's turn had. A failure
+    # user message, with the iteration limit the offer's turn had, from the
+    # run that turn started (TurnFlow#resume_from: its reasoning stays). A failure
     # keeps the offer, as the REPL does ("continue prompt preserved"), and
     # asks again, one before the turn began too (logged, no :turn_failed).
     # The answer's text is carried into the turn as it begins; a turn that
     # never began leaves it to no other.
     def run_continue_turn(command)
       offer = @turn_flow.offer
+      resume_from = @turn_flow.resume_from
       close("answered")
       steer = @continue_steer
       @continue_steer = nil
@@ -129,7 +131,8 @@ module Samagotchi
           Log.warn(:worker, "turn_not_begun", continue: true, error: e.class.name, msg: e.message)
           return announce_offer(offer)
         end
-        @run_turn.call(nil, continue: true, origin: { client_id: command.client_id }.compact,
+        @run_turn.call(nil, continue: true, origin: { client_id: command.client_id }.compact, resumed: true,
+                            resume_from: resume_from,
                             max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
           if error
             announce_offer(offer)

data/lib/samagotchi/engine.rb

@@ -64,6 +64,7 @@ require_relative "sampling_settings"
 require_relative "thinking"
 require_relative "reasoning_history"
 require_relative "answer_display"
+require_relative "answer_refs"
 require_relative "edit_preview"
 require_relative "question_desk"
 require_relative "child_reports"
@@ -105,11 +106,13 @@ module Samagotchi
     # @param memories           [Array<String>] explicit --memory preload list (merged with the config.yml `memories:` baseline)
     # @param muted_memories     [Array<String>] --mute list: memories hidden from this session (not in the
     #   prompt's index, dropped from the preloads, refused by memory_read); a mute wins over a preload
+    # @param appended_prompt_files [Array<String>] --append-system-prompt's files (absolute paths; a session's
+    #   appended_prompt_files): their text goes into the system prompt after config.yml's append_system_prompt:
     # @param plugins            [Boolean] false: load no bundle plugins (a throwaway Engine for a prompt)
     # @param scratch            [Boolean] a `chi scratch` session: memory writes are refused, and there is no
     #   delegate (a child would outlive it) nor plugin fork
     def initialize(client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, model_name: nil, memories: [], muted_memories: [], kernel: nil, recap: nil, reminders: nil,
-                   plugins: true, scratch: false, model_typed: nil)
+                   plugins: true, scratch: false, model_typed: nil, appended_prompt_files: [])
       # The turn as other threads see it (flag, cancel controller, sink,
       # steers) and the idle layer's activity clock. Built first: a plugin
       # may steer or ask whether a turn runs while it loads.
@@ -205,7 +208,7 @@ module Samagotchi
       @prompt_builder = SystemPrompt.new(profile: -> { self.profile }, tools: -> { @tools }, session: -> { @session },
                                          thinking: -> { turn_thinking }, model: -> { model_identity },
                                          model_notes: -> { model_notes }, memories: memories,
-                                         muted_memory_names: @muted_memory_names)
+                                         muted_memory_names: @muted_memory_names, appended_files: appended_prompt_files)
       @session = nil
       @session_observer = SessionObserver.new
       @metrics = SessionMetrics.new
@@ -1013,7 +1016,8 @@ module Samagotchi
       snapshot = snapshot.merge(served_model: served, served_model_for: served_for,
                                 served_expected_by: served_expected_by(served, target: target), llm_context: llm_context_summary,
                                 thinking: thinking_explained&.summary,
-                                reasoning_history: reasoning_history_explained&.summary, prompt_notes: prompt_notes.map(&:to_h), price_host: target.entry.name)
+                                reasoning_history: reasoning_history_explained&.summary, prompt_notes: prompt_notes.map(&:to_h),
+                                prompt_files: @prompt_builder.prompt_files, price_host: target.entry.name)
       unless snapshot.dig(:context, :window_tokens)
         window = current_context_window(target)
         if window
@@ -1475,19 +1479,31 @@ module Samagotchi
     private :save_quietly
 
     # Keep what the after_turn hooks presented as the answer's `display`
-    # and tell the observers (:answer_display), after the turn_completed
-    # they already had: the web re-reads the answer then. A turn_completed
+    # and the refs they attached as its `display_refs` (AnswerRefs, one
+    # replace for both), and tell the observers (:answer_display, the
+    # display or nil, and how many refs), after the turn_completed they
+    # already had: the web re-reads the answer then. A turn_completed
     # with display_pending (after_turn hooks were about to run) always gets
     # one, `display: nil` when nothing was presented, so the web holds the
     # answer's pop until then and never swaps it after. Terminals are not
     # sinks of it; they printed the answer already. The session is saved by
     # the caller, as after every turn.
-    def store_answer_display(session, display, pending: false)
+    def store_answer_display(session, display, refs, pending: false)
       synchronize_events do
+        # A plugin that kept event[:refs] and calls it later gets nil: the
+        # list is stored now (and the turn is over on every path).
+        refs.close!
         messages = Array(session.messages)
-        if display.changed? && messages.last.equal?(display.target)
-          replace_session_messages(session, messages[0...-1] + [display.target.merge(AnswerDisplay::KEY => display.text)])
-          @session_observer.notify({ type: :answer_display, display: display.text })
+        changed = display.changed? && messages.last.equal?(display.target)
+        added = refs.added? && messages.last.equal?(refs.target)
+        if changed || added
+          merged = messages.last.dup
+          merged[AnswerDisplay::KEY] = display.text if changed
+          merged[AnswerRefs::KEY] = refs.to_a if added
+          replace_session_messages(session, messages[0...-1] + [merged])
+          event = { type: :answer_display, display: changed ? display.text : nil }
+          event[:refs] = refs.count if added
+          @session_observer.notify(event)
         elsif pending
           @session_observer.notify({ type: :answer_display, display: nil })
         end
@@ -1518,7 +1534,7 @@ module Samagotchi
     private :hook_source
 
     # What a notice may stand in for (hook_notify's fallback_for:).
-    NOTICE_FALLBACKS = %i[display].freeze
+    NOTICE_FALLBACKS = %i[display editor].freeze
 
     # One line to the user (:hook_notice). During a turn it is a turn
     # event: the turn's sink (the REPL) and the observers (bridge, log).
@@ -1527,9 +1543,10 @@ module Samagotchi
     #
     # +fallback_for+ names what the line stands in for (NOTICE_FALLBACKS):
     # :display, the answer's display (AnswerDisplay), for a UI that doesn't
-    # render its links. A UI that does leaves the line out; the others, the
-    # log among them, show it. An unknown value is dropped, so the line
-    # shows everywhere.
+    # render its links; :editor, a ref the viewer could open in its editor
+    # (Web::Capabilities#editor), for a UI or a viewer that can't. A UI that
+    # does leaves the line out; the others, the log among them, show it. An
+    # unknown value is dropped, so the line shows everywhere.
     def hook_notify(text, level, hook, fallback_for: nil)
       level = (level || :info).to_sym
       level = :info unless %i[info warn].include?(level)
@@ -1801,8 +1818,14 @@ module Samagotchi
     # +id+: names the turn on :turn_started (its metrics record's id) and on
     # its saved prompt, so a UI pairs the two whatever left the conversation.
     # +limit+: the iteration limit #generate ran it with.
+    # +resumed+: a step-limit Continue (run_turn's resumed:).
+    # +resume_from+: where its reasoning starts, the run it resumes
+    # (run_turn's resume_from:); nil for every other turn, and for a
+    # Continue that starts cold (after a model change).
     Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id, :limit) do
+                      :settings, :id, :limit, :resumed, :resume_from) do
+      def resumed? = resumed ? true : false
+
       # The turn's boundary events carry the origin only when there is one,
       # so payloads stay unchanged for callers that don't pass it.
       def tag(event) = origin ? event.merge(origin: origin) : event
@@ -1832,6 +1855,14 @@ module Samagotchi
     # @param continue [Boolean] resume the conversation without appending a
     #   user prompt (continue after the iteration limit, reminder turns);
     #   +prompt+ is ignored and :turn_started carries `continue: true`
+    # @param resumed [Boolean] a step-limit Continue (with continue:):
+    #   :turn_started carries `resumed: true`, so do the before_turn payload
+    #   and the turn's analytics record. false for every other continue (a
+    #   reminder, a wake).
+    # @param resume_from [Integer, nil] a step-limit Continue's: where the
+    #   run it resumes started (ModelResult#run_start, kept in the offer by
+    #   TurnFlow), so it keeps that run's reasoning; nil starts cold (a
+    #   model change while the offer stood, every other turn).
     # @param origin [Hash, nil] who queued the turn ({client_id:, enqueued_id:});
     #   when given, the turn's boundary events (:turn_started, :turn_completed,
     #   :turn_canceled, :turn_failed) carry it as `origin:`
@@ -1854,9 +1885,13 @@ module Samagotchi
     # re-raises; a provider error adds error_kind:, retryable:, host: and a
     # one-line summary:.
     def run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
-                 images: [], id: nil)
+                 images: [], id: nil, resumed: false, resume_from: nil)
       turn = begin_turn(session, prompt, on_event: on_event, cancel_controller: cancel_controller, origin: origin,
                                          continue: continue, id: id)
+      if continue
+        turn.resumed = resumed
+        turn.resume_from = resume_from
+      end
       begin
         # A Stop cuts the /props probes this thread makes for the turn
         # (window, served model, vision) instead of waiting their timeout.
@@ -1939,6 +1974,7 @@ module Samagotchi
       bind_metrics(session)
       turn_started = { type: :turn_started, session_id: session.id, prompt: turn.prompt, turn_id: turn.id }
       turn_started[:continue] = true if turn.continue
+      turn_started[:resumed] = true if turn.resumed?
       turn_started[:images] = image_refs unless image_refs.empty?
       turn_started[:cut_after] = steer_cut_after
       emit_event(turn.on_event, turn.tag(turn_started))
@@ -1980,9 +2016,9 @@ module Samagotchi
       end
 
       # Fire :before_turn hook, with a read-only copy of the history so far
-      # and the prompt (nil on a continue).
+      # and the prompt (nil on a continue); resumed: a step-limit Continue.
       @hooks.fire(:before_turn, { type: :before_turn, session_id: session.id, prompt: turn.prompt,
-                                  messages: hook_messages(session.messages) })
+                                  resumed: turn.resumed?, messages: hook_messages(session.messages) })
 
       turn_messages(turn, image_refs)
       true
@@ -2118,18 +2154,39 @@ module Samagotchi
       log_llm_context(explained)
 
       turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
-      backend.complete(
+      # Where this run starts (ChatLoop::Run's start): an offer made at its
+      # end keeps it, so a Continue resumes this run.
+      run_start = turn.messages.length
+      reasoning_since = resumed_run_start(turn, run_start)
+      result = backend.complete(
         messages: turn.messages,
         max_iterations: turn.limit,
         on_stream_event: build_stream_event_handler(turn.on_event, cancel_controller: turn.controller),
         cancel_controller: turn.controller,
         model_name: bare_for_backend,
         max_tool_output_chars: max_tool_output_chars,
-        pending_input: turn_drain(pending_input)
+        pending_input: turn_drain(pending_input),
+        reasoning_since: reasoning_since
       )
+      result.run_start = run_start
+      result
     end
     private :generate
 
+    # A step-limit Continue's resume_from, when it is inside the messages the
+    # run gets (a wrong one only drops reasoning: it is ignored, logged).
+    # Entries before it never move between the turns (#turn_messages adds
+    # at the tail, and the system head is replaced in place).
+    def resumed_run_start(turn, run_start)
+      start = turn.resume_from
+      return nil if start.nil?
+      return start if start.is_a?(Integer) && start.between?(0, run_start)
+
+      Log.warn(:turn, "resume_start_invalid", resume_from: start, length: run_start)
+      nil
+    end
+    private :resumed_run_start
+
     # The turn's LLM context strategy and where it came from, in the turn
     # log: when it runs a layer, or the session set it (none too).
     def log_llm_context(explained)
@@ -2184,15 +2241,18 @@ module Samagotchi
 
       # Fire :after_turn hook (an answer or a Stop; an Interrupt or a failure
       # ends the turn in #run_turn without it), with a read-only
-      # copy of the conversation the turn stored, and event[:present] for
-      # a display version of the answer (AnswerDisplay).
+      # copy of the conversation the turn stored, event[:present] for
+      # a display version of the answer (AnswerDisplay) and event[:refs]
+      # for refs on it (AnswerRefs).
       session = turn.session
       display = AnswerDisplay.new(session.messages)
+      refs = AnswerRefs.new(session.messages, cwd: session.working_directory)
       after_turn = { type: :after_turn, status: canceled ? "canceled" : "completed",
                      messages: hook_messages(session.messages) }
       after_turn[:present] = display.presenter(after_turn)
+      after_turn[:refs] = refs.adder(after_turn)
       @hooks.fire(:after_turn, after_turn)
-      store_answer_display(session, display, pending: display_pending)
+      store_answer_display(session, display, refs, pending: display_pending)
 
       # Fire :session_end after the turn (turn-level lifecycle), as :after_turn
       @hooks.fire(:session_end, { type: :session_end, session_id: session.id })
@@ -2203,7 +2263,8 @@ module Samagotchi
     # replace). Runs under the event lock: it also adds the turn's note to
     # result.conversation, which the REPL keeps as-is.
     # A turn that ran out of iterations ends at its tool results, so a
-    # continue resumes from them rather than after a made-up reply.
+    # continue resumes from them rather than after a made-up reply (and a
+    # step-limit Continue from its run's start: ModelResult#run_start).
     def kept_messages(turn, result, seconds)
       conversation = result.conversation if result.conversation.is_a?(Array)
       # Nothing visible (no text) is a turn the model should know ended
@@ -2502,6 +2563,19 @@ module Samagotchi
       clone_messages(@session&.messages)
     end
 
+    # The running turn's conversation as its loop builds it (both loops
+    # register it on the kernel's llm_context_turn): the same array the loop
+    # appends to, not a copy, so read it on the turn's thread (the pending
+    # input drain, at an iteration boundary: TurnCheckpoint). nil when no
+    # turn runs (llm_context_turn is never cleared, and still holds the
+    # last turn's then).
+    # @return [Array<Hash>, nil]
+    def live_conversation
+      return nil unless turn_running? && @kernel.respond_to?(:llm_context_turn)
+
+      @kernel.llm_context_turn&.conversation
+    end
+
     # Append messages to the current session's conversation.
     # @param messages [Array<Hash>]
     # @return [Array<Hash>] the session's messages
@@ -2624,6 +2698,10 @@ module Samagotchi
         state_dir: -> { session_state_dir },
         scratch: -> { @scratch },
         setup: -> { SessionSetup.of(@session) },
+        # The files whose text the built system prompt holds; [] until a
+        # build and after a rebuild that drops them (SystemPrompt#prompt_files
+        # returns [] itself: the || keeps a nil builder safe).
+        prompt_files: -> { @prompt_builder&.prompt_files || [] },
         frontend: -> { interface }
       )
     end

data/lib/samagotchi/hooks/registry.rb

@@ -253,9 +253,11 @@ module Samagotchi
       #   event[:steer].call(text) -> true when the text was queued for the
       #     running turn's next boundary (its own user message, source: the
       #     hook's bundle); from after_turn / session_end false
-      # and after_turn's fire site adds one more (AnswerDisplay):
+      # and after_turn's fire site adds two more (AnswerDisplay, AnswerRefs):
       #   event[:present].call { |text| new_text } -> the answer's display
       #     text after the call (chained in hook order), nil without an answer
+      #   event[:refs].call(match:, kind:, target:, label: nil, actions: [])
+      #     -> true (kept), false (refused, logged), nil without an answer
       #
       # @param name [Symbol] the hook name to fire
       # @param event [Hash] the event payload (may be mutated by hooks)

data/lib/samagotchi/interrupted_turn.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The mark of a turn a worker checkpointed and never finished
+  # (Session#interrupted_turn, saved as session.json's "interrupted_turn"):
+  # TurnCheckpoint writes it with the turn's messages so far while the turn
+  # runs; the turn's end saves without it; the next worker to start finds it
+  # and settles the turn (Worker#settle_interrupted_turn).
+  #
+  # id: the turn's id (nil when unknown); started_at / at: iso8601, when the
+  # turn began and when this checkpoint was taken; iteration: the loop
+  # boundaries it had passed (Integer).
+  InterruptedTurn = Data.define(:id, :started_at, :at, :iteration) do
+    def initialize(id: nil, started_at: nil, at: nil, iteration: nil) = super
+
+    # A saved record (string or symbol keys), an InterruptedTurn as it is;
+    # nil for anything else.
+    # @return [InterruptedTurn, nil]
+    def self.from_file(raw)
+      return raw if raw.is_a?(InterruptedTurn)
+      return nil unless raw.is_a?(Hash)
+
+      new(**members.to_h { |m| [m, raw.key?(m.to_s) ? raw[m.to_s] : raw[m]] })
+    end
+
+    # @return [Hash{String => Object}] string keys, unset fields left out
+    def to_file = to_h.compact.transform_keys(&:to_s)
+
+    # Seconds from the turn's start to this checkpoint (nil when unknown).
+    # @return [Float, nil]
+    def seconds
+      return nil unless started_at && at
+
+      (Time.iso8601(at) - Time.iso8601(started_at)).clamp(0, Float::INFINITY)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/samagotchi/iteration_limit.rb

@@ -10,8 +10,9 @@ module Samagotchi
   module IterationLimit
     KEY = "turn.max_iterations"
     # A turn's limit unless turn.max_iterations says otherwise, and the
-    # loops' own default.
-    DEFAULT = 100
+    # loops' own default. Loops are caught by the loop-guard bundle and a
+    # long turn shows check-in's card well before it; this catches the rest.
+    DEFAULT = 300
     # A --no-interrupt / --non-interactive turn's, at least: nobody is there
     # to answer a continue offer.
     NO_INTERRUPT = 1000

data/lib/samagotchi/kernel_loop.rb

@@ -204,12 +204,18 @@ module Samagotchi
     #   steering mid-stream); drained lines merge into ONE user message appended
     #   at the conversation tail (prefix KV cache preserved) and a
     #   :pending_input_merged stream event is emitted.
+    # @param reasoning_since [Integer, nil] a step-limit Continue's: where the
+    #   run it resumes started in +messages+; that run's model messages keep
+    #   their thought blocks (#prepare_conversation), as within one run. nil:
+    #   every earlier thought is stripped.
     # @return [LLM::ModelResult] final visible response with continuation metadata
-    def run(messages, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil, model_name: nil, max_tool_output_chars: nil, pending_input: nil)
+    def run(messages, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil, model_name: nil, max_tool_output_chars: nil, pending_input: nil,
+            reasoning_since: nil)
       @turn_settings = @turn_settings.with(model_name: completion_model_name(model_name))
       @last_slot = nil
       turn = start_turn(messages, on_stream_event: on_stream_event, cancel_controller: cancel_controller,
-                                  pending_input: pending_input, cap: resolve_output_char_cap(max_tool_output_chars))
+                                  pending_input: pending_input, cap: resolve_output_char_cap(max_tool_output_chars),
+                                  reasoning_since: reasoning_since)
 
       max_iterations.times do |iteration_index|
         turn.iteration = iteration_index + 1
@@ -284,8 +290,8 @@ module Samagotchi
                             :buffer_mark, keyword_init: true)
     private_constant :Turn, :Request, :Generation
 
-    def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:)
-      conversation = prepare_conversation(messages)
+    def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:, reasoning_since: nil)
+      conversation = prepare_conversation(messages, keep_thought_from: thought_floor(messages, reasoning_since))
       context = ContextStatus.new(conversation: conversation, llm_context: @turn_settings.llm_context)
       emit = ->(event) { emit_stream_event(on_stream_event, event) }
       @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context, emit: emit)
@@ -992,20 +998,42 @@ module Samagotchi
       @profile.uses_role_prefixes? ? @profile.user_prefix : "#{@profile.turn_start}user\n"
     end
 
-    def sanitize_history(messages)
-      messages.map do |m|
-        if m[:role] == "model"
-          # `display` rides along so the stored conversation keeps it; the
-          # prompt formatter never reads it (AnswerDisplay).
-          { role: m[:role], content: strip_thought_blocks(m[:content].to_s), display: m[:display] }.compact
+    # +keep_thought_from+: model messages from this index on keep their
+    # thought blocks (a resumed run's); nil strips every one.
+    def sanitize_history(messages, keep_thought_from: nil)
+      messages.each_with_index.map do |m, index|
+        if m[:role] == "model" && keep_thought_from && index >= keep_thought_from
+          { role: m[:role], content: m[:content].to_s, display: m[:display], display_refs: m[:display_refs] }.compact
+        elsif m[:role] == "model"
+          # `display` and `display_refs` ride along so the stored
+          # conversation keeps them; the prompt formatter never reads them
+          # (AnswerDisplay, AnswerRefs).
+          { role: m[:role], content: strip_thought_blocks(m[:content].to_s), display: m[:display],
+            display_refs: m[:display_refs] }.compact
         else
           m.dup
         end
       end
     end
 
-    # Standard multi-turn compliance: never pass prior raw thought blocks.
-    def prepare_conversation(messages) = sanitize_history(messages)
+    # Standard multi-turn compliance: never pass prior raw thought blocks,
+    # but a resumed run's (+keep_thought_from+, #thought_floor): the same
+    # run going on after a step-limit Continue.
+    def prepare_conversation(messages, keep_thought_from: nil) = sanitize_history(messages, keep_thought_from: keep_thought_from)
+
+    # Where a resumed run's thought blocks start: its start (+since+). Inside
+    # one native run nothing re-sanitizes, so a user entry the run merged (a
+    # steer, a delegate report, the Qwen recovery prompt) left the thoughts
+    # before it in the prompt: they stay. Only a user or turn_start entry
+    # added after the run ended (after its last model message: a !cmd's
+    # output) starts them again past itself. nil without +since+.
+    def thought_floor(messages, since)
+      return nil if since.nil?
+
+      last_reply = messages.rindex { |m| m[:role].to_s == "model" } || -1
+      query = messages.rindex { |m| m[:role].to_s == "user" || m[:turn_start] == true }
+      query && query > last_reply ? [query + 1, since].max : since
+    end
 
     def duplicate_conversation(messages)
       messages.map(&:dup)

data/lib/samagotchi/llm/backend.rb

@@ -14,9 +14,14 @@ module Samagotchi
     # extra surface lives on backend-specific subclasses, never on this interface.
     #
     # The raw-prompt KernelLoop is NativeBackend; the chat loop is ChatLoop.
+    #
+    # +reasoning_since+: where the run a step-limit Continue resumes started
+    # in +messages+ (Engine#run_turn resume_from:); the replies from there on
+    # keep the model's reasoning (thought blocks), as within one run. nil:
+    # the run starts here, as every other turn's does.
     class ModelBackend
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
-                   model_name: nil, max_tool_output_chars: nil, pending_input: nil)
+                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
         raise NotImplementedError, "#{self.class}#complete must be implemented"
       end
     end

data/lib/samagotchi/llm/chat_loop.rb

@@ -11,6 +11,7 @@ require_relative "native_tool_normalizer"
 require_relative "stream_drops"
 require_relative "../kernel_loop"
 require_relative "../answer_display"
+require_relative "../answer_refs"
 require_relative "../cut_policy"
 require_relative "../context_status"
 require_relative "../context_window"
@@ -68,12 +69,14 @@ module Samagotchi
 
       def provider = :chat
 
+      # +reasoning_since+ (ModelBackend#complete): the resumed run's start,
+      # the Run's own start then (#reasoning_boundary).
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
-                   model_name: nil, max_tool_output_chars: nil, pending_input: nil)
+                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
         raise ArgumentError, "ChatLoop has no adapter" unless @adapter
 
         conversation = Array(messages).map(&:dup)
-        Run.new(self, conversation, on_stream_event, cancel_controller, model_name, pending_input)
+        Run.new(self, conversation, on_stream_event, cancel_controller, model_name, pending_input, start: reasoning_since)
            .call(max_iterations: max_iterations || 1, cap: KernelLoop.resolve_output_char_cap(max_tool_output_chars))
       rescue StandardError => e
         FailedTurn.attach(e, conversation && plain(conversation))
@@ -195,7 +198,8 @@ module Samagotchi
       # user message: a prompt, a steer, merged input, the chat template's
       # last query; or an entry that starts a turn, turn_start) and +since+
       # (the Run's start, so a continue turn -- a reminder, a context wake,
-      # a continue after a stop -- sends none of the run before it).
+      # a delegate report's wake -- sends none of the run before it; a
+      # step-limit Continue's Run starts where the run it resumes did).
       # @return [Integer, nil]
       def reasoning_boundary(conversation, since: nil, level: reasoning_history)
         case level
@@ -299,8 +303,9 @@ module Samagotchi
       # refs of a user message or a tool result, a prompt's turn_id (Engine,
       # never sent) and a wake turn's report's turn_start (Steer, never sent), and a plugin tool result's tool_params and tool_labels
       # (the live row's params line and label, never sent back), an
-      # edit/write result's tool_diffs (never sent), and an empty-answer
-      # note's marker (TurnNote.empty, never sent).
+      # edit/write result's tool_diffs (never sent), an empty-answer
+      # note's marker (TurnNote.empty, never sent), and an answer's display
+      # and display_refs (AnswerDisplay, AnswerRefs; never sent).
       def plain(conversation)
         conversation.map do |entry|
           content = entry[:content].is_a?(Array) ? entry[:content] : entry[:content].to_s
@@ -316,6 +321,7 @@ module Samagotchi
           marker = TurnNote.empty_answer(entry)
           message[TurnNote::EMPTY_ANSWER] = marker if marker
           message[AnswerDisplay::KEY] = entry[AnswerDisplay::KEY] if entry[AnswerDisplay::KEY]
+          message[AnswerRefs::KEY] = entry[AnswerRefs::KEY] if entry[AnswerRefs::KEY]
           ContextNote::KEYS.each { |key| message[key] = entry[key] if entry.key?(key) }
           message
         end
@@ -402,7 +408,9 @@ module Samagotchi
       # One turn's state: the conversation, the stream sink and tool
       # activity.
       class Run
-        def initialize(loop, conversation, on_stream_event, cancel_controller, model_name, pending_input)
+        # +start+: where the run a step-limit Continue resumes started (nil:
+        # this run starts at the conversation's end).
+        def initialize(loop, conversation, on_stream_event, cancel_controller, model_name, pending_input, start: nil)
           @loop = loop
           @conversation = conversation
           @on_stream_event = on_stream_event
@@ -410,8 +418,8 @@ module Samagotchi
           @model_name = model_name
           @pending_input = pending_input
           # Where this run's entries start: the reasoning it sends back
-          # (ChatLoop#reasoning_boundary) is its own.
-          @start = conversation.length
+          # (ChatLoop#reasoning_boundary) is its own, a resumed run's too.
+          @start = start || conversation.length
           @tool_activity = []
           @empty_retry = EmptyAnswerRetry.new
           # The empty generations, never saved: the UIs draw the turn's

data/lib/samagotchi/llm/model_result.rb

@@ -14,9 +14,15 @@ module Samagotchi
     # generations as model messages, which the loops keep out of the
     # conversation) and .empty_retries (the retries spent): the Engine saves
     # them on the turn's note for the UIs (TurnNote.empty).
+    #
+    # .run_start is where the turn's run started in the conversation (the
+    # length of the messages the loop got), set by the Engine after the loop
+    # returns; nil from a loop called directly. A step-limit offer keeps it
+    # (TurnFlow), so a Continue resumes that run (Engine#run_turn resume_from:).
     class ModelResult
       attr_reader :text, :conversation, :canceled, :cancellation_reason, :exhausted,
                   :tool_activity, :context_status, :pending_tool_calls, :empty_steps, :empty_retries
+      attr_accessor :run_start
 
       def initialize(text:, conversation: nil, canceled: false, cancellation_reason: nil, exhausted: false,
                      tool_activity: [], context_status: nil, pending_tool_calls: false, empty_steps: [], empty_retries: 0)
@@ -57,8 +63,11 @@ module Samagotchi
         !!pending_tool_calls
       end
 
-      # KernelLoop only marks a run exhausted when it stopped on pending tool
-      # calls, so exhausted? alone already means "resumable".
+      # A run that ran out of iterations can be continued (the step-limit
+      # offer). KernelLoop marks one exhausted only when it stopped on pending
+      # tool calls; ChatLoop also leaves it exhausted when its last iteration
+      # ended in a retry (an empty answer's nudge, a cut) or merged input
+      # after an answer, which a Continue then picks up.
       def resumable?
         exhausted?
       end

data/lib/samagotchi/llm/native_backend.rb

@@ -17,7 +17,7 @@ module Samagotchi
       def provider = :native
 
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
-                   model_name: nil, max_tool_output_chars: nil, pending_input: nil)
+                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
         @kernel.run(
           messages,
           max_iterations: max_iterations,
@@ -25,7 +25,8 @@ module Samagotchi
           cancel_controller: cancel_controller,
           model_name: model_name,
           max_tool_output_chars: max_tool_output_chars,
-          pending_input: pending_input
+          pending_input: pending_input,
+          reasoning_since: reasoning_since
         )
       end
     end

data/lib/samagotchi/log_subscriber.rb

@@ -63,7 +63,8 @@ module Samagotchi
       @generation_started_at.clear
       @tool_started_at.clear
       log(:info, :turn_started, session: event[:session_id], prompt_chars: event[:prompt].to_s.length,
-                                continue: event[:continue] || nil, **items(event), **origin(event))
+                                continue: event[:continue] || nil, resumed: event[:resumed] || nil, **items(event),
+                                **origin(event))
     end
 
     def on_turn_completed(event)
@@ -151,10 +152,13 @@ module Samagotchi
       log(level, :hook_notice, hook: event[:hook], fallback_for: event[:fallback_for], msg: event[:text].to_s[0, 300])
     end
 
-    # after_turn hooks presented the answer (AnswerDisplay): its size only
-    # (none for the display: nil that says nothing was presented).
+    # after_turn hooks presented the answer (AnswerDisplay) or attached refs
+    # to it (AnswerRefs): the display's size and the refs' count only (none
+    # for the display: nil that says nothing was presented).
     def on_answer_display(event)
-      log(:info, :answer_display, chars: event[:display].to_s.length) if event[:display]
+      return unless event[:display] || event[:refs]
+
+      log(:info, :answer_display, chars: event[:display]&.length, refs: event[:refs])
     end
 
     # A card shown to the user (Engine#show_card): whose, which, and its