samagotchi 0.60.0 → 0.62.0

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"
@@ -23,6 +24,7 @@ require_relative "../vision_context"
 require_relative "../log"
 require_relative "../empty_answer_retry"
 require_relative "../steer"
+require_relative "../reasoning_history"
 require_relative "../turn_note"
 require_relative "../thinking"
 
@@ -69,7 +71,7 @@ module Samagotchi
       def provider = :chat
 
       # +reasoning_since+ (ModelBackend#complete): the resumed run's start,
-      # the Run's own start then (#reasoning_boundary).
+      # the Run's own start then (Run#initialize, #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, reasoning_since: nil)
         raise ArgumentError, "ChatLoop has no adapter" unless @adapter
@@ -136,7 +138,8 @@ module Samagotchi
       # A model turn carries its saved reasoning as reasoning_content when
       # +reasoning+ (a ReasoningHistory level; the turn's by default) says
       # so: under turn the running turn's only (#reasoning_boundary, with
-      # +since+ the Run's start), under all every one.
+      # +since+ where the Run's reasoning starts; a steer it merged doesn't
+      # move that), under all every one.
       #
       # The conversation goes through the kernel's LLMContextView first,
       # as the native prompt does (it keeps every entry in place).
@@ -193,19 +196,24 @@ module Samagotchi
       TOOL_IMAGES_TEXT = "[images from tool results]"
 
       # The first index whose model entries carry their reasoning (nil:
-      # none do) under +level+. Under turn: past both the last query (a
-      # 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 delegate report's wake -- sends none of the run before it; a
-      # step-limit Continue's Run starts where the run it resumes did).
+      # none do) under +level+. Under turn: +since+ when given, where a
+      # Run's reasoning starts (ReasoningHistory.run_start, the native
+      # loop's rule: an entry the run merged -- a person's line, a plugin's
+      # steer, a Continue's text -- keeps the reasoning before it, so the
+      # request after it extends the one before; a continue turn -- a
+      # reminder, a context wake, a delegate report's wake -- starts a Run
+      # of its own and sends none of the run before it). Without +since+,
+      # past the last query (a user message or an entry that starts a turn,
+      # turn_start).
       # @return [Integer, nil]
       def reasoning_boundary(conversation, since: nil, level: reasoning_history)
         case level
         when :all then 0
         when :turn
+          return since if since
+
           query = conversation.rindex { |entry| entry[:role].to_s == "user" || entry[:turn_start] == true }
-          [query ? query + 1 : 0, since.to_i].max
+          query ? query + 1 : 0
         end
       end
 
@@ -302,8 +310,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
@@ -319,6 +328,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
@@ -414,9 +424,10 @@ module Samagotchi
           @cancel_controller = cancel_controller
           @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, a resumed run's too.
-          @start = start || conversation.length
+          # Where the reasoning this run sends back starts
+          # (ChatLoop#reasoning_boundary): its own replies', a resumed run's
+          # too, fixed for the run; a steer it merges doesn't move it.
+          @reasoning_start = ReasoningHistory.run_start(conversation, start || conversation.length)
           @tool_activity = []
           @empty_retry = EmptyAnswerRetry.new
           # The empty generations, never saved: the UIs draw the turn's
@@ -593,7 +604,7 @@ module Samagotchi
 
         def request(iteration, retry_generation, streamed, thought, generation_controller, streamed_any = nil)
           @loop.adapter.chat(
-            messages: @loop.wire_messages(@conversation, since: @start, reasoning: reasoning_level), tools: @loop.tool_definitions, model: @model_name,
+            messages: @loop.wire_messages(@conversation, since: @reasoning_start, reasoning: reasoning_level), tools: @loop.tool_definitions, model: @model_name,
             cancel_controller: generation_controller || @cancel_controller, session_id: @loop.session_id,
             options: @loop.request_options(retry_generation: retry_generation, model: @model_name),
             on_delta: lambda { |content:, reasoning:, payload:|
@@ -667,7 +678,7 @@ module Samagotchi
 
         # Whether this step's request sends reasoning back.
         def reasoning_sent?
-          !@without_reasoning && @loop.reasoning_chars(@conversation, since: @start, reasoning: reasoning_level).positive?
+          !@without_reasoning && @loop.reasoning_chars(@conversation, since: @reasoning_start, reasoning: reasoning_level).positive?
         end
 
         # The level this step's request sends reasoning back under: none
@@ -730,7 +741,7 @@ module Samagotchi
         # names and arguments, and the reasoning sent back.
         def prompt_chars
           LLMContextView.chars(@loop.llm_context_view.messages(@conversation)) +
-            @loop.reasoning_chars(@conversation, since: @start, reasoning: reasoning_level)
+            @loop.reasoning_chars(@conversation, since: @reasoning_start, reasoning: reasoning_level)
         end
 
         # The server's counts for this request (prompt + answer): the status

data/lib/samagotchi/log_subscriber.rb

@@ -152,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

data/lib/samagotchi/plugin/api.rb

@@ -79,9 +79,11 @@ module Samagotchi
       # @param targets [#call, nil] args → what guardrail rules match: a Hash
       #   with paths: (absolute or relative to the cwd), command: (a shell
       #   command) and cwd:, each optional
-      def tool(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &)
-        spec = Api.tool_spec(name, description, params: params, schema: schema, label: label, preview: preview,
-                                                targets: targets, &)
+      # @param refs [#call, nil] args → the call's row's refs, display only:
+      #   a list of {kind:, target:, label:, actions:} (RowRefs, Ref). Run
+      #   once per call on the tool path, so it must be cheap (no I/O)
+      def tool(name, description, **, &)
+        spec = Api.tool_spec(name, description, **, &)
         if (taken = @registries.tools[spec[:name]])
           raise ArgumentError, "tool #{spec[:name]} is already registered (#{taken.source})"
         end
@@ -125,9 +127,8 @@ module Samagotchi
         end
 
         # As Api#tool.
-        def tool(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &)
-          spec = Api.tool_spec(name, description, params: params, schema: schema, label: label, preview: preview,
-                                                  targets: targets, &)
+        def tool(name, description, **, &)
+          spec = Api.tool_spec(name, description, **, &)
           raise ArgumentError, "tool #{spec[:name]} is registered twice" if @specs.any? { |s| s[:name] == spec[:name] }
 
           @specs << spec
@@ -249,34 +250,44 @@ module Samagotchi
       def counts = { commands: @commands.size, tools: @tools.size, hooks: @hooks.size, services: @services.size,
                      inits: @inits.size }
 
-      # A checked tool declaration (#tool's arguments).
-      # @return [Hash] {name:, schema:, label:, preview:, targets:, block:}
-      def self.tool_spec(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &block)
+      # A checked tool declaration (#tool's arguments: Api#tool and
+      # ToolSet#tool pass theirs on, so a new keyword is added here).
+      # @return [Hash] {name:, schema:, label:, preview:, targets:, refs:, block:}
+      def self.tool_spec(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, refs: nil,
+                         &block)
         raise ArgumentError, "tool #{name.inspect} needs a block" unless block
 
         name = name.to_s
         raise ArgumentError, "tool name #{name.inspect} must be a-z, 0-9 and _ (at most 48)" unless name.match?(TOOL_NAME)
         raise ArgumentError, "tool #{name}: preview must respond to #call" if preview && !preview.respond_to?(:call)
         raise ArgumentError, "tool #{name}: targets must respond to #call" if targets && !targets.respond_to?(:call)
+        raise ArgumentError, "tool #{name}: refs must respond to #call" if refs && !refs.respond_to?(:call)
 
         parameters = schema ? schema_parameters(name, schema) : params_schema(name, params)
         { name: name, schema: { name: name, description: description.to_s, parameters: parameters },
-          label: label&.to_s, preview: preview, targets: targets, block: block }
+          label: label&.to_s, preview: preview, targets: targets, refs: refs, block: block }
       end
 
       # Make +bundle+'s tools in +registry+ the +specs+: its tools not in
       # them go; a new one, or one whose schema or label changed, is
       # registered (a changed one again, in its place: Tools::Registry
       # orders bundle tools by bundle and name); an unchanged one is kept
-      # as it is. A name another source has is left out. Called on
-      # the turn thread (Engine#apply_staged_tools!).
+      # as it is, but for its block, preview:, targets: and refs:, swapped
+      # in place: none of them reaches the prompt, so not a change (that
+      # would build the prompts again). A name
+      # another source has is left out. Called on the turn thread
+      # (Engine#apply_staged_tools!).
       # @return [Hash] {changed: Boolean, skipped: [String] (why)}
       def self.apply_tools(registry, bundle, specs, context)
         wanted = specs.to_h { |spec| [spec[:name], spec] }
         changed = false
         registry.entries.each do |entry|
           next unless entry.source == bundle
-          next if (spec = wanted[entry.name]) && spec[:schema] == entry.schema && spec[:label] == entry.label
+
+          if (spec = wanted[entry.name]) && spec[:schema] == entry.schema && spec[:label] == entry.label
+            entry_fields(spec, context).slice(:handler, :preview, :targets, :refs).each { |key, value| entry[key] = value }
+            next
+          end
 
           registry.unregister(entry.name)
           changed = true
@@ -295,23 +306,30 @@ module Samagotchi
       end
 
       # Registry#register's keywords for a tool declaration: its block
-      # wrapped as a handler (typed args, the Context), preview, targets.
+      # wrapped as a handler (typed args, the Context), preview, targets, refs.
       def self.entry_fields(spec, context)
         block = spec[:block]
-        preview = spec[:preview]
-        targets = spec[:targets]
         parameters = spec[:schema][:parameters]
+        preview = per_call(spec[:preview], parameters)
         {
           schema: spec[:schema], label: spec[:label],
           handler: lambda { |call, _kctx|
             result = block.call(Api.args_of(call, parameters), context)
             Api.result_text(result)
           },
-          preview: preview && ->(call) { preview.call(Api.args_of(call, parameters))&.to_s },
-          targets: targets && ->(call) { targets.call(Api.args_of(call, parameters)) }
+          preview: preview && ->(call) { preview.call(call)&.to_s },
+          targets: per_call(spec[:targets], parameters),
+          refs: per_call(spec[:refs], parameters)
         }
       end
 
+      # A plugin's args → value lambda (+fn+) as call → value: it gets the
+      # call's typed args (Api.args_of), as the tool's block does. nil
+      # without one.
+      def self.per_call(fn, parameters)
+        fn && ->(call) { fn.call(Api.args_of(call, parameters)) }
+      end
+
       # A tool's result as the model reads it: a String (a ToolResult too,
       # with its images) as it is, a Hash or Array as JSON (its #to_s is
       # Hash#inspect, which changes with the Ruby version), else #to_s.

data/lib/samagotchi/reasoning_history.rb

@@ -7,9 +7,9 @@ module Samagotchi
   # Which of its own reasoning a chat host's model gets back
   # (LLM::ChatLoop sends it as reasoning_content on its earlier replies):
   #
-  #   turn  the running turn's replies only (the tool-call rounds since the
-  #         last user message); what Qwen's, Gemma 4's and DeepSeek's
-  #         templates and the hosted APIs expect
+  #   turn  the running turn's replies only (since the turn's start; a
+  #         steer, a plugin's nudge or a Continue's text merged into the
+  #         turn doesn't reset it, as on a native host: .run_start)
   #   drop  none
   #   all   every reply that has reasoning, earlier turns too (a direct
   #         DeepSeek API with tools wants this)
@@ -17,7 +17,8 @@ module Samagotchi
   # Order (#resolve): the session's own level (/reasoning-history), then
   # SAMAGOTCHI_REASONING_HISTORY, models.<key>.reasoning_history,
   # hosts.<name>.reasoning_history, then turn. Native hosts ignore it:
-  # KernelLoop keeps the running turn's reasoning on its own.
+  # KernelLoop keeps the running turn's reasoning on its own, from the
+  # run's start (.run_start).
   module ReasoningHistory
     LEVELS = %i[drop turn all].freeze
     DEFAULT = :turn
@@ -118,6 +119,23 @@ module Samagotchi
       end
     end
 
+    # Where a run's own reasoning starts in +messages+: its start (+since+;
+    # nil without one). Inside one run nothing re-sanitizes, so an entry the
+    # run merged (a steer, a delegate report, the Qwen recovery prompt) left
+    # the reasoning before it in the prompt: it stays. Only a user or
+    # turn_start entry added after the run ended (after its last model
+    # message: a !cmd's output) starts it again past itself.
+    # @param messages [Array<Hash>] the conversation
+    # @param since [Integer, nil] the run's start
+    # @return [Integer, nil]
+    def run_start(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
+
     # "drop (models: qwen)", "turn (default)".
     def label(level, source) = "#{level} (#{source || "default"})"
 

data/lib/samagotchi/ref.rb

@@ -10,14 +10,17 @@ module Samagotchi
   # (refs.js httpUrl): the page opens it as is, so a javascript:, data: or
   # editor URL never gets there.
   RefAction = Data.define(:id, :label, :url) do
-    # @raise [ArgumentError] an empty id or label, or a URL that isn't an
-    #   http(s) one with a host, at most MAX_URL characters
+    # @raise [ArgumentError] an empty id or label, one over its cap
+    #   (MAX_ID, MAX_LABEL), or a URL that isn't an http(s) one with a host,
+    #   at most MAX_URL characters
     def initialize(id:, label:, url:)
       id = id.to_s.strip
       label = label.to_s.strip
       url = url.to_s.strip
       raise ArgumentError, "a ref action needs an id" if id.empty?
       raise ArgumentError, "a ref action needs a label" if label.empty?
+      raise ArgumentError, "a ref action's id is at most #{RefAction::MAX_ID} characters" if id.length > RefAction::MAX_ID
+      raise ArgumentError, "a ref action's label is at most #{RefAction::MAX_LABEL} characters" if label.length > RefAction::MAX_LABEL
       raise ArgumentError, "a ref action's url must be http(s) with a host, at most #{RefAction::MAX_URL} characters" unless RefAction.http_url?(url)
 
       super
@@ -26,13 +29,17 @@ module Samagotchi
 
   class RefAction
     MAX_URL = 2_000
+    MAX_ID = 64
+    MAX_LABEL = 100
 
-    # @return [Boolean] +url+ is an http or https URL with a host
+    # @return [Boolean] +url+ is an http or https URL with a host and no
+    #   userinfo (a "https://github.com@evil.example/" shows one host and
+    #   opens another, and a token in it would be copied around)
     def self.http_url?(url)
       return false if url.length > MAX_URL
 
       uri = URI.parse(url)
-      uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+      uri.is_a?(URI::HTTP) && !uri.host.to_s.empty? && uri.userinfo.nil?
     rescue URI::InvalidURIError
       false
     end
@@ -61,13 +68,17 @@ module Samagotchi
   # rows' own ref; this is the one a plugin gives.
   Ref = Data.define(:kind, :target, :label, :actions) do
     # @raise [ArgumentError] a kind that isn't a short lowercase word, a
-    #   target without its kind's key, a non-list of actions or a bad action
+    #   target without its kind's key, a non-list of actions, a bad action,
+    #   or a value over its cap (MAX_LABEL, MAX_ACTIONS, MAX_ID, MAX_PATH)
     def initialize(kind:, target:, label: nil, actions: [])
       kind = kind.to_s
       raise ArgumentError, "a ref's kind is a short lowercase word (#{kind.inspect})" unless Ref::KIND.match?(kind)
       raise ArgumentError, "a ref's actions are a list" unless actions.nil? || actions.is_a?(Array)
+      raise ArgumentError, "a ref has at most #{Ref::MAX_ACTIONS} actions" if Array(actions).length > Ref::MAX_ACTIONS
 
       label = label.to_s.strip
+      raise ArgumentError, "a ref's label is at most #{Ref::MAX_LABEL} characters" if label.length > Ref::MAX_LABEL
+
       super(kind: kind, target: Ref.target_for(kind, target), label: label.empty? ? nil : label,
             actions: Array(actions).map { |action| RefAction.from(action) }.freeze)
     end
@@ -81,6 +92,11 @@ module Samagotchi
     KIND = /\A[a-z][a-z0-9_-]{0,31}\z/
     # FileRef::KIND, not required here (it loads the file tools).
     FILE = "file"
+    # Caps, so a plugin can't bloat session.json or the page.
+    MAX_LABEL = 200
+    MAX_ACTIONS = 8
+    MAX_ID = 200
+    MAX_PATH = 4_096
 
     # A plugin's {kind:, target:, label:, actions:} (String or Symbol keys).
     # @raise [ArgumentError] as +new+
@@ -97,19 +113,20 @@ module Samagotchi
       raise ArgumentError, "a ref's target is a Hash" unless raw.is_a?(Hash)
 
       raw = raw.transform_keys(&:to_sym)
-      kind == FILE ? file_target(raw) : { id: required(raw[:id], :id) }.freeze
+      kind == FILE ? file_target(raw) : { id: required(raw[:id], :id, MAX_ID) }.freeze
     end
 
     def self.file_target(raw)
       line = positive(raw[:line])
       end_line = line && positive(raw[:end_line])
-      { path: required(raw[:path], :path), line: line, end_line: end_line && end_line > line ? end_line : nil }.compact.freeze
+      { path: required(raw[:path], :path, MAX_PATH), line: line, end_line: end_line && end_line > line ? end_line : nil }.compact.freeze
     end
     private_class_method :file_target
 
-    def self.required(value, key)
+    def self.required(value, key, max)
       value = value.to_s.strip
       raise ArgumentError, "a ref's target needs #{key}" if value.empty?
+      raise ArgumentError, "a ref's target #{key} is at most #{max} characters" if value.length > max
 
       value
     end

data/lib/samagotchi/reply_wait.rb

@@ -106,10 +106,14 @@ module Samagotchi
 
         if session.status == Session::STATUS_RUNNING
           seen_running = true
-        elsif seen_running || turn_ended_since?(session, baseline)
+        elsif (seen_running && !baseline&.key?(:last_turn)) || turn_ended_since?(session, baseline)
           # It ran and is idle again with no new reply: canceled, failed or
           # empty. Before it was ever seen running, idle means a
-          # file-delivered message its worker has not picked up yet.
+          # file-delivered message its worker has not picked up yet. With
+          # the baseline's last_turn only a turn that ended since counts:
+          # a session left running by a worker that died goes idle when the
+          # next worker settles that turn (TurnCheckpoint.settle), before
+          # the sent message's turn runs.
           # The worker writes the reply before its idle save, so the read
           # above has it; one more look costs nothing should that change.
           return reply_past(id, state_dir: state_dir, cursor: cursor)&.tap { |r| r.session = session } ||

data/lib/samagotchi/row_refs.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "log"
+require_relative "ref"
+
+module Samagotchi
+  # The refs a plugin tool gives its row (chi.tool's refs: lambda, traceable
+  # refs P5d): what the call traces to (a ticket, a PR, a file), each a Ref
+  # whose +to_h+ the row carries as +refs+ on tool_call_started and
+  # tool_call_completed (ToolRowFields::EVENT_KEYS), saved with the result
+  # as tool_refs (ToolResponse::SAVED_KEYS) for a reload, which has no
+  # plugins (Web::MessageParts). Display only: the model never sees them.
+  #
+  # A file ref is any file under the session's folder (plan D7): a relative
+  # path is resolved against it, a path outside it is dropped. The folder
+  # counts under its own spelling and its real path (macOS /tmp is
+  # /private/tmp), and a kept path is stored under the real one, so a
+  # reload under either spelling keeps it. The page
+  # shows the first ref on the row's title and the rest in its menu.
+  module RowRefs
+    # Per row, so a plugin can't bloat the events or session.json.
+    MAX_REFS = 20
+    # The row's refs' JSON; a ref that would cross it is left out.
+    MAX_BYTES = 64 * 1024
+
+    module_function
+
+    # Runs +fn+ (the tool's refs: lambda, as Api.per_call wraps it: call →
+    # a list of {kind:, target:, label:, actions:}) on +call+. Never
+    # raises: a lambda that raises or returns something other than a list
+    # gives none, and a bad ref is dropped; both are logged (warn, not
+    # echoed: the turn's live region is on screen).
+    # @param cwd [String, nil] the session's folder
+    # @return [Array<Hash>] Ref#to_h each, deduped, at most MAX_REFS
+    def for(fn, call, cwd:)
+      return [] unless fn
+
+      tool = call[:name].to_s
+      raw = fn.call(call)
+      return [] if raw.nil?
+      raise ArgumentError, "refs: returned #{raw.class}, not a list" unless raw.is_a?(Array)
+
+      build(raw, cwd) { |why| Log.warn(:plugins, "tool_refs_rejected", tool: tool, reason: why) }
+    rescue StandardError => e
+      Log.warn(:plugins, "tool_refs_failed", tool: tool, error: "#{e.class}: #{e.message}")
+      []
+    end
+
+    # Stored refs (+raw+, a saved tool_refs entry), each rebuilt and
+    # checked again as #for checks a lambda's: a stored file is never
+    # trusted. What isn't valid any more is dropped, a relative path too
+    # (it was stored absolute). Never raises: a reload must show the
+    # conversation.
+    # @return [Array<Hash>]
+    def for_display(raw, cwd:)
+      return [] unless raw.is_a?(Array)
+
+      build(raw, cwd, relative: false) { |_why| nil }
+    rescue StandardError
+      []
+    end
+
+    # +raw+'s valid refs as Ref#to_h; +rejected+ gets why each other one
+    # was dropped. +relative+: a relative file path is resolved against
+    # +cwd+ (else dropped).
+    def build(raw, cwd, relative: true, &)
+      roots = roots(cwd)
+      bytes = 2 # the list's []
+      raw.each_with_object([]) do |value, refs|
+        break refs if refs.length >= MAX_REFS
+
+        hash = inside(Ref.from(value), roots, relative).to_h
+        next if refs.include?(hash)
+
+        size = JSON.generate(hash).bytesize + (refs.empty? ? 0 : 1)
+        break refs if bytes + size > MAX_BYTES
+
+        bytes += size
+        refs << hash
+      # One junk ref ({1 => "x"}, a nil target) goes alone.
+      rescue ArgumentError, TypeError, NoMethodError => e
+        yield(e.message)
+      end
+    end
+    private_class_method :build
+
+    # +cwd+ as [its spelling, its real path] (one when they are the same,
+    # none without a +cwd+). absolute_path, not expand_path: a leading ~ is
+    # a name, never a home. One realpath per row: the lambda's refs are
+    # checked together.
+    def roots(cwd)
+      return [] if cwd.to_s.empty?
+
+      given = File.absolute_path(cwd.to_s)
+      real = begin
+        File.realpath(given)
+      rescue SystemCallError
+        given
+      end
+      [given, real].uniq
+    end
+    private_class_method :roots
+
+    # +ref+ with a file's path absolute, resolved against the folder
+    # (+roots+, #roots), under its real spelling.
+    # @raise [ArgumentError] a relative path with no folder (or not
+    #   +relative+), or a path outside the folder
+    def inside(ref, roots, relative)
+      return ref unless ref.kind == Ref::FILE
+
+      path = ref.target[:path]
+      unless File.absolute_path?(path) || (relative && roots.any?)
+        raise ArgumentError, "a file ref's relative path needs the session folder"
+      end
+      return ref if roots.empty?
+
+      path = File.absolute_path(path, roots.first)
+      root = roots.find { |dir| path == dir || path.start_with?(dir.end_with?("/") ? dir : "#{dir}/") }
+      raise ArgumentError, "a file ref outside the session folder (#{path})" unless root
+
+      ref.with(target: ref.target.merge(path: "#{roots.last}#{path.delete_prefix(root)}").freeze)
+    end
+    private_class_method :inside
+  end
+end

data/lib/samagotchi/session.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "time"
 require_relative "atomic_file"
 require_relative "context_note"
+require_relative "interrupted_turn"
 require_relative "last_turn"
 require_relative "llm_context_override"
 require_relative "session_setup"
@@ -107,6 +108,26 @@ module Samagotchi
     def last_turn=(value)
       @last_turn = LastTurn.from_file(value)
     end
+
+    # The mark of a turn a worker checkpointed and never finished
+    # (InterruptedTurn), as loaded; the next worker settles it and sets it
+    # to nil. While a turn runs, #turn_checkpoint's marker is saved instead.
+    attr_reader :interrupted_turn
+
+    # @param value [InterruptedTurn, Hash, nil]
+    def interrupted_turn=(value)
+      @interrupted_turn = InterruptedTurn.from_file(value)
+    end
+
+    # The running turn's checkpoint (TurnCheckpoint): {messages:, marker:}
+    # (marker an InterruptedTurn). While +status+ is running, every save
+    # writes these messages and the marker instead of #messages and
+    # #interrupted_turn, so a save in the middle of the turn (a question
+    # asked, the checkpoint's own) keeps the turn so far on disk; #messages
+    # itself is never touched. The turn's end sets status idle before it
+    # saves, so that save writes the real messages, without a marker. Not
+    # saved; the worker clears it after each turn.
+    attr_accessor :turn_checkpoint
     # The session's own llm_context values (LLMContextOverride: strategy,
     # apply rule, budget), before the model's; nil when it has none.
     # Saved, so a --resume and a respawned worker keep them; a plugin's
@@ -191,7 +212,8 @@ module Samagotchi
                    used_memory_names: [], project_root: nil,
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
-                   continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [])
+                   continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
+                   interrupted_turn: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -220,6 +242,8 @@ module Samagotchi
       self.thinking = thinking
       self.reasoning_history = reasoning_history
       self.appended_prompt_files = appended_prompt_files
+      self.interrupted_turn = interrupted_turn
+      @turn_checkpoint = nil
       @archived = false
     end
 
@@ -363,7 +387,8 @@ module Samagotchi
       "continues" => nil,
       "thinking" => nil,
       "reasoning_history" => nil,
-      "appended_prompt_files" => []
+      "appended_prompt_files" => [],
+      "interrupted_turn" => nil
     }.freeze
 
     # A session from a parsed session file. +messages+ false leaves the
@@ -475,11 +500,15 @@ module Samagotchi
       self
     end
 
-    # The session as #save writes it (FIELDS, in their order).
+    # The session as #save writes it (FIELDS, in their order); a running
+    # turn's checkpoint (#turn_checkpoint) in place of its messages.
     def to_h
+      checkpoint = checkpointed
       FIELDS.keys.to_h do |key|
         value = case key
-                when "messages" then @messages.map { |msg| scrub_utf8(stringify_message_keys(msg)) }
+                when "messages"
+                  (checkpoint ? checkpoint[:messages] : @messages).map { |msg| scrub_utf8(stringify_message_keys(msg)) }
+                when "interrupted_turn" then (checkpoint ? checkpoint[:marker] : @interrupted_turn)&.to_file
                 when "pending_question" then @pending_question && scrub_utf8(stringify_message_keys(@pending_question))
                 when "test_run" then !!@test_run
                 when "delegate" then @delegate
@@ -496,6 +525,13 @@ module Samagotchi
       end
     end
 
+    # The running turn's checkpoint, while the turn runs (#turn_checkpoint).
+    def checkpointed
+      checkpoint = @turn_checkpoint
+      checkpoint if checkpoint && @status == STATUS_RUNNING
+    end
+    private :checkpointed
+
     # Mark a session as errored.
     def self.mark_error(session_id, reason:, state_dir: default_state_dir)
       session = load(session_id, state_dir: state_dir)