samagotchi 0.3.0 → 0.5.0

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require_relative "installer"
+require_relative "listing"
+require_relative "manifest"
+require_relative "merger"
+require_relative "provenance"
+require_relative "source"
+require_relative "status"
+require_relative "system_bundle"
+require_relative "../version"
+
+module Samagotchi
+  module MemoryBundle
+    # What `chi update` does to the installed bundles that chi ships: one
+    # Row per installed bundle (the system bundle aside: SystemBundle.sync
+    # has it). A bundle is updated when it was installed from a shipped dir
+    # (its source is …/lib/samagotchi/bundles/<dir>, in a gem or a
+    # checkout), chi ships it under the same name, the shipped version is
+    # newer and this chi meets its requires_chi. It never installs a
+    # bundle that isn't installed and never downgrades.
+    #
+    # .md files take the Installer's 3-way merge: a conflict keeps the
+    # user's file (kept). Hooks, rules and the plugin are replaced; an
+    # edited one (which didn't load: its sha no longer matched) is listed
+    # in replaced.
+    module ShippedUpdate
+      # status: :would_update (plan), :updated, :up_to_date, :skipped,
+      # :failed. note says why for skipped/failed. kept and replaced are
+      # file names; under plan they are what apply would keep or replace.
+      Row = Struct.new(:name, :from, :to, :status, :note, :kept, :replaced, :source_dir, :scope, keyword_init: true)
+
+      SHIPPED_SOURCE = %r{/lib/samagotchi/bundles/[^/]+/?\z}
+
+      module_function
+
+      # Read-only.
+      # @return [Array<Row>] by name
+      def plan(shipped_dir: SourceNormalizer::SHIPPED_DIR, chi_version: Samagotchi::VERSION)
+        shipped = Listing.shipped(dir: shipped_dir).to_h { |s| [s.name, s] }
+        installed_names.map do |name|
+          plan_row(name, shipped[name], shipped_dir, chi_version)
+        end
+      end
+
+      # The shipped bundles not installed (what the footer lists).
+      # @return [Array<Listing::Shipped>]
+      def not_installed(shipped_dir: SourceNormalizer::SHIPPED_DIR)
+        names = installed_names
+        Listing.shipped(dir: shipped_dir).reject { |s| names.include?(s.name) }
+      end
+
+      # Runs the Installer for each :would_update row; the others pass
+      # through. A failing bundle doesn't stop the rest.
+      # @return [Array<Row>]
+      def apply(rows)
+        rows.map do |row|
+          next row unless row.status == :would_update
+
+          installer = Installer.new(source: row.source_dir, name: row.name, scope: row.scope, strict: true, upgrade: true)
+          installer.run
+          row.dup.tap do |r|
+            r.status = :updated
+            r.kept = installer.conflicts.keys
+          end
+        rescue StandardError => e
+          row.dup.tap do |r|
+            r.status = :failed
+            r.note = e.message.lines.first.to_s.strip
+          end
+        end
+      end
+
+      def installed_names
+        dir = Provenance.bundles_dir
+        return [] unless File.directory?(dir)
+
+        Dir.children(dir).reject { |e| e.start_with?(".") || e == SystemBundle::BUNDLE_NAME }
+           .select { |e| File.file?(File.join(dir, e, "manifest.json")) }.sort
+      end
+
+      def plan_row(name, ship, shipped_dir, chi_version)
+        row = Row.new(name: name, kept: [], replaced: [])
+        data = begin
+          Provenance.new(name: name).read
+        rescue JSON::ParserError, SystemCallError
+          nil
+        end
+        return skip(row, "manifest.json unreadable") unless data.is_a?(Hash)
+
+        row.from = data[:version].to_s
+        row.scope = data[:scope].to_s.empty? ? "system" : data[:scope].to_s
+        return skip(row, "not from chi") unless ship && data[:source].to_s.match?(SHIPPED_SOURCE)
+
+        row.to = ship.version.to_s
+        return skip(row, "newer than shipped: left") if Listing.newer?(row.from, row.to)
+        return row.tap { |r| r.status = :up_to_date; r.to = nil } unless Listing.newer?(row.to, row.from)
+
+        row.source_dir = File.join(shipped_dir, ship.source)
+        manifest = Manifest.read(dir: row.source_dir)
+        if Manifest.requires_chi_failure(manifest.requires_chi, chi_version)
+          return skip(row, "needs chi #{manifest.requires_chi}", keep_to: true)
+        end
+        return skip(row, "project scope: chi bundle upgrade #{ship.source} in the project") if row.scope == "project"
+
+        row.kept = conflicts(row, data)
+        row.replaced = edited_executables(name, data)
+        row.status = :would_update
+        row
+      end
+
+      def skip(row, note, keep_to: false)
+        row.to = nil unless keep_to
+        row.status = :skipped
+        row.note = note
+        row
+      end
+
+      # The .md files whose local edits conflict with the shipped version.
+      def conflicts(row, data)
+        provenance = Provenance.new(name: row.name)
+        target_dir = Status.resolve_target_dir(row.scope)
+        return [] unless data[:files]
+
+        Dir.glob(File.join(row.source_dir, "*.md")).map { |f| File.basename(f) }.sort.select do |key|
+          Merger.classify(base_path: provenance.base_path(key), current_path: File.join(target_dir, key),
+                          incoming_path: File.join(row.source_dir, key)) == :conflict
+        end
+      end
+
+      # Installed hooks, rules and the plugin whose sha differs from the
+      # recorded one (they didn't load), as hooks/F, guardrails/F, plugin/F.
+      def edited_executables(name, data)
+        provenance = Provenance.new(name: name)
+        edited = []
+        (data[:hooks] || {}).each do |file, meta|
+          edited << "hooks/#{file}" if edited?(File.join(provenance.hooks_dir, file.to_s), meta)
+        end
+        (data[:guardrails] || {}).each do |file, meta|
+          edited << "guardrails/#{file}" if edited?(File.join(provenance.guardrails_dir, file.to_s), meta)
+        end
+        plugin = provenance.plugin_path(data)
+        edited << "plugin/#{File.basename(plugin)}" if plugin && edited?(plugin, data[:plugin])
+        edited
+      end
+
+      def edited?(path, meta)
+        recorded = meta.is_a?(Hash) ? meta[:sha256].to_s.delete_prefix("sha256:") : ""
+        return false if recorded.empty? || !File.file?(path)
+
+        Digest::SHA256.hexdigest(File.binread(path)) != recorded
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/status.rb

@@ -31,6 +31,7 @@ module Samagotchi
           missing = !File.exist?(target_path)
           index_present = index_has_entry?(scope, file_key_str)
           details[file_key_str] = {
+            conflict: meta.is_a?(Hash) && meta[:conflict] == true,
             stored_checksum: stored_checksum,
             current_checksum: current_checksum,
             base_checksum: base_checksum,
@@ -96,11 +97,13 @@ module Samagotchi
         end
       end
 
+      # Index lines name the entry without ".md" (Installer#update_target_index,
+      # memory_write); a legacy "name.md" line counts too.
       def self.index_has_entry?(scope, file_key)
         path = IndexUpdater.index_path_for(scope)
         return false unless path && File.exist?(path)
         content = File.read(path)
-        content.match?(IndexUpdater.managed_pattern(file_key))
+        [file_key.delete_suffix(".md"), file_key].uniq.any? { |name| content.match?(IndexUpdater.managed_pattern(name)) }
       end
     end
   end

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require_relative "installer"
 require_relative "provenance"
 require_relative "manifest"
+require_relative "merger"
 require_relative "../log"
 
 module Samagotchi
@@ -27,40 +28,72 @@ module Samagotchi
 
       module_function
 
+      # What sync did (or, with dry_run, would do). status is :installed,
+      # :updated, :restored (missing files put back), :up_to_date,
+      # :newer_installed (left as is), :skipped (SKIP_ENV or no shipped
+      # bundle) or :failed (error: says why); kept lists the files whose
+      # local edits conflicted with the update and were kept.
+      Result = Struct.new(:from, :to, :status, :kept, :warnings, :error, keyword_init: true) do
+        def changed? = %i[installed updated restored].include?(status)
+      end
+
       # Ensure the system bundle is installed and up-to-date.
       # Idempotent and warn-only: never raises to callers.
       # Safe for TUI and non-TUI (web/worker) paths — Engine calls this.
       def ensure!
-        return false if skip?
-        return false unless File.directory?(GEM_BUNDLE_DIR)
+        result = sync
+        case result.status
+        when :failed
+          Log.error(:memory, "system_bundle_failed", echo: "[samagotchi-system] #{result.error}")
+        when :newer_installed
+          with_lock { note_newer_installed(result.from, result.to) }
+        end
+        result.kept.each do |file_key|
+          Log.info(:memory, "system_local_edit_kept", echo: "[samagotchi-system] kept local edit in #{file_key} (bundle v#{result.to} has update — run: chi bundle status #{BUNDLE_NAME} / chi bundle diff #{BUNDLE_NAME} #{file_key})", file: file_key.to_s)
+        end
+        result.warnings.each { |w| Log.warn(:memory, "system_bundle_warning", echo: "[samagotchi-system] #{w}") }
+        result.changed?
+      end
+
+      # Install, upgrade or repair the installed system bundle to match the
+      # shipped one, under the lock. Never raises; logs nothing (ensure!
+      # and chi update report the Result).
+      # @param dry_run [Boolean] classify only, write nothing
+      # @return [Result]
+      def sync(dry_run: false)
+        return result(:skipped, error: "#{SKIP_ENV} is set") if skip?
+        return result(:skipped, error: "no shipped system bundle") unless File.directory?(GEM_BUNDLE_DIR)
 
         begin
           gem_manifest = Manifest.read(dir: GEM_BUNDLE_DIR)
         rescue Manifest::ValidationError => e
-          Log.error(:memory, "system_manifest_invalid", echo: "[samagotchi-system] invalid gem manifest: #{e.message}")
-          return false
+          return result(:failed, error: "invalid gem manifest: #{e.message}")
         end
+        to = gem_manifest.version.to_s
 
         with_lock do
           data = Provenance.new(name: BUNDLE_NAME).read
+          from = data && data[:version].to_s
 
           if data.nil?
-            install_fresh(gem_manifest)
-          elsif installed_newer?(data[:version], gem_manifest.version)
+            dry_run ? result(:installed, to: to) : install_fresh(to)
+          elsif installed_newer?(from, to)
             # Running an older checkout/gem: never downgrade the user's system memories
             # (not even to restore a missing file). `chi self` shows installed vs shipped.
-            note_newer_installed(data[:version], gem_manifest.version)
-            false
-          elsif data[:version].to_s != gem_manifest.version.to_s
-            upgrade_existing(gem_manifest, data)
+            result(:newer_installed, from: from, to: to)
+          elsif from != to
+            dry_run ? result(:updated, from: from, to: to, kept: conflicting(gem_manifest)) : upgrade_existing(from, to)
           else
             # Already at desired version — still verify files present (e.g. user deleted one)
-            verify_files_present(gem_manifest, data)
+            verify_files_present(gem_manifest, from, dry_run)
           end
         end
       rescue StandardError => e
-        Log.error(:memory, "system_bundle_failed", echo: "[samagotchi-system] ensure failed: #{e.class}: #{e.message}", error: e.class.name)
-        false
+        result(:failed, error: "ensure failed: #{e.class}: #{e.message}")
+      end
+
+      def result(status, from: nil, to: nil, kept: [], warnings: [], error: nil)
+        Result.new(from: from, to: to, status: status, kept: kept, warnings: warnings, error: error)
       end
 
       # Parallel chi starts on one config dir take turns: the second one reads
@@ -101,7 +134,7 @@ module Samagotchi
         File.write(path, "#{pair}\n", mode: "a")
       end
 
-      def install_fresh(gem_manifest)
+      def install_fresh(to)
         installer = Installer.new(
           source: GEM_BUNDLE_DIR,
           name: BUNDLE_NAME,
@@ -109,53 +142,48 @@ module Samagotchi
           force: false,
           strict: true
         )
-        _nd, _manifest = installer.run
-        unless installer.warnings.empty?
-          installer.warnings.each { |w| Log.warn(:memory, "system_bundle_warning", echo: "[samagotchi-system] #{w}") }
-        end
-        true
+        installer.run
+        result(:installed, to: to, warnings: installer.warnings)
       end
 
-      def upgrade_existing(gem_manifest, _existing_data)
-        installer = Installer.new(
-          source: GEM_BUNDLE_DIR,
-          name: BUNDLE_NAME,
-          scope: SCOPE,
-          force: false,
-          strict: true,
-          upgrade: true
-        )
-        _nd, _manifest = installer.run
-        # Installer already handled fast_forward/keep/noop. Conflicts are kept with warning.
-        if installer.conflicts.any?
-          installer.conflicts.each do |file_key, _info|
-            Log.info(:memory, "system_local_edit_kept", echo: "[samagotchi-system] kept local edit in #{file_key} (bundle v#{gem_manifest.version} has update — run: chi bundle status #{BUNDLE_NAME} / chi bundle diff #{BUNDLE_NAME} #{file_key})", file: file_key.to_s)
-          end
-        end
-        installer.warnings.each { |w| Log.warn(:memory, "system_bundle_warning", echo: "[samagotchi-system] #{w}") } unless installer.warnings.empty?
-        true
+      # Installer handles fast_forward/keep/noop; a conflict keeps the local
+      # file, and its own "Conflict in" warning is left out (kept says it).
+      def upgrade_existing(from, to)
+        installer = upgrade_installer
+        installer.run
+        kept = installer.conflicts.keys
+        warnings = installer.warnings.reject { |w| kept.any? { |k| w.start_with?("Conflict in #{k}:") } }
+        result(:updated, from: from, to: to, kept: kept, warnings: warnings)
       end
 
-      def verify_files_present(gem_manifest, data)
-        # If any file from the bundle is missing on disk but provenance says it should exist,
-        # reinstall that file via Installer (which will classify as :install). This handles
-        # accidental user deletion without forcing a full reinstall.
+      # A file from the bundle missing on disk (the user deleted it) is put
+      # back via the Installer (which classifies it as :install), without a
+      # full reinstall.
+      def verify_files_present(gem_manifest, version, dry_run)
         target_dir = Installer.system_dir
         missing = gem_manifest.files.keys.any? { |k| !File.exist?(File.join(target_dir, k)) }
-        return false unless missing
+        return result(:up_to_date, from: version, to: version) unless missing
+        return result(:restored, from: version, to: version) if dry_run
 
-        installer = Installer.new(
-          source: GEM_BUNDLE_DIR,
-          name: BUNDLE_NAME,
-          scope: SCOPE,
-          force: false,
-          strict: true,
-          upgrade: true
-        )
-        _nd, _manifest = installer.run
-        true
+        upgrade_installer.run
+        result(:restored, from: version, to: version)
+      end
+
+      # The files an upgrade would keep: edited here and changed in the
+      # shipped bundle (a dry run's kept).
+      def conflicting(gem_manifest)
+        provenance = Provenance.new(name: BUNDLE_NAME)
+        gem_manifest.files.keys.map(&:to_s).sort.select do |key|
+          Merger.classify(base_path: provenance.base_path(key), current_path: File.join(Installer.system_dir, key),
+                          incoming_path: File.join(GEM_BUNDLE_DIR, key)) == :conflict
+        end
+      end
+
+      def upgrade_installer
+        Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true)
       end
-      private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present
+      private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present,
+                           :upgrade_installer, :result, :conflicting
     end
   end
 end

data/lib/samagotchi/model_profile.rb

@@ -14,6 +14,9 @@ module Samagotchi
     # 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)
+    # 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)
 
     attr_reader :name, :turn_start, :turn_end,
                 :tool_call_open, :tool_call_close,
@@ -113,23 +116,37 @@ module Samagotchi
       end
     end
 
-    def self.required_model_name(model_name = nil, env: ENV)
+    def self.required_model_name(model_name = nil)
       value = model_name.to_s.strip
       if value.empty?
-        begin
-          require_relative "config"
-          cfg = Samagotchi::Config.get("default.model") rescue nil
-          value = cfg.to_s.strip unless cfg.nil? || cfg.to_s.strip.empty?
-        rescue StandardError
-          nil
-        end
+        require_relative "config"
+        value = Samagotchi::Config.get("default.model").to_s.strip
       end
-      value = env[MODEL_ENV].to_s.strip if value.empty?
       raise MissingModel, missing_model_message if value.empty?
 
       value
     end
 
+    # Raises UnknownHost when +model_name+ (or the alias it names) is
+    # qualified with a host that isn't configured, instead of sending the
+    # whole ref to the default host as a model id. Where a model comes in
+    # (an Engine starting or switching, a spawned session) calls it.
+    # @param hosts [Hash, nil] the hosts a prefix may name (a HostRegistry's
+    #   entries); config.yml's by default
+    # @return [String] +model_name+
+    def self.check_host!(model_name, env: ENV, hosts: nil)
+      require_relative "config"
+      hosts ||= Samagotchi::ConfigFile.hosts_config(env: env)
+      ref = Samagotchi::ConfigFile.resolve_model_alias(model_name, env: env, hosts: hosts)
+      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(', ')}"
+    end
+
     # One line for the user: where to set the model.
     def self.missing_model_message
       path = begin
@@ -158,7 +175,7 @@ module Samagotchi
     end
 
     def self.from_env
-      from_model_name(required_model_name(nil, env: ENV))
+      from_model_name(required_model_name(nil))
     end
 
     # ── Resolution: which profile a model gets ───────────────────────────

data/lib/samagotchi/note_command.rb

@@ -102,7 +102,8 @@ module Samagotchi
 
     # --all: every live session. @return [Integer] exit status
     def deliver_to_live(text, source)
-      ids = SessionManager.session_summaries(live: true, include_tests: false, state_dir: @state_dir).map { |s| s[:id] }
+      ids = SessionManager.session_summaries(live: true, include_tests: Session.test_session_env?,
+                                             state_dir: @state_dir).map { |s| s[:id] }
       if ids.empty?
         error_line("chi note: no live sessions (chi sessions list --live --scope=all)")
         return 1

data/lib/samagotchi/prompt.rb

@@ -39,8 +39,10 @@ module Samagotchi
     # what it was before images existed.
     #
     # @param vision [VisionContext, nil] the turn's images context
+    # @param prefill [String] text after the generation cue, the start of
+    #   the model's answer (Thinking.native: Qwen's empty thought)
     # @return [Array(String, Array<String>)]
-    def self.format_with_images(messages, profile: ModelProfile.default, vision: nil)
+    def self.format_with_images(messages, profile: ModelProfile.default, vision: nil, prefill: "")
       plan = ImagePlan.new(messages, vision, data: :base64)
       images = []
       suffixes = messages.each_with_index.map { |m, index| image_lines(plan.items(m, index), profile, images) }
@@ -49,7 +51,7 @@ module Samagotchi
              else
                format_with_turn_markers(messages, profile, suffixes)
              end
-      [text, images]
+      [text + prefill.to_s, images]
     end
 
     private

data/lib/samagotchi/reminder_store.rb

@@ -90,7 +90,7 @@ module Samagotchi
 
     # Get all due reminders whose interval has elapsed.
     # Returns an Array of {name:, description:, interval_minutes:} hashes.
-    # Called by Engine#maybe_inject_reminders (synchronously, at run_turn start).
+    # Called by Engine#collect_due_reminders (synchronously, at run_turn start).
     # Thread-safe. Returns a frozen copy so the caller can't mutate internal state.
     # @return [Array<Hash>] array of due reminder hashes (may be empty)
     def due_reminders
@@ -103,14 +103,6 @@ module Samagotchi
       end
     end
 
-    # Get the name of the next due reminder (if any) whose interval has elapsed.
-    # Kept for backward compatibility with IdleReminders thread.
-    # @return [String, nil] the reminder name, or nil if none are due
-    def next_due_name
-      due = due_reminders
-      due.first&.fetch(:name)
-    end
-
     # Mark a reminder as fired — resets its next_fire_at to now + interval.
     # Called by Engine after a due reminder has been delivered.
     # @param name [String] the reminder name

data/lib/samagotchi/reply_wait.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "session"
+require_relative "turn_note"
 
 module Samagotchi
   # Loaded on first use: session_manager requires terminal_ui, which
@@ -23,7 +24,11 @@ module Samagotchi
     # @!attribute file [String, nil] the reply's filename, the next cursor
     # @!attribute question [Hash, nil] the pending question
     #   (:waiting_for_answer)
-    Result = Struct.new(:status, :text, :file, :question, keyword_init: true)
+    # @!attribute outcome [String, nil] how the turn ended when it left no
+    #   reply (:no_reply): "failed", "canceled" or "completed" (empty), from
+    #   the session's last_turn; nil when unknown. With "failed", text is
+    #   the failure's summary when the turn note has one.
+    Result = Struct.new(:status, :text, :file, :question, :outcome, keyword_init: true)
 
     module_function
 
@@ -38,7 +43,10 @@ module Samagotchi
     #   messages (a failed, canceled or empty one leaves its note) and went
     #   idle again ends the wait even if it was never seen running, and a
     #   question already pending then is not the answer's. A nil
-    #   messages: skips the count.
+    #   messages: skips the count. last_turn: (the session's
+    #   last_turn["ended_at"] then, maybe nil) ends the wait on any turn
+    #   that ended since, idle again, however fast it ran: a failure after
+    #   a failure replaces the note and leaves the count as it was.
     # @param owner_grace [Numeric, nil] seconds with no live worker before
     #   :worker_gone (one that died before its rescue leaves it running)
     # @return [Result]
@@ -72,13 +80,13 @@ module Samagotchi
 
         if session.status == Session::STATUS_RUNNING
           seen_running = true
-        elsif seen_running || (baseline&.dig(:messages) && session.messages.size > baseline[:messages])
+        elsif seen_running || 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.
           # 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) || Result.new(status: :no_reply)
+          return reply_past(id, state_dir: state_dir, cursor: cursor) || no_reply(session, baseline)
         end
 
         if owner_grace
@@ -95,6 +103,42 @@ module Samagotchi
       end
     end
 
+    # An idle session whose turn ended after the baseline was taken: its
+    # last_turn moved on, or its messages grew (a turn's note).
+    def turn_ended_since?(session, baseline)
+      return false unless baseline
+
+      if baseline.key?(:last_turn)
+        ended = session.last_turn.is_a?(Hash) ? session.last_turn["ended_at"] : nil
+        return true if ended && ended != baseline[:last_turn]
+      end
+      !!(baseline[:messages] && session.messages.size > baseline[:messages])
+    end
+
+    # @return [Result] :no_reply with the outcome the session's last_turn
+    #   records, when it is the turn waited for
+    def no_reply(session, baseline)
+      last = session.last_turn.is_a?(Hash) ? session.last_turn : {}
+      fresh = baseline.nil? || !baseline.key?(:last_turn) || (last["ended_at"] && last["ended_at"] != baseline[:last_turn])
+      outcome = fresh ? last["outcome"] : nil
+      text = outcome == "failed" ? failure_summary(session.messages) : nil
+      Result.new(status: :no_reply, outcome: outcome, text: text)
+    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)