samagotchi 0.40.0 → 0.42.0

data/lib/samagotchi/llm_context_strategy.rb

@@ -7,8 +7,8 @@ module Samagotchi
   # llm_context_strategy (models.<key>, hosts.<name>), each a layer name,
   # "|"-separated names or a YAML list.
   #
-  # Resolution, first set wins: the session's own (a later per-session
-  # override; nothing sets it yet), models.<key> (by the model's lookup
+  # Resolution, first set wins: the session's own (Session#llm_context,
+  # set by chi --llm-context, /llm-context and the web), models.<key> (by the model's lookup
   # names, as window_tokens), hosts.<name>, then llm_context.strategy.
   # An unknown layer warns and is none (every layer is built: stale, and
   # forget, experimental, with its tool forget_outputs).
@@ -118,29 +118,71 @@ module Samagotchi
       nil
     end
 
+    # Where one value came from: :session, :model_setting, :host_setting
+    # or :config, and the place as a warning names it ("the session",
+    # "models: deepseek", "hosts entry 'box'", "llm_context.apply").
+    Origin = Data.define(:source, :where)
+    SESSION_ORIGIN = Origin.new(source: :session, where: "the session")
+
+    # What a turn's strategy, apply rule and budget are, each with its
+    # Origin (/llm-context, /stats, the web's info bar).
+    Explained = Data.define(:resolved, :strategy, :apply, :budget_tokens) do
+      # The plain form /stats, the snapshot and the web read: each value
+      # with its source and place, and +own+, the session's own values
+      # (LLMContextOverride#to_file; nil without any).
+      # @return [Hash] symbol keys
+      def summary(own = nil)
+        layers = resolved.active_layers
+        { strategy: layers.empty? ? NONE.to_s : layers.join(","), strategy_source: strategy.source.to_s,
+          strategy_where: strategy.where, apply: resolved.apply.to_s, apply_source: apply.source.to_s,
+          apply_where: apply.where, budget_tokens: resolved.budget_tokens, budget_source: budget_tokens.source.to_s,
+          budget_where: budget_tokens.where, own: own&.to_file }
+      end
+    end
+
     # The strategy for +target+'s turn.
     # @param target [HostRegistry::ModelTarget, nil]
     # @param names [Array<String>] HostRegistry#lookup_names
     # @param models [Hash, nil] ConfigFile.model_settings (specs)
-    # @param session [Array<Symbol>, nil] the session's own layers (none yet)
-    # @param session_apply [Symbol, nil] the session's own apply rule (none yet)
-    # @param session_budget [Integer, nil] the session's own budget (none yet)
+    # @param session [Array<Symbol>, nil] the session's own layers ([]: none)
+    # @param session_apply [Symbol, nil] the session's own apply rule
+    # @param session_budget [Integer, nil] the session's own budget (0: off)
     # @return [Resolved]
     def resolve(target, names:, models: nil, session: nil, session_apply: nil, session_budget: nil)
+      explain(target, names: names, models: models, session: session, session_apply: session_apply,
+                      session_budget: session_budget).resolved
+    end
+
+    # #resolve, with where each value came from.
+    # @return [Explained]
+    def explain(target, names:, models: nil, session: nil, session_apply: nil, session_budget: nil)
       models ||= ConfigFile.model_settings
       layers, source, where = layers_for(target, names, models, session)
-      resolved(layers, source, where).with(apply: apply_for(target, names, models, session_apply),
-                                           protect_steps: protect_steps, stale_edits: Config.get(STALE_EDITS_SETTING) == true,
-                                           budget_tokens: budget_for(target, names, models, session_budget))
+      apply, apply_origin = apply_for(target, names, models, session_apply)
+      budget, budget_origin = budget_for(target, names, models, session_budget)
+      resolved = resolved(layers, source, where).with(apply: apply, protect_steps: protect_steps,
+                                                      stale_edits: Config.get(STALE_EDITS_SETTING) == true,
+                                                      budget_tokens: budget)
+      Explained.new(resolved: resolved, strategy: Origin.new(source: source, where: where), apply: apply_origin,
+                    budget_tokens: budget_origin)
     end
 
+    # [the budget, its Origin]: the session's own first (0 there is off,
+    # whatever the model says).
     def budget_for(target, names, models, session_budget)
-      session_budget || ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models)&.last ||
-        target&.entry&.llm_context_budget_tokens || parse_budget(Config.get(BUDGET_SETTING), BUDGET_SETTING)
+      return [session_budget.positive? ? session_budget : nil, SESSION_ORIGIN] unless session_budget.nil?
+
+      key, budget = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models)
+      return [budget, Origin.new(source: :model_setting, where: "models: #{key}")] if budget
+
+      budget = target&.entry&.llm_context_budget_tokens
+      return [budget, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if budget
+
+      [parse_budget(Config.get(BUDGET_SETTING), BUDGET_SETTING), Origin.new(source: :config, where: BUDGET_SETTING)]
     end
 
     def layers_for(target, names, models, session)
-      return [session, :session, "the session"] if session
+      return [session, :session, SESSION_ORIGIN.where] if session
 
       key, layers = ConfigFile.model_setting(names, :llm_context_strategy, models: models)
       return [layers, :model_setting, "models: #{key}"] if layers
@@ -151,9 +193,17 @@ module Samagotchi
       [parse(Config.get(SETTING), SETTING) || [], :config, SETTING]
     end
 
+    # [the apply rule, its Origin].
     def apply_for(target, names, models, session_apply)
-      session_apply || ConfigFile.model_setting(names, :llm_context_apply, models: models)&.last ||
-        target&.entry&.llm_context_apply || parse_apply(Config.get(APPLY_SETTING), APPLY_SETTING) || DEFAULT_APPLY
+      return [session_apply, SESSION_ORIGIN] if session_apply
+
+      key, apply = ConfigFile.model_setting(names, :llm_context_apply, models: models)
+      return [apply, Origin.new(source: :model_setting, where: "models: #{key}")] if apply
+
+      apply = target&.entry&.llm_context_apply
+      return [apply, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if apply
+
+      [parse_apply(Config.get(APPLY_SETTING), APPLY_SETTING) || DEFAULT_APPLY, Origin.new(source: :config, where: APPLY_SETTING)]
     end
 
     # llm_context.protect_steps: 0 or more (a negative one is the default).

data/lib/samagotchi/memory_bundle/index_size.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../tools/memory"
+require_relative "../model_notes"
+
+module Samagotchi
+  module MemoryBundle
+    # The size of one scope's memory index as a prompt carries it: every
+    # session's system prompt holds both indexes in full, so their size is
+    # paid on every request. tokens is the estimate ContextStatus uses
+    # (characters / context.chars_per_token, rounded up), lines the
+    # non-blank lines, bytes the UTF-8 size.
+    #
+    # memory_write and write/edit on a memory compare the size before and
+    # after a write against memory.index_warn_tokens (#crossing_note);
+    # chi self shows it (#summary), and a session's figure comes from the
+    # index text its prompt holds (SystemPrompt).
+    IndexSize = Data.define(:scope, :bytes, :lines, :tokens) do
+      # @param text [String, nil] the index text
+      # @param chars_per_token [Float]
+      # @return [IndexSize]
+      def self.of_text(scope, text, chars_per_token: self.chars_per_token)
+        text = text.to_s
+        new(scope: scope.to_s, bytes: text.bytesize, lines: text.each_line.count { |line| !line.strip.empty? },
+            tokens: (text.length / chars_per_token).ceil)
+      end
+
+      # +scope+'s index as the prompt carries it before a session's own
+      # filters (mutes): index.md, or the file listing without one, minus
+      # the model notes' lines (ModelNotes.filter_index).
+      # @param env [Hash] the XDG env the memories dir resolves from
+      # @return [IndexSize]
+      def self.of_scope(scope, chars_per_token: self.chars_per_token, env: ENV)
+        text = Tools::MemoryRead.scoped_index(scope, env: env)
+        of_text(scope, ModelNotes.filter_index(text, scope, env: env), chars_per_token: chars_per_token)
+      end
+
+      # of_scope, or nil when the index can't be read (a write's measure
+      # must never fail the write).
+      def self.measure(scope)
+        of_scope(scope)
+      rescue StandardError
+        nil
+      end
+
+      # context.chars_per_token, 4.0 when it isn't positive.
+      def self.chars_per_token
+        value = Config.get("context.chars_per_token").to_f
+        value.positive? ? value : 4.0
+      rescue StandardError
+        4.0
+      end
+
+      # memory.index_warn_tokens: the tokens one scope's index may hold
+      # before a write that crosses it gets a note; 0 turns the note off.
+      def self.warn_limit
+        Config.get("memory.index_warn_tokens").to_i
+      rescue StandardError
+        0
+      end
+
+      # The note a write gets when it took the index from at or under
+      # +limit+ to over it, nil otherwise: once per crossing, so a write
+      # while the index is already over gets none and the note doesn't
+      # start a loop of small tightenings. Sessions sharing the dir measure
+      # on their own (before and after aren't one locked step), so writes
+      # in parallel sessions racing over the limit may each get it.
+      # @param before [IndexSize, nil]
+      # @param after [IndexSize, nil]
+      # @return [String, nil]
+      def self.crossing_note(before, after, limit = warn_limit)
+        return nil unless before && after && after.over?(limit) && !before.over?(limit)
+
+        "Note: the #{after.scope} memory index is now ~#{after.tokens} tokens (over memory.index_warn_tokens " \
+          "#{limit}) and is sent with every prompt. When you next have a moment, tighten long index " \
+          "descriptions (memory_write with name, scope and description only). Don't remove or merge memories " \
+          "unless the user asks."
+      end
+
+      # "450", "2.0k": a token count as the size readouts show it (the
+      # web's ctx.js memoryIndexText too; spec/shared/labels_matrix.json).
+      def self.count_text(tokens)
+        value = tokens.to_i
+        value >= 1000 ? "#{format("%.1f", (value / 100.0).round / 10.0)}k" : value.to_s
+      end
+
+      # Whether the index holds more than +limit+ tokens; a limit that
+      # isn't positive is off.
+      def over?(limit) = limit.to_i.positive? && tokens > limit.to_i
+
+      # "system ~2.0k tokens (54 lines)", with ", over 2500" in the
+      # parentheses when over +limit+: chi self's row.
+      def summary(limit = 0)
+        over = over?(limit) ? ", over #{limit}" : ""
+        "#{scope} ~#{self.class.count_text(tokens)} tokens (#{lines} #{lines == 1 ? "line" : "lines"}#{over})"
+      end
+
+      # { tokens:, lines: }: the session's block (SessionMetrics).
+      def figures = { tokens: tokens, lines: lines }
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/index_sync.rb

@@ -38,7 +38,7 @@ module Samagotchi
       end
 
       # "project" or "system" when +path+ is a memory's file (or an
-      # overlay's): a *.md right in that scope's memories dir, not index.md,
+      # overlay's): a *.md right in that scope's memories dir, not index.md (in any case),
       # not hidden, not a symlink. nil otherwise. The guardrails' outside_repo
       # uses it too: write/edit there is what memory_write does. A symlink
       # isn't: write/edit follow it to wherever it points, memory_write
@@ -47,7 +47,8 @@ module Samagotchi
         path = File.expand_path(path.to_s)
         name = File.basename(path, ".md")
         return nil unless File.extname(path) == ".md"
-        return nil if name == IndexUpdater::MEMORY_INDEX || name.start_with?(".") || File.symlink?(path)
+        # Any case: on a case-insensitive disk INDEX.md is the index itself.
+        return nil if name.casecmp?(IndexUpdater::MEMORY_INDEX) || name.start_with?(".") || File.symlink?(path)
 
         dir = real(File.dirname(path))
         SCOPES.find { |s| real(Tools::MemoryRead.memories_dir(s)) == dir }

data/lib/samagotchi/model_match.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Which models a `models:` list is for, in one grammar shared by the
+  # guardrails rules' `models:`, `guardrails.small_models` and the model
+  # notes' first line: entries `|`-separated (or a list), each `small` (the
+  # caller says whether the model is a small one) or an fnmatch glob
+  # (case-insensitive, extglob) on the bare model name or the model key
+  # (ModelOverlay.key_for). Any entry matching wins; no model matches
+  # nothing.
+  module ModelMatch
+    GLOB_FLAGS = File::FNM_CASEFOLD | File::FNM_EXTGLOB
+    SMALL = "small"
+    # A model note's first line (ModelNotes): `models: …`, any case, after
+    # an optional UTF-8 BOM.
+    MODELS_LINE = /\A\uFEFF?\s*models:(.*)\z/i
+
+    module_function
+
+    # The entries of a `models:` value: a string, or a list of them, each
+    # split on `|`, stripped, blanks dropped.
+    # @param value [String, Array<String>, nil]
+    # @return [Array<String>]
+    def parse(value)
+      Array(value).flat_map { |entry| entry.to_s.split("|") }.map(&:strip).reject(&:empty?)
+    end
+
+    # The entries of +text+'s first line when it is a `models:` line with
+    # at least one; nil otherwise.
+    # @return [Array<String>, nil]
+    def models_line(text)
+      first = text.to_s.each_line.first.to_s.chomp
+      match = first.match(MODELS_LINE)
+      entries = match && parse(match[1])
+      entries unless entries.nil? || entries.empty?
+    end
+
+    # @param entries [Array<String>] parsed entries (#parse)
+    # @param name [String, nil] the bare model name
+    # @param key [String, nil] its model key
+    # @param small [#call] → whether the model is a small one; called only
+    #   for a `small` entry
+    def match?(entries, name:, key:, small:)
+      return false if name.nil? || name.to_s.empty?
+
+      entries.any? { |entry| entry == SMALL ? small.call : glob?(entry, name: name, key: key) }
+    end
+
+    # Whether the glob +entry+ matches the name or the key.
+    def glob?(entry, name:, key:)
+      [name, key].compact.any? { |candidate| File.fnmatch(entry, candidate.to_s, GLOB_FLAGS) }
+    end
+  end
+end

data/lib/samagotchi/model_notes.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "log"
+require_relative "model_match"
+require_relative "model_overlay"
+require_relative "memory_paths"
+require_relative "muted_memories"
+require_relative "tools/memory"
+require_relative "guardrails/model_size"
+
+module Samagotchi
+  # Model notes: memories named `model_notes_<name>` whose first line says
+  # which models they are for, in ModelMatch's grammar:
+  #
+  #   models: deepseek-*|*deepseek-v4*
+  #   Working habits for this model: ...
+  #
+  # Every note matching the session's model is loaded into the system
+  # prompt (SystemPrompt#model_notes_section, after identity), stacked: the
+  # system scope's, then the project's, by name within a scope. Notes add
+  # habits; none overrides another. The body is read through memory_read,
+  # so a note's own model overlays are appended as for any memory; the
+  # models: line is left out. Their index lines are left out of the
+  # prompt's indexes (#filter_index): the body is already there.
+  module ModelNotes
+    PREFIX = Tools::MODEL_NOTES_PREFIX
+    SCOPES = %w[system project].freeze
+    # A note over this, or all of them over TOTAL_LIMIT, still loads but
+    # warns once: they cost every request.
+    NOTE_LIMIT = 1_500
+    TOTAL_LIMIT = 3_000
+
+    # name: the memory name; scope: "system" or "project"; body: what the
+    # prompt carries (overlays appended, the models: line dropped); chars:
+    # its length; digest: a short SHA-256 of it.
+    Note = Data.define(:name, :scope, :body, :chars, :digest)
+
+    @warned = Set.new
+    @warn_mutex = Mutex.new
+
+    module_function
+
+    # The notes for a model.
+    # @param name [String, nil] the bare model id (no host prefix)
+    # @param key [String, nil] its model key (ModelOverlay.key_for)
+    # @param fallback_key [String, nil] the overlay key read when +key+ has
+    #   none (SystemPrompt::ModelIdentity#fallback_key)
+    # @param muted [Array<String>] the session's muted names (MutedMemories)
+    # @param small [#call, nil] → whether the model is a small one; nil:
+    #   guardrails.small_models (Guardrails::ModelSize)
+    # @param env [Hash] the XDG env the memories dirs resolve from
+    # @param warn [Boolean] false: no size warnings (a read-only report such
+    #   as chi self; the prompt's build gives them)
+    # @return [Array<Note>]
+    def for(name:, key:, fallback_key: nil, muted: [], small: nil, env: ENV, warn: true)
+      return [] if name.nil? || name.to_s.strip.empty?
+
+      small ||= -> { Guardrails::ModelSize.small?(name, key) }
+      small_once = memo(small)
+      seen = Set.new
+      notes = SCOPES.flat_map do |scope|
+        files(scope, env).filter_map do |path|
+          next unless seen.add?(File.expand_path(path))
+
+          note_at(path, scope, name: name, key: key, fallback_key: fallback_key, muted: muted, small: small_once)
+        end
+      end
+      warn_sizes(notes) if warn
+      notes
+    end
+
+    # +text+ (+scope+'s memory index) without the lines naming a model note
+    # that loads for some model (its file in +scope+ has a `models:` line);
+    # the same object when it names none. A `model_notes_*` memory that
+    # isn't one keeps its line, so it doesn't vanish. +env+: the XDG env
+    # the scope's dir resolves from.
+    def filter_index(text, scope, env: ENV)
+      return text if text.nil? || !text.include?(PREFIX)
+
+      dir = MemoryPaths.scope_dir(scope, env: env)
+      names = files_in(dir).map { |path| File.basename(path) }
+      text.each_line.reject do |line|
+        name = MutedMemories.index_line_name(line).to_s
+        name.start_with?(PREFIX) && !name.include?(".") && names.include?("#{name}.md") &&
+          note_file?(File.join(dir, "#{name}.md"))
+      end.join
+    end
+
+    # Whether +path+ is a model note's file: it has a models: first line.
+    def note_file?(path)
+      File.file?(path) && !ModelMatch.models_line(File.open(path, encoding: "UTF-8", &:gets)).nil?
+    rescue StandardError
+      false
+    end
+
+    # Forgets which warnings were given (specs).
+    def reset_warnings!
+      @warn_mutex.synchronize { @warned.clear }
+    end
+
+    def files(scope, env = ENV) = files_in(MemoryPaths.scope_dir(scope, env: env))
+
+    # The `model_notes_*.md` files in +dir+, by their names on disk: the
+    # prefix exactly as written (a case-insensitive disk's glob matches
+    # MODEL_NOTES_x.md too, which the guardrails would not see as a note).
+    def files_in(dir)
+      Dir.glob(File.join(dir, "#{PREFIX}*.md")).select { |path| File.basename(path).start_with?(PREFIX) }.sort
+    rescue StandardError
+      []
+    end
+
+    def note_at(path, scope, name:, key:, fallback_key:, muted:, small:)
+      stem = File.basename(path, ".md")
+      return nil if dotted?(path, stem)
+      return nil if MutedMemories.muted?(stem, muted)
+
+      entries = models_of(path)
+      return nil unless entries
+      return nil unless ModelMatch.match?(entries, name: name, key: key, small: small)
+
+      body = File.read(path, encoding: "UTF-8").sub(/\A[^\n]*\n?/, "").strip
+      return nil if body.empty?
+
+      body = with_overlay(body, stem, scope, [key, fallback_key])
+
+      Note.new(name: stem, scope: scope, body: body, chars: body.length, digest: Digest::SHA256.hexdigest(body)[0, 12])
+    rescue StandardError
+      nil
+    end
+
+    # The note's model overlay appended as memory_read appends one: the
+    # key's, else the fallback key's. The file is read by its own path, not
+    # by name through memory_read (whose names are comma lists).
+    def with_overlay(body, stem, scope, keys)
+      keys.compact.each do |overlay_key|
+        overlay = ModelOverlay.overlay_path_for(stem, overlay_key, scope)
+        next unless overlay && File.file?(overlay)
+
+        return "#{body}#{Tools::MemoryRead::SEPARATOR}Model-specific guidance (#{overlay_key}):\n" \
+               "#{File.read(overlay, encoding: "UTF-8").strip}"
+      end
+      body
+    end
+
+    # A model overlay of a note (`model_notes_a.<key>.md`) is read with
+    # its note; any other dotted name is skipped with a warning (memory_write
+    # refuses it: next to a base it would read as an overlay).
+    def dotted?(path, stem)
+      return false unless stem.include?(".")
+
+      unless ModelOverlay.overlay_file?(path)
+        warn_once("model_note_skipped", "Warning: model note #{path} skipped: a model note's name has no dot " \
+                                        "(rename it, e.g. #{Tools::MemoryWrite.undotted(stem)}.md)", path)
+      end
+      true
+    end
+
+    # The entries of the file's `models:` first line; nil (warned once)
+    # without one.
+    def models_of(path)
+      entries = ModelMatch.models_line(File.open(path, encoding: "UTF-8", &:gets))
+      return entries if entries
+
+      warn_once("model_note_skipped", "Warning: model note #{path} skipped: its first line must be " \
+                                      "`models: <glob>|small|…`", path)
+      nil
+    end
+
+    def warn_sizes(notes)
+      notes.each do |note|
+        next unless note.chars > NOTE_LIMIT
+
+        warn_once("model_notes_large", "Warning: model note #{note.name} (#{note.scope}) is #{note.chars} chars, over " \
+                                       "#{NOTE_LIMIT}: it is sent with every request", note.name)
+      end
+      total = notes.sum(&:chars)
+      return unless total > TOTAL_LIMIT
+
+      warn_once("model_notes_large", "Warning: the model notes for this model are #{total} chars, over #{TOTAL_LIMIT}: " \
+                                     "they are sent with every request", notes.map(&:name).join(","))
+    end
+
+    # Once per message for the process (a prompt is built again on a
+    # model switch, another thinking level, changed tools).
+    def warn_once(event, echo, memory)
+      first = @warn_mutex.synchronize { @warned.add?(echo) }
+      Log.warn(:memory, event, echo: echo, memory: memory) if first
+    end
+
+    def memo(callable)
+      value = nil
+      known = false
+      lambda do
+        unless known
+          value = callable.call
+          known = true
+        end
+        value
+      end
+    end
+
+    private_class_method :note_file?, :files, :files_in, :note_at, :with_overlay, :dotted?, :models_of, :warn_sizes, :warn_once, :memo
+  end
+end

data/lib/samagotchi/parent_report.rb

@@ -94,7 +94,7 @@ module Samagotchi
     # @return [Hash]
     def stop_facts(result)
       case status(result)
-      when "failed" then { error_kind: result.error_kind, retryable: result.retryable }.compact
+      when "failed" then { error_kind: result.error_kind, retryable: result.retryable, kept_steps: result.kept_steps }.compact
       when "canceled" then { cancel_reason: result.cancel_reason, stopped_by: result.stopped_by }.compact
       else {}
       end
@@ -242,7 +242,7 @@ module Samagotchi
 
     def no_reply_line(result, session_id = nil)
       case result.outcome
-      when "failed" then result.text.to_s.strip.empty? ? "the turn failed" : "the turn failed: #{result.text.strip}"
+      when "failed" then failed_line(result)
       when "canceled" then "the turn was canceled"
       when "completed" then "the turn ended with no visible answer"
       when "not_continued" then "the turn was not continued (Stop); its work so far stays"
@@ -253,6 +253,16 @@ module Samagotchi
       end
     end
 
+    # A failed turn's line; one whose work stayed says so, so the task isn't
+    # sent again over what it changed.
+    def failed_line(result)
+      why = result.text.to_s.strip
+      steps = result.kept_steps
+      return why.empty? ? "the turn failed" : "the turn failed: #{why}" unless steps.is_a?(Integer)
+
+      "the turn failed after #{steps} tool step#{"s" if steps != 1}#{": #{why}" unless why.empty?}; its work so far stays"
+    end
+
     def first_line(text)
       text.to_s.strip.lines.first.to_s.strip
     end

data/lib/samagotchi/plugin/context.rb

@@ -20,12 +20,13 @@ module Samagotchi
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +model_name+ (the session's resolved model ref, live after /model) and
-    # +state_dir+ are what ctx.sessions forks with; +model_key+ is the
+    # +state_dir+ are what ctx.sessions forks with, and +llm_context+ (the
+    # session's own LLMContextOverride, nil without one), which a fork copies; +model_key+ is the
     # model's memory overlay key (ctx.model, ctx.model_key).
     # +steer+ takes (text, label), +stop_turn+ and +stop_generation+
     # (reason, label), each true when it acted on a running turn.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
-                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :steer, :stop_turn, :stop_generation,
+                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :llm_context, :steer, :stop_turn, :stop_generation,
                       keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or

data/lib/samagotchi/plugin/sessions.rb

@@ -32,6 +32,7 @@ module Samagotchi
       # Start a child session from +messages+ (usually ctx.messages plus
       # more). With no prompt the child waits idle for the user; with one it
       # runs it as its first turn, and counts against session.max_children.
+      # It keeps this session's own llm_context values (Session#llm_context).
       # Each image a message names is copied into the child, or dropped with
       # a note in its message when its file is gone.
       # @param messages [Array<Hash>] the child's conversation to start with
@@ -52,7 +53,8 @@ module Samagotchi
         child = SessionManager.spawn_session(
           prompt: prompt, working_directory: @host.cwd.call || Dir.pwd, model_name: @host.model_name&.call,
           parent_id: parent_id, messages: Array(messages).map { |message| unfrozen(message) }, title: title,
-          images_from: Session.session_dir(parent_id, state_dir: state_dir), state_dir: state_dir
+          images_from: Session.session_dir(parent_id, state_dir: state_dir), state_dir: state_dir,
+          llm_context: @host.llm_context&.call
         )
         child.id
       end

data/lib/samagotchi/prompt_note.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A model note a session's system prompt carried (ModelNotes::Note
+  # without its body): what the session file's `prompt_notes` records at
+  # each prompt build, so /stats, /model, the web and a later comparison
+  # read what the prompt really held. name: the memory name; scope:
+  # "system" or "project"; chars: the body's length in the prompt; digest:
+  # a short SHA-256 of that body (ModelNotes::Note#digest).
+  PromptNote = Data.define(:name, :scope, :chars, :digest) do
+    # @param note [ModelNotes::Note]
+    def self.from_note(note)
+      new(name: note.name, scope: note.scope, chars: note.chars, digest: note.digest)
+    end
+
+    # A saved or wire record (string or symbol keys); nil without a name.
+    def self.from_h(raw)
+      return raw if raw.is_a?(PromptNote)
+      return nil unless raw.is_a?(Hash)
+
+      get = ->(key) { raw.key?(key.to_s) ? raw[key.to_s] : raw[key] }
+      name = get.call(:name).to_s.strip
+      return nil if name.empty?
+
+      chars = get.call(:chars)
+      new(name: name, scope: get.call(:scope)&.to_s, chars: chars.is_a?(Numeric) ? chars.to_i : nil,
+          digest: get.call(:digest)&.to_s)
+    end
+
+    # The records of a saved list (others dropped).
+    # @return [Array<PromptNote>]
+    def self.list(raw)
+      Array(raw).filter_map { |entry| from_h(entry) }
+    end
+
+    # "model_notes_deepseek (system, 612 chars), model_notes_x (project,
+    # 80 chars)": the line /model, /stats and chi self show; "" without
+    # notes. As format.js promptNotesText (spec/shared/labels_matrix.json).
+    # @param notes [Array<PromptNote, Hash>]
+    def self.text(notes)
+      list(notes).map(&:label).join(", ")
+    end
+
+    # "model_notes_deepseek (system, 612 chars)".
+    def label
+      details = [scope, chars && "#{chars} chars"].compact.reject { |part| part.to_s.empty? }
+      details.empty? ? name : "#{name} (#{details.join(", ")})"
+    end
+
+    # The session file's record (string keys).
+    def to_file = to_h.transform_keys(&:to_s)
+  end
+end

data/lib/samagotchi/reply_wait.rb

@@ -45,7 +45,7 @@ module Samagotchi
     #   decided the outcome loaded it (a caller's next baseline); nil for
     #   :canceled and :timeout
     Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, :error_kind, :retryable, :cancel_reason,
-                        :stopped_by, :session, keyword_init: true)
+                        :stopped_by, :kept_steps, :session, keyword_init: true)
 
     module_function
 
@@ -171,8 +171,8 @@ module Samagotchi
         return Result.new(status: :no_reply, outcome: "exhausted", limit: last["limit"], session: session)
       end
 
-      text = outcome == "failed" ? failure_summary(session.messages) : nil
-      why = fresh ? last.slice("error_kind", "retryable", "cancel_reason", "stopped_by").transform_keys(&:to_sym) : {}
+      text = outcome == "failed" ? TurnNote.failure_summary(session.messages) : nil
+      why = fresh ? last.slice("error_kind", "retryable", "cancel_reason", "stopped_by", "kept_steps").transform_keys(&:to_sym) : {}
       Result.new(status: :no_reply, outcome: outcome, text: text, session: session, **why)
     end
 
@@ -200,20 +200,6 @@ module Samagotchi
       session
     end
 
-    # The summary in the failed-turn note at the conversation's tail, nil
-    # without one.
-    def failure_summary(messages)
-      list = Array(messages)
-      index = TurnNote.trailing_index(list)
-      return nil unless index
-
-      text = (list[index][:content] || list[index]["content"]).to_s
-      prefix = "#{TurnNote::OPEN}#{TurnNote::FAILED}"
-      return nil unless text.start_with?(prefix)
-
-      text[prefix.length..].sub(/\. [^.]*\.\]\z/, "")
-    end
-
     # @return [Result, nil] :done with the newest reply past the cursor
     def reply_past(id, state_dir:, cursor:)
       file = newest_reply(id, state_dir: state_dir)