samagotchi 0.21.0 → 0.23.0

data/lib/samagotchi/model_overlay.rb

@@ -32,10 +32,7 @@ module Samagotchi
 
       key = model_name.to_s
         .downcase
-        .gsub(/[^a-z0-9]+/, "-")
-        .gsub(/-+/, "-")
-        .sub(/\A-/, "")
-        .sub(/-\z/, "")
+        .gsub(/[^a-z0-9]+/, "-").squeeze("-").delete_prefix("-").delete_suffix("-")
       key.empty? ? nil : key
     end
 
@@ -43,12 +40,13 @@ module Samagotchi
     # Respects MemoryBundle overrides (delegates to Tools::MemoryRead.memories_dir).
     def self.overlay_path_for(name, key, scope)
       return nil unless key && !key.to_s.strip.empty?
+
       File.join(Tools::MemoryRead.memories_dir(scope), "#{name}.#{key.to_s.strip}.md")
     end
 
     # Regex matching overlay file names: /<something>.<lowercase-dashed-key>.md\z
     # Useful for tooling, tests, and future index suppression.
-    OVERLAY_SUFFIX_PATTERN = /\.([a-z0-9\-]+)\.md\z/
+    OVERLAY_SUFFIX_PATTERN = /\.([a-z0-9-]+)\.md\z/
 
     # The base file name (`tips.md`) an overlay-looking name
     # (`tips.qwen3.md`) would belong to, or nil when it doesn't match the

data/lib/samagotchi/model_profile.rb

@@ -17,10 +17,13 @@ module Samagotchi
     MODEL_FROM_CLI_ENV = "SAMAGOTCHI_DEFAULT_MODEL_FROM_CLI"
     # No model anywhere (--model, default.model in config.yml, the env): a
     # first run before any config. An ArgumentError, as before.
-    MissingModel = Class.new(ArgumentError)
+    class MissingModel < ArgumentError
+    end
+
     # A host-qualified model whose host isn't configured (a MissingModel,
     # so every surface that reports a missing model reports it the same way).
-    UnknownHost = Class.new(MissingModel)
+    class UnknownHost < MissingModel
+    end
 
     # Gemma 4 thinks in a channel: `<|channel>thought` … `<channel|>`. The
     # one source for the parser, the stream splitter, the literal guard and
@@ -74,7 +77,7 @@ module Samagotchi
       new(
         name: "gemma4",
         turn_start: "<|turn>",
-        turn_end: "<end_of_turn>",
+        turn_end: "<turn|>",
         tool_call_open: "<|tool_call>",
         tool_call_close: "<tool_call|>",
         tool_response_open: "<|tool_response>",
@@ -88,7 +91,7 @@ module Samagotchi
         user_prefix: "",
         assistant_prefix: "",
         model_prefix: "",
-        stop_sequences: ["<end_of_turn>", "<|tool_response>"],
+        stop_sequences: ["<turn|>", "<|tool_response>"],
         tool_decl_format: :gemma4
       )
     end
@@ -165,14 +168,15 @@ module Samagotchi
       if !parsed.host_name && (disabled = disabled_host_prefix(ref, hosts, env))
         raise UnknownHost, "host '#{disabled}' is disabled (enabled: false in config.yml)"
       end
+
       warn_host_slash(ref, hosts) unless parsed.host_name
       host = Samagotchi::ConfigFile.unknown_host_prefix(ref, hosts: hosts)
       return model_name unless host
 
       names = hosts.keys.map { |k| k.to_s.downcase }.sort
       near = Samagotchi::Config.near_names(host, names).first(3)
-      hint = near.empty? ? "" : " (did you mean #{near.map { |n| "'#{n}'" }.join(' or ')}?)"
-      raise UnknownHost, "unknown host '#{host}' in model '#{ref}'#{hint}; the configured hosts are #{names.join(', ')}"
+      hint = near.empty? ? "" : " (did you mean #{near.map { |n| "'#{n}'" }.join(" or ")}?)"
+      raise UnknownHost, "unknown host '#{host}' in model '#{ref}'#{hint}; the configured hosts are #{names.join(", ")}"
     end
 
     # The prefix of "box:x" when box is a host config.yml has with
@@ -275,7 +279,7 @@ module Samagotchi
       FINGERPRINTS.each do |name, markers|
         return [name, markers.join(" + ")] if markers.all? { |marker| template.include?(marker) }
       end
-      return ["qwen36", "ChatML"] if template.include?("<|im_start|>")
+      return %w[qwen36 ChatML] if template.include?("<|im_start|>")
 
       nil
     end
@@ -341,7 +345,7 @@ module Samagotchi
 
     def self.configured(value, where)
       profile = named(value)
-      Log.warn(:config, "unknown_profile", echo: "Warning: unknown profile #{value.to_s.inspect} in #{where} (allowed: #{NAMES.join(', ')}) — ignored", profile: value.to_s, where: where) unless profile
+      Log.warn(:config, "unknown_profile", echo: "Warning: unknown profile #{value.to_s.inspect} in #{where} (allowed: #{NAMES.join(", ")}) — ignored", profile: value.to_s, where: where) unless profile
       profile
     end
     private_class_method :configured

data/lib/samagotchi/note_command.rb

@@ -92,6 +92,7 @@ module Samagotchi
     # passes down may never close: waiting on either would hang a script.
     def read_stdin
       return nil if @stdin.respond_to?(:tty?) && @stdin.tty?
+
       if @stdin.respond_to?(:stat)
         stat = @stdin.stat
         return nil unless stat.pipe? || stat.file?
@@ -135,7 +136,7 @@ module Samagotchi
       if owner
         @stdout.puts("#{short}  queued: its worker adds it within a few seconds")
       else
-        queued = SessionInbox.find_new_note_files(File.dirname(File.dirname(path))).size
+        queued = SessionInbox.find_new_note_files(File.dirname(path, 2)).size
         @stdout.puts("#{short}  waits for the session's next start (#{queued} #{queued == 1 ? "note" : "notes"} queued)")
       end
       true

data/lib/samagotchi/output_formatter.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module Samagotchi
   # OutputFormatter strips model wire-format tokens from raw engine output at
   # render time, so downstream renderers (web UI, terminal UI) never show the
@@ -23,7 +24,6 @@ module Samagotchi
     # wrapper forms; bare <name> content (no pipe) is deliberately preserved.
     CONTROL_NAMES = %w[
       turn
-      end_of_turn
       tool_call
       tool_response
       tool
@@ -40,31 +40,32 @@ module Samagotchi
     # <word> in the surrounding content is NOT stripped:
     #   <|name> / <name|> / <|name|>
     INDIVIDUAL_RE = Regexp.new(
-      '<\\|(?:' + CONTROL_NAMES.join('|') + ')\\|?>' \
-      '|<(?:' + CONTROL_NAMES.join('|') + ')\\|>'
+      '<\\|(?:' + CONTROL_NAMES.join("|") + ')\\|?>' \
+      "|<(?:" + CONTROL_NAMES.join("|") + ')\\|>'
     )
     INDIVIDUAL_RE.freeze
 
     # Angle-bracketed literal tokens stripped wholesale (including the thought
     # channel's trailing word). Applied before INDIVIDUAL_RE so multi-part tokens
     # are removed as a unit. Pipes are escaped; angle brackets are literal.
-    LITERALS_RE = /<\|"\|>|<end_of_turn>/.freeze
+    LITERALS_RE = /<\|"\|>/
 
     # Gemma 4's thought channel, as a whole block: `<|channel>thought` to its
     # `<channel|>` close, or to the end of the text when the close is missing
     # (ToolCallParser::Gemma strips the same pair). Removing only the marker
     # would leave the model's private reasoning in the answer; the channel is
     # the profile's thinking lane, not output.
-    GEMMA_THOUGHT_RE = /<\|\w*channel>thought.*?(?:<channel\|>|\z)/m.freeze
+    GEMMA_THOUGHT_RE = /<\|\w*channel>thought.*?(?:<channel\|>|\z)/m
 
     # Qwen prompt-literal placeholders, e.g. </think>.
-    PROMPT_LITERALS = /\[\[SAMAGOTCHI_LITERAL_[A-Z_]+\]\]/.freeze
+    PROMPT_LITERALS = /\[\[SAMAGOTCHI_LITERAL_[A-Z_]+\]\]/
 
     # Qwen3.6 thinking blocks: <think>...</think> (including empty)
-    QWEN_THINK_RE = /<think>.*?<\/think>/m.freeze
+    QWEN_THINK_RE = %r{<think>.*?</think>}m
     # Qwen tool_call XML blocks that survive when a tool call is rendered as text
     # e.g. <tool_call>\n<function=list_reminders>\n</function>\n</tool_call>
-    QWEN_TOOL_CALL_RE = /<tool_call>.*?<\/tool_call>/m.freeze
+    QWEN_TOOL_CALL_RE = %r{<tool_call>.*?</tool_call>}m
+
     module_function
 
     # Remove both control-token and prompt-literal token families from +text+.
@@ -79,7 +80,7 @@ module Samagotchi
         .gsub(/[ \t]+/, " ")
         .gsub(/ *\n */, "\n")
         .strip
-      cleaned.empty? ? '' : cleaned
+      cleaned.empty? ? "" : cleaned
     end
 
     # The same tokens as #strip, but the text keeps its layout (indentation,
@@ -91,15 +92,15 @@ module Samagotchi
 
     def remove_tokens(text)
       text.to_s
-          .gsub(QWEN_THINK_RE, '')
-          .gsub(GEMMA_THOUGHT_RE, '')
-          .gsub(QWEN_TOOL_CALL_RE, '')
-          .gsub(LITERALS_RE, '')
-          .gsub(INDIVIDUAL_RE, '')
-          .gsub(PROMPT_LITERALS, '')
+          .gsub(QWEN_THINK_RE, "")
+          .gsub(GEMMA_THOUGHT_RE, "")
+          .gsub(QWEN_TOOL_CALL_RE, "")
+          .gsub(LITERALS_RE, "")
+          .gsub(INDIVIDUAL_RE, "")
+          .gsub(PROMPT_LITERALS, "")
           # orphaned closing tags that may remain after block removal
-          .gsub(/<\/?think>/, '')
-          .gsub(/<\/?tool_call>/, '')
+          .gsub(%r{</?think>}, "")
+          .gsub(%r{</?tool_call>}, "")
     end
   end
 end

data/lib/samagotchi/owner_lock.rb

@@ -40,7 +40,8 @@ module Samagotchi
     # @return [OwnerLock, nil] nil when another owner holds it
     def self.acquire(session_dir, kind:, wait: DEFAULT_WAIT)
       FileUtils.mkdir_p(session_dir)
-      file = File.open(path(session_dir), File::RDWR | File::CREAT, 0o644)
+      # Held open on purpose: the flock lives as long as the OwnerLock (#release closes it).
+      file = File.open(path(session_dir), File::RDWR | File::CREAT, 0o644) # rubocop:disable Style/FileOpen
       deadline = monotonic_now + wait.to_f
       until file.flock(File::LOCK_EX | File::LOCK_NB)
         if monotonic_now >= deadline

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/plugin/api.rb

@@ -51,6 +51,7 @@ module Samagotchi
       #   it runs as other commands do)
       def command(name, description, anytime: false, &block)
         raise ArgumentError, "command #{name.inspect} needs a block" unless block
+
         name = name.to_s
         raise ArgumentError, "command name #{name.inspect} must look like /name (a-z, 0-9, _ and -)" unless name.match?(COMMAND_NAME)
         if (taken = @registries.commands.entries.find { |entry| entry.name == name })
@@ -78,9 +79,9 @@ 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, &block)
+      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, &block)
+                                                targets: targets, &)
         if (taken = @registries.tools[spec[:name]])
           raise ArgumentError, "tool #{spec[:name]} is already registered (#{taken.source})"
         end
@@ -124,9 +125,9 @@ module Samagotchi
         end
 
         # As Api#tool.
-        def tool(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &block)
+        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, &block)
+                                                  targets: targets, &)
           raise ArgumentError, "tool #{spec[:name]} is registered twice" if @specs.any? { |s| s[:name] == spec[:name] }
 
           @specs << spec
@@ -159,6 +160,7 @@ module Samagotchi
       # @return [Service]
       def service(name, eager: false, &block)
         raise ArgumentError, "service #{name.inspect} needs a block" unless block
+
         name = "#{@bundle}:#{name}"
         raise ArgumentError, "service #{name} is registered twice" if @services.any? { |svc| svc.name == name }
         raise ArgumentError, "this chi has no services (plugins: false)" unless @registries.services
@@ -249,6 +251,7 @@ module Samagotchi
       # @return [Hash] {name:, schema:, label:, preview:, targets:, block:}
       def self.tool_spec(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: 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)
@@ -323,7 +326,7 @@ module Samagotchi
       # (a call built without one, in a spec say: the call without its
       # name), string keys, typed by +parameters+, frozen.
       def self.args_of(call, parameters = nil)
-        given = call[:args].is_a?(Hash) ? call[:args] : call.reject { |key, _| key == :name || key == :args }
+        given = call[:args].is_a?(Hash) ? call[:args] : call.reject { |key, _| %i[name args].include?(key) }
         Tools::Args.coerce(given, parameters).freeze
       end
 

data/lib/samagotchi/plugin/context.rb

@@ -107,9 +107,7 @@ module Samagotchi
       # $XDG_STATE_HOME/samagotchi/plugins/<bundle>/, created on first use.
       # @return [String]
       def data_dir
-        @data_dir ||= begin
-          File.join(Paths.state_dir(env: @env), "plugins", @bundle).tap { |dir| FileUtils.mkdir_p(dir) }
-        end
+        @data_dir ||= File.join(Paths.state_dir(env: @env), "plugins", @bundle).tap { |dir| FileUtils.mkdir_p(dir) }
       end
 
       # The conversation so far, a frozen copy, without the system prompt.

data/lib/samagotchi/plugin/loader.rb

@@ -73,7 +73,7 @@ module Samagotchi
         true
       rescue Exception => e # rubocop:disable Lint/RescueException -- a plugin's SyntaxError or exit must not stop chi
         api&.abort!
-        raise if e.is_a?(Interrupt)
+        raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
 
         failed(bundle_name, basename, "#{e.class}: #{e.message}", failures)
       end

data/lib/samagotchi/plugin/service.rb

@@ -62,7 +62,7 @@ module Samagotchi
       def running? = @state == :running
 
       # @return [Symbol] :idle, :running or :stopped
-      def state = @state
+      attr_reader :state
 
       # Run the stop callbacks (newest first) once; a raise is logged, the
       # rest still run. It never starts again after this.

data/lib/samagotchi/plugin/sessions.rb

@@ -38,6 +38,7 @@ module Samagotchi
       def fork(messages:, title: nil, prompt: nil)
         parent_id = @host.session_id.call or raise Error, "this session has no id yet"
         raise Error, "a scratch session starts no other sessions: they would outlive it" if @host.scratch&.call
+
         state_dir = self.state_dir
         prompt = prompt.to_s.strip.empty? ? nil : prompt.to_s
         check_children(parent_id, state_dir) if prompt

data/lib/samagotchi/plugin_tasks.rb

@@ -121,7 +121,7 @@ module Samagotchi
         sleep(INIT_WAIT_POLL)
       end
       Log.info(:plugins, "init_wait", ms: ((@clock.call - started) * 1000).round,
-                                      cancelled: controller&.cancelled? ? true : nil)
+                                      cancelled: controller&.cancelled? || nil)
       true
     end
 

data/lib/samagotchi/prompt.rb

@@ -3,6 +3,7 @@
 require_relative "model_profile"
 require_relative "prompt_literal_guard"
 require_relative "vision_context"
+require_relative "tool_response"
 
 module Samagotchi
   # Formats a message list into a prompt string ready for the /completion endpoint.
@@ -10,10 +11,13 @@ module Samagotchi
   # Supports multiple model profiles (Gemma 4, Qwen 3.6, etc.) with different
   # token formats, role prefixing strategies, and tool response handling.
   #
-  # Gemma 4:
-  #   - Turn markers: <|turn>ROLE\n...<end_of_turn>\n
-  #   - Tool response: standalone <|tool_response>...<tool_response|>
-  #   - Generation cue: <|turn>model\n
+  # Gemma 4 (as its chat template renders a conversation):
+  #   - Turn markers: <|turn>ROLE\n...<turn|>\n, the text trimmed
+  #   - Tool calls and their responses stay inside the model's turn:
+  #     ...<tool_call|><|tool_response>response:NAME{value:<|"|>...<|"|>}<tool_response|>
+  #     and the model goes on in the same turn
+  #   - Generation cue: <|turn>model\n, or nothing after a tool response
+  #   - An answer's thought is dropped once a later user turn starts
   #
   # Qwen 3.6:
   #   - Role framing: <|im_start|>ROLE\n...<|im_end|>
@@ -51,11 +55,9 @@ module Samagotchi
              else
                format_with_turn_markers(messages, profile, suffixes)
              end
-      [text + prefill.to_s, images]
+      [text + prefill_for(messages, profile, prefill), images]
     end
 
-    private
-
     def self.image_lines(items, profile, images)
       return "" if items.empty?
 
@@ -71,19 +73,70 @@ module Samagotchi
     end
 
     def self.format_with_turn_markers(messages, profile, suffixes)
-      # Gemma 4 style: <|turn>ROLE\n...<end_of_turn>\n
+      last_user = messages.rindex { |m| m[:role] == "user" } || -1
       parts = messages.each_with_index.map do |m, index|
         content = prompt_content_for(m, profile) + suffixes[index]
-        if m[:role] == "tool_response"
-          "#{profile.tool_response_open}\n#{content}#{profile.tool_response_close}\n"
+        previous = index.positive? ? messages[index - 1][:role] : nil
+        following = messages[index + 1]&.dig(:role)
+        case m[:role]
+        when "tool_response"
+          # Inside the model's turn; closed when another role follows.
+          tool_response_blocks(content, profile) +
+            (following && following != "tool_response" && following != "model" ? "#{profile.turn_end}\n" : "")
+        when "model"
+          content = strip_gemma_thought(content) if index < last_user && !content.include?(profile.tool_call_open)
+          opener = previous == "tool_response" ? "" : "#{profile.turn_start}model\n"
+          closer = following == "tool_response" ? "" : "#{profile.turn_end}\n"
+          "#{opener}#{content.strip}#{closer}"
         else
-          "#{profile.turn_start}#{m[:role]}\n#{content}#{profile.turn_end}\n"
+          "#{profile.turn_start}#{m[:role]}\n#{content.strip}#{profile.turn_end}\n"
         end
       end
-      parts << "#{profile.turn_start}model\n"
+      parts << "#{profile.turn_start}model\n" unless ends_in_tool_response?(messages)
       parts.join
     end
 
+    def self.ends_in_tool_response?(messages)
+      messages.last&.dig(:role) == "tool_response"
+    end
+
+    # The text after the generation cue: +prefill+, except where Gemma's
+    # turn goes on after a tool response (no cue, so nothing to fill).
+    # The prompt and the model message the kernel keeps both use it.
+    def self.prefill_for(messages, profile, prefill)
+      return "" if !profile.uses_role_prefixes? && ends_in_tool_response?(messages)
+
+      prefill.to_s
+    end
+
+    # A native tool_response entry (ToolResponse.joined: "[name]" outputs
+    # joined by its SEPARATOR) as Gemma's template writes the results: one
+    # response:NAME{value:<|"|>…<|"|>} block per call. A part that doesn't
+    # open with a "[name]" is the previous output's own text.
+    def self.tool_response_blocks(content, profile)
+      runs = content.split(ToolResponse::SEPARATOR).each_with_object([]) do |part, acc|
+        if (match = part.match(/\A\[([^\]\s]+)\](?:\n| |\z)/))
+          acc << [match[1], match.post_match]
+        elsif acc.empty?
+          acc << ["unknown", part]
+        else
+          acc.last[1] = "#{acc.last[1]}#{ToolResponse::SEPARATOR}#{part}"
+        end
+      end
+      runs = [["unknown", ""]] if runs.empty?
+      q = profile.string_delim
+      runs.map do |name, body|
+        "#{profile.tool_response_open}response:#{name}{value:#{q}#{body}#{q}}#{profile.tool_response_close}"
+      end.join
+    end
+
+    GEMMA_THOUGHT_BLOCK = /#{Regexp.escape(ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN.delete_suffix("thought"))}.*?#{Regexp.escape(ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE)}/m
+    private_constant :GEMMA_THOUGHT_BLOCK
+
+    def self.strip_gemma_thought(content)
+      content.gsub(GEMMA_THOUGHT_BLOCK, "")
+    end
+
     def self.format_with_prefixes(messages, profile, suffixes)
       # Qwen 3.6 style: <|im_start|>ROLE\n...<|im_end|>
       parts = []
@@ -117,5 +170,8 @@ module Samagotchi
       role = ESCAPED_KINDS.include?(message[:kind].to_s) ? "user" : message[:role]
       PromptLiteralGuard.escape(message[:content], profile: profile, role: role)
     end
+
+    private_class_method :image_lines, :format_with_turn_markers, :ends_in_tool_response?, :tool_response_blocks,
+                         :strip_gemma_thought, :format_with_prefixes, :prompt_content_for
   end
 end

data/lib/samagotchi/prompt_literal_guard.rb

@@ -8,7 +8,7 @@ module Samagotchi
   module PromptLiteralGuard
     GEMMA_TOKEN_PAIRS = [
       ["[[SAMAGOTCHI_LITERAL_TURN_START]]", "<|turn>"],
-      ["[[SAMAGOTCHI_LITERAL_TURN_END]]", "<end_of_turn>"],
+      ["[[SAMAGOTCHI_LITERAL_TURN_END]]", "<turn|>"],
       ["[[SAMAGOTCHI_LITERAL_TOOL_CALL_OPEN]]", "<|tool_call>"],
       ["[[SAMAGOTCHI_LITERAL_TOOL_CALL_CLOSE]]", "<tool_call|>"],
       ["[[SAMAGOTCHI_LITERAL_TOOL_RESPONSE_OPEN]]", "<|tool_response>"],

data/lib/samagotchi/question_desk.rb

@@ -101,8 +101,8 @@ module Samagotchi
     # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
     # @return [String] normalized answer JSON
     def request(payload)
-      result = open_question({ **payload.slice(:question, :options, :header),
-                               multi_select: !!payload[:multi_select], allow_freeform: !!payload[:allow_freeform] })
+      result = open_question(payload.slice(:question, :options, :header)
+                                    .merge(multi_select: !!payload[:multi_select], allow_freeform: !!payload[:allow_freeform]))
       # Dismissed (the card's dismiss, Esc): an answer of its own, not a
       # tool failure the model learns to avoid the tool from.
       result = { dismissed: true, id: result[:id], note: DISMISSED_NOTE } if result.is_a?(Hash) && result[:error] == "no answer"
@@ -288,6 +288,7 @@ module Samagotchi
         if parent_agent && (reason = Guardrails::ParentContinue.refusal(pending, sel, allowed: parent_continue))
           raise Refused, reason
         end
+
         if @standing
           # No waiter: cleared here, so a second answer finds none.
           standing = @standing
@@ -332,9 +333,7 @@ module Samagotchi
       true
     end
 
-    def sync_handler=(block)
-      @sync_handler = block
-    end
+    attr_writer :sync_handler
 
     # @return [Boolean] a REPL answers inline (no wait loop)
     def sync_handler? = !@sync_handler.nil?
@@ -355,7 +354,7 @@ module Samagotchi
         next if id && pending[:id].to_s != id.to_s
         next if @answer || pending[:status].to_s != "pending"
         # Its poster closes it; nothing waits on a cancel.
-        raise NotDismissable, "answer #{Array(pending[:options]).join(' or ')}" if @standing && id
+        raise NotDismissable, "answer #{Array(pending[:options]).join(" or ")}" if @standing && id
         next if @standing
 
         pending[:status] = "cancelled"
@@ -455,7 +454,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
@@ -469,14 +468,9 @@ module Samagotchi
     def validated_answer(pending, sel, fm, parent_agent:, parent_setting:)
       opts = Array(pending[:options])
       invalid = sel.reject { |v| opts.include?(v) }
-      raise ArgumentError, "invalid selection: #{invalid.join(', ')} (valid: #{opts.join(', ')})" unless invalid.empty?
+      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).

data/lib/samagotchi/recap_setup.rb

@@ -114,7 +114,7 @@ module Samagotchi
       return range if range
 
       default = IdleRecap::RecapPrompt::DEFAULT_SENTENCES
-      Log.warn(:recap, "sentences_invalid", echo: "Warning: invalid value for recap.sentences: #{value.to_s.inspect} — using #{default.join('-')}",
+      Log.warn(:recap, "sentences_invalid", echo: "Warning: invalid value for recap.sentences: #{value.to_s.inspect} — using #{default.join("-")}",
                                             value: value.to_s)
       default
     end

data/lib/samagotchi/relay_desk.rb

@@ -35,7 +35,7 @@ module Samagotchi
     # The parent's user (or a parent agent) answered the relay card.
     # @param by [String] "user" or "parent_agent"
     # @return [Boolean] false when the relay isn't open (first answer wins)
-    def record(id, selected_indices: [], freeform: nil, dismissed: false, by:)
+    def record(id, by:, selected_indices: [], freeform: nil, dismissed: false)
       @mutex.synchronize do
         relay = @relays[id.to_s]
         next false unless relay && relay[:state] == "open"

data/lib/samagotchi/reminder_store.rb

@@ -81,7 +81,7 @@ module Samagotchi
       @mutex.synchronize do
         return "No active reminders." if @reminders.empty?
 
-        lines = @reminders.map do |name, r|
+        lines = @reminders.map do |_name, r|
           "  #{r[:name]} (interval: #{r[:interval_minutes]}m, id: #{r[:id]})"
         end
         "Active reminders:\n" + lines.join("\n")
@@ -98,6 +98,7 @@ module Samagotchi
       @mutex.synchronize do
         @reminders.each_value.filter_map do |r|
           next unless r[:next_fire_at] && now >= r[:next_fire_at]
+
           { name: r[:name], description: r[:description], interval_minutes: r[:interval_minutes] }
         end.freeze
       end

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