samagotchi 0.11.0 → 0.13.0

data/lib/samagotchi/llm/usage.rb

@@ -4,8 +4,8 @@ require_relative "../token_usage"
 
 module Samagotchi
   module LLM
-    # A turn's token counts, never nil: what the server reported (:server),
-    # else a chars/4 estimate (:estimate), else zeros (:none).
+    # A response's token counts, never nil: what the server reported
+    # (:server), else zeros (:none).
     Usage = Data.define(:prompt_tokens, :completion_tokens, :source) do
       # @return [Usage, nil] nil when the payload carries no counts
       def self.from_payload(payload)
@@ -16,64 +16,9 @@ module Samagotchi
             source: :server)
       end
 
-      # +extra_prompt_tokens+: what the prompt holds besides text (images).
-      def self.estimate(prompt_text:, completion_text:, extra_prompt_tokens: 0)
-        new(prompt_tokens: TokenUsage.estimate(prompt_text.to_s) + extra_prompt_tokens.to_i,
-            completion_tokens: TokenUsage.estimate(completion_text.to_s),
-            source: :estimate)
-      end
-
       def self.none = new(prompt_tokens: 0, completion_tokens: 0, source: :none)
 
       def total_tokens = prompt_tokens + completion_tokens
     end
-
-    # Builds a turn's Usage from its stream events, the way SessionMetrics
-    # counts them: server counts are cumulative per request, so each
-    # generation keeps its highest; the prompt grows across a turn's
-    # generations, so the last generation's prompt counts, and completions
-    # add up. Without server counts, the streamed text is estimated.
-    class UsageCollector
-      def initialize
-        @generations = []
-      end
-
-      def observe(event)
-        case event[:type]
-        when :generation_started
-          @generations << { prompt: 0, completion: 0, server: false, text: +"" }
-        when :generation_chunk
-          @generations << { prompt: 0, completion: 0, server: false, text: +"" } if @generations.empty?
-          record(@generations.last, event)
-        end
-      end
-
-      # @param prompt_text [String, nil] what an estimate counts as the prompt
-      # @param extra_prompt_tokens [Integer] estimated non-text prompt tokens
-      def usage(prompt_text: nil, extra_prompt_tokens: 0)
-        server = @generations.select { |generation| generation[:server] }
-        unless server.empty?
-          return Usage.new(prompt_tokens: server.last[:prompt], completion_tokens: server.sum { |g| g[:completion] },
-                           source: :server)
-        end
-
-        text = @generations.sum("") { |generation| generation[:text] }
-        return Usage.none if text.empty?
-
-        Usage.estimate(prompt_text: prompt_text, completion_text: text, extra_prompt_tokens: extra_prompt_tokens)
-      end
-
-      private
-
-      def record(generation, event)
-        counts = Usage.from_payload(event[:payload])
-        if counts
-          generation[:server] = true
-          generation[:prompt] = [generation[:prompt], counts.prompt_tokens].max
-          generation[:completion] = [generation[:completion], counts.completion_tokens].max
-        end
-        generation[:text] << event[:content].to_s
-      end
-    end
   end
 end

data/lib/samagotchi/memory_bundle/installer.rb

@@ -265,6 +265,7 @@ module Samagotchi
         # ── Plugin: <file> into <bundle_dir>/plugin/ (docs/plugins.md) ────
         # Like the rules, the bundle's plugin replaces an earlier one.
         plugin_file_for_provenance = install_plugin(manifest, normalized_dir, provenance)
+        warn_hooks_requires_chi(manifest, all_hooks_in_bundle)
 
         # Files the previous version shipped and this one doesn't.
         if @upgrade && existing_provenance && existing_provenance[:files]
@@ -365,7 +366,7 @@ module Samagotchi
             version: manifest.version,
             source_path: @source,
             hooks: hooks_for_provenance,
-            trust_level: manifest.respond_to?(:trust_level) ? manifest.trust_level : nil,
+            trust_level: manifest.trust_level,
             source_commit: source_commit,
             hooks_files: hooks_files_for_provenance,
             guardrails_files: guardrail_files_for_provenance,
@@ -467,6 +468,17 @@ module Samagotchi
         end
       end
 
+      # The hook loader skips every hook of a bundle whose requires_chi this
+      # chi doesn't meet (Hooks::BundleLoader); say so at install, as
+      # install_plugin does for the plugin.
+      def warn_hooks_requires_chi(manifest, hook_files)
+        return if manifest.nil? || hook_files.empty?
+
+        if (failure = Manifest.requires_chi_failure(manifest.requires_chi, Samagotchi::VERSION))
+          @warnings << "Bundle #{@name}: its hooks won't load: #{failure}"
+        end
+      end
+
       # Copy the manifest's plugin file into the bundle's plugin/ dir,
       # warning when its sha256 differs from the declared one or this chi
       # doesn't meet requires_chi (the Engine then won't load it).

data/lib/samagotchi/memory_bundle/status.rb

@@ -43,7 +43,15 @@ module Samagotchi
           }
         end
         { provenance: data, scope: scope, target_dir: target_dir, files: details, plugin: plugin_status(provenance, data),
-          needs: needs_status(data) }
+          hooks_requires_failure: hooks_requires_failure(data), needs: needs_status(data) }
+      end
+
+      # Why none of the bundle's hooks load (this chi doesn't meet its
+      # requires_chi, Hooks::BundleLoader), or nil: it has no hooks or meets it.
+      def self.hooks_requires_failure(data)
+        return nil if (data[:hooks] || {}).empty?
+
+        Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION)
       end
 
       # The stored needs, each with found: from this process's PATH (the

data/lib/samagotchi/memory_paths.rb

@@ -51,6 +51,14 @@ module Samagotchi
       File.basename(common) == ".git" ? File.dirname(common) : common
     end
 
+    # The top of the git work tree holding +cwd+: the directory with the
+    # nearest .git (a linked worktree's own checkout, unlike #project_root);
+    # nil outside any repository.
+    def work_tree_root(cwd = Dir.pwd)
+      dot_git = find_dot_git(cwd)
+      dot_git && File.dirname(dot_git)
+    end
+
     # Is +cwd+ inside a git repository (a .git somewhere above it)?
     def in_repo?(cwd = Dir.pwd)
       !find_dot_git(cwd).nil?

data/lib/samagotchi/model_catalog.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "host_registry"
+
+module Samagotchi
+  # The hosts' model listings (HostRegistry#list_all_models) as rows a user
+  # picks from: GET /api/models and `chi models`. Every name question goes
+  # to ModelRef / HostRegistry#resolve; nothing here parses a ref.
+  module ModelCatalog
+    # host: the host that listed the id; ref: the name `--model` takes for
+    # it (see .spell).
+    Row = Data.define(:host, :id, :ref)
+    # rows: the default host's first, then the others by name; warnings:
+    # "host: error" per host that failed.
+    Listing = Data.define(:rows, :warnings)
+
+    module_function
+
+    # @param results [Hash] list_all_models' answer
+    # @param registry [#default_entry]
+    # @return [Listing]
+    def listing(results, registry:)
+      default_host = registry.default_entry&.name
+      rows = []
+      warnings = []
+      results.keys.sort_by { |name| [name == default_host ? 0 : 1, name] }.each do |host|
+        data = results[host]
+        if data[:error]
+          warnings << "#{host}: #{data[:error]}"
+          next
+        end
+        Array(data[:models]).each do |info|
+          id = info.id.to_s
+          next if id.strip.empty? || id.end_with?(":batch")
+
+          rows << Row.new(host: host, id: id, ref: spell(host, id, default_host))
+        end
+      end
+      Listing.new(rows: rows, warnings: warnings)
+    end
+
+    # A listed id as a ref that routes back to its host: bare on the
+    # default host (a bare id goes there first), "host:id" elsewhere and for
+    # a default-host id with a ':' (bare, "qwen3:8b" would name a host qwen3).
+    # '/' doesn't name a host, so "openai/gpt-4o" stays bare.
+    def spell(host, id, default_host)
+      host == default_host && !id.include?(":") ? id : "#{host}:#{id}"
+    end
+
+    # `chi models --format json`'s object. default_host: where bare names
+    # go first (its rows are the "default host" group). default: the default's listed
+    # row name when it resolves to one, else its resolved ref; default_typed:
+    # the alias it was typed as. A row whose name resolves elsewhere (an
+    # alias named like the id shadows it) carries shadowed_by.
+    # @param default_name [String, nil] default.model as configured
+    # @return [Hash]
+    def payload(results, registry:, default_name:)
+      listing = listing(results, registry: registry)
+      models = listing.rows.map do |row|
+        hash = { name: row.ref, host: row.host, id: row.id }
+        shadow = shadowed_by(row, registry)
+        shadow ? hash.merge(shadowed_by: shadow) : hash
+      end
+      default, typed = default_for(default_name, listing.rows, registry)
+      { default: default, default_typed: typed, default_host: registry.default_entry&.name, models: models,
+        aliases: aliases(registry), warnings: listing.warnings }
+    end
+
+    # The alias (or the ref) that takes +row+'s name elsewhere, or nil.
+    def shadowed_by(row, registry)
+      target = registry.resolve(row.ref)
+      return nil if target.entry.name == row.host && target.bare_model == row.id
+
+      registry.model_ref(row.ref).alias_name || "#{target.entry.name}:#{target.bare_model}"
+    end
+
+    def default_for(name, rows, registry)
+      return [nil, nil] if name.to_s.strip.empty?
+
+      ref = registry.model_ref(name)
+      target = registry.resolve(name)
+      row = rows.find { |r| r.host == target.entry.name && r.id.casecmp?(target.bare_model) }
+      [row ? row.ref : ref.ref, ref.alias_name ? name.to_s.strip : nil]
+    end
+
+    # config.yml's aliases, each under the host its target goes to: the
+    # default host's first, then by host and name.
+    def aliases(registry)
+      default_host = registry.default_entry&.name
+      names = begin
+        ConfigFile.model_aliases
+      rescue StandardError
+        {}
+      end
+      rows = names.keys.map do |name|
+        { name: name, ref: registry.model_ref(name).ref, host: registry.resolve(name).entry.name }
+      end
+      rows.sort_by { |row| [row[:host] == default_host ? 0 : 1, row[:host], row[:name]] }
+    end
+  end
+end

data/lib/samagotchi/model_profile.rb

@@ -18,11 +18,18 @@ module Samagotchi
     # so every surface that reports a missing model reports it the same way).
     UnknownHost = Class.new(MissingModel)
 
+    # Gemma 4 thinks in a channel: `<|channel>thought` … `<channel|>`. The
+    # one source for the parser, the stream splitter, the literal guard and
+    # the web's saved-message reader.
+    GEMMA_THOUGHT_CHANNEL_OPEN = "<|channel>thought"
+    GEMMA_THOUGHT_CHANNEL_CLOSE = "<channel|>"
+
     attr_reader :name, :turn_start, :turn_end,
                 :tool_call_open, :tool_call_close,
                 :tool_response_open, :tool_response_close,
                 :string_delim,
                 :thought_open, :thought_close,
+                :thought_channel_open, :thought_channel_close,
                 :system_prefix, :user_prefix, :assistant_prefix,
                 :model_prefix,
                 :stop_sequences, :tool_decl_format,
@@ -39,6 +46,9 @@ module Samagotchi
       @string_delim = config[:string_delim]
       @thought_open = config[:thought_open]
       @thought_close = config[:thought_close]
+      # A thinking block besides thought_open's (Gemma's channel), or nil.
+      @thought_channel_open = config[:thought_channel_open]
+      @thought_channel_close = config[:thought_channel_close]
       @system_prefix = config[:system_prefix]
       @user_prefix = config[:user_prefix]
       @assistant_prefix = config[:assistant_prefix]
@@ -68,6 +78,8 @@ module Samagotchi
         string_delim: '<|"|>',
         thought_open: "<|think|>",
         thought_close: nil,
+        thought_channel_open: GEMMA_THOUGHT_CHANNEL_OPEN,
+        thought_channel_close: GEMMA_THOUGHT_CHANNEL_CLOSE,
         system_prefix: "",
         user_prefix: "",
         assistant_prefix: "",
@@ -131,8 +143,9 @@ module Samagotchi
     # qualified with a host that isn't configured, instead of sending the
     # whole ref to the default host as a model id, and when an alias after
     # a host prefix names another host ("openrouter:tiny" with tiny:
-    # box:…). Where a model comes in (an Engine starting or switching, a
-    # spawned session) calls it.
+    # box:…), or with a host config.yml has with enabled: false. 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+
@@ -145,6 +158,9 @@ module Samagotchi
                            "use #{parsed.alias_name} or #{other}:#{parsed.alias_name}"
       end
       ref = parsed.ref
+      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
@@ -155,6 +171,18 @@ module Samagotchi
       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
+    # enabled: false (left out of +hosts+), else nil.
+    def self.disabled_host_prefix(ref, hosts, env)
+      prefix, rest = ref.to_s.split(":", 2)
+      return nil if rest.to_s.strip.empty?
+
+      prefix = prefix.strip.downcase
+      return nil if hosts.keys.any? { |k| k.to_s.downcase == prefix }
+
+      Samagotchi::ConfigFile.disabled_host_names(env: env).include?(prefix) ? prefix : nil
+    end
+
     # "box/x" named host box until '/' stopped naming a host: a saved
     # session or a hand-written ref says so once, then goes to the default host.
     def self.warn_host_slash(ref, hosts)
@@ -193,10 +221,6 @@ module Samagotchi
       DEFAULT_NAME
     end
 
-    def self.from_env
-      from_model_name(required_model_name(nil))
-    end
-
     # ── Resolution: which profile a model gets ───────────────────────────
 
     NAMES = %w[qwen36 gemma4].freeze
@@ -324,20 +348,10 @@ module Samagotchi
       return false if client.nil? || !client.respond_to?(:server_props)
       return false if entry&.chat?
 
-      !client.respond_to?(:transport) || client.transport.name == :llama_cpp
+      client.transport.name == :llama_cpp
     end
     private_class_method :probe?
 
-    # ── Thought channel support ──────────────────────────────────────────
-
-    def thought_channel_open
-      nil
-    end
-
-    def uses_channel_thoughts?
-      false
-    end
-
     def uses_role_prefixes?
       !system_prefix.empty? && !user_prefix.empty?
     end

data/lib/samagotchi/models_command.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "host_registry"
+require_relative "model_catalog"
+require_relative "model_profile"
+require_relative "cli/command"
+require_relative "cli/flags"
+
+module Samagotchi
+  # `chi models`: the names `--model` (and `chi send --new --model`) takes,
+  # listed anew from every host in parallel, within a bounded wait; the
+  # desktop helper's model picker reads --format json. No cache: each run
+  # lists every host (the registry's TTLs live in one process only).
+  class ModelsCommand
+    include CLI::Command
+
+    DEFAULT_TIMEOUT = 4.0
+    FORMATS = %w[text json].freeze
+
+    USAGE = <<~TEXT
+      Usage: chi models [--format text|json] [--timeout S] [TEXT]
+        Lists the models every configured host offers, as the names
+        --model takes: the default first, a default-host id bare, another
+        host's as host:id, then the aliases as "name -> ref". A host that
+        fails or doesn't answer in time is noted on stderr.
+        TEXT          only the names containing it (any case)
+        --format json the default, the models (host, id, name), the aliases
+                      and the warnings as one JSON object
+        --timeout S   wait at most S seconds for the hosts; default 4
+        Exit 0 when any host listed its models, 1 when none did (the
+        default is still printed), 2 on a usage error.
+    TEXT
+
+    FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) do |f|
+      f.value "--format"
+      f.value "--timeout"
+    end
+
+    # @param registry [HostRegistry, nil] specs inject one
+    # @param default_name [String, nil, :config] default.model; :config reads it
+    def initialize(argv, stdout: $stdout, stderr: $stderr, registry: nil, default_name: :config)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @registry = registry
+      @default_name = default_name
+    end
+
+    # @return [Integer] 0 any host listed, 1 none did, 2 usage
+    def run
+      parsed = parse_flags(FLAGS, @argv, format: "text", timeout: DEFAULT_TIMEOUT.to_s)
+      return parsed if parsed.is_a?(Integer)
+
+      options = parsed.options
+      return usage_error("--format takes text or json") unless FORMATS.include?(options[:format])
+
+      timeout = Float(options[:timeout], exception: false)
+      return usage_error("--timeout takes a number of seconds above 0") unless timeout&.positive?
+
+      payload, listed = catalog(timeout)
+      payload = filtered(payload, parsed.args.join(" ").strip)
+      options[:format] == "json" ? print_json(payload) : print_text(payload)
+      listed ? 0 : 1
+    end
+
+    private
+
+    def command_name = "chi models"
+
+    # @return [Array(Hash, Boolean)] the payload and whether any host listed
+    def catalog(timeout)
+      registry = @registry || HostRegistry.new
+      results = registry.list_all_models(force: true, wait: timeout)
+      listed = results.values.any? { |data| data[:error].nil? }
+      [ModelCatalog.payload(results, registry: registry, default_name: default_name), listed]
+    rescue StandardError => e
+      [{ default: default_name, default_typed: nil, default_host: nil, models: [], aliases: [], warnings: [e.message] }, false]
+    end
+
+    def default_name
+      return @default_name unless @default_name == :config
+
+      ModelProfile.required_model_name
+    rescue ArgumentError
+      nil
+    end
+
+    def filtered(payload, text)
+      return payload if text.empty?
+
+      needle = text.downcase
+      payload.merge(models: payload[:models].select { |m| m[:name].downcase.include?(needle) },
+                    aliases: payload[:aliases].select { |a| "#{a[:name]} #{a[:ref]}".downcase.include?(needle) },
+                    filter: text)
+    end
+
+    def print_json(payload)
+      @stdout.puts(JSON.generate(payload.except(:filter)))
+    end
+
+    def print_text(payload)
+      default = payload[:default]
+      names = payload[:models].reject { |m| m[:shadowed_by] }.map { |m| m[:name] }
+      shown_default = default && (payload[:filter].nil? || default.downcase.include?(payload[:filter].downcase))
+      @stdout.puts(default) if shown_default
+      (names - [default]).each { |name| @stdout.puts(name) }
+      payload[:aliases].each { |a| @stdout.puts("#{a[:name]} -> #{a[:ref]}") }
+      payload[:warnings].each { |w| @stderr.puts("chi models: #{w}") }
+    end
+  end
+end

data/lib/samagotchi/parent_report.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "json"
+
+require_relative "cli/exit"
+
+module Samagotchi
+  # How a wait's end (ReplyWait::Result) reads to whoever runs chi as a
+  # sub-agent: `chi send --wait` and `chi answer`. One JSON object for
+  # --format json, or a line (a block for a question) for stderr, and the
+  # exit status. A question carries everything needed to answer it, so a
+  # parent agent can answer from the output alone. Kept apart from the
+  # commands so a later delegate_answer tool reports the same shape.
+  module ParentReport
+    # The approval facts a parent needs; the rest (preview, branch) is the
+    # card's.
+    APPROVAL_KEYS = %i[tool label command paths args cwd rule source reason scopes].freeze
+
+    # stderr that keeps its last line: with --format json a failure before
+    # any wait is reported from it (#error_line).
+    class LastLine < SimpleDelegator
+      attr_reader :last
+
+      def puts(*lines)
+        @last = lines.last.to_s.chomp unless lines.empty?
+        __getobj__.puts(*lines)
+      end
+    end
+
+    module_function
+
+    # @param result [ReplyWait::Result]
+    # @return [String] answered, question, failed, canceled, no_answer,
+    #   error, worker_gone, stopped or running
+    def status(result)
+      case result.status
+      when :done then "answered"
+      when :waiting_for_answer then "question"
+      when :no_reply
+        case result.outcome
+        when "failed" then "failed"
+        when "canceled" then "canceled"
+        else "no_answer"
+        end
+      when :error then "error"
+      when :worker_gone then "worker_gone"
+      when :stopped then "stopped"
+      # ReplyWait's own :canceled is the caller giving up (its cancelled:),
+      # and :timeout the deadline: the turn goes on either way.
+      else "running"
+      end
+    end
+
+    # @return [Integer] 0 answered, 3 a question waits, 4 still running,
+    #   1 anything else
+    def exit_status(result)
+      case status(result)
+      when "answered" then CLI::Exit::OK
+      when "question" then CLI::Exit::QUESTION
+      when "running" then CLI::Exit::RUNNING
+      else CLI::Exit::FAILED
+      end
+    end
+
+    # @param session_id [String]
+    # @param timeout [Numeric, nil] the wait's --timeout (for the running detail)
+    # @return [Hash] the --format json object
+    def json(result, session_id:, timeout: nil)
+      report = { status: status(result), session_id: session_id }
+      case report[:status]
+      when "answered" then report[:text] = result.text.to_s
+      when "question"
+        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)
+      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))
+    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"
+    # @return [Integer] the exit status
+    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil)
+      if json
+        stdout.puts(json_line(result, session_id: session_id, timeout: timeout))
+      elsif result.status == :done
+        stdout.puts(result.text)
+      else
+        stdout.flush
+        text = if result.status == :waiting_for_answer
+                 question_text(result.question, session_id: session_id)
+               else
+                 "#{detail(result, session_id: session_id, timeout: timeout)}\n"
+               end
+        stderr.print("#{command}: #{text}")
+      end
+      stdout.flush
+      exit_status(result)
+    end
+
+    # A failure before any wait (no such session, a busy one, a message
+    # that didn't go in) as the JSON object.
+    # @param session_id [String, nil]
+    def error_line(detail, session_id: nil)
+      JSON.generate({ status: "error", session_id: session_id, detail: detail.to_s })
+    end
+
+    # A pending question (Session#pending_question) as a parent sees it.
+    # kind is "question" for the model's own (the desk stores none),
+    # "hook" or "approval".
+    # @return [Hash]
+    def question(pending)
+      pending ||= {}
+      approval = pending[:approval].is_a?(Hash) ? symbolize(pending[:approval]) : nil
+      {
+        id: pending[:id].to_s,
+        kind: (pending[:kind] || "question").to_s,
+        header: blank(pending[:header]),
+        text: pending[:question].to_s,
+        options: Array(pending[:options]).map(&:to_s),
+        multi_select: !!pending[:multi_select],
+        allow_freeform: !!pending[:allow_freeform],
+        approval: approval&.slice(*APPROVAL_KEYS)
+      }.compact
+    end
+
+    # The command that answers +question+; N is the parent's to fill in.
+    # An approval's is a deny: allowing it is the user's
+    # (Guardrails::ParentApprovals).
+    def answer_with(session_id, question)
+      return "chi answer #{session_id} --question #{question[:id]} --option Deny --text WHY" if approval?(question)
+
+      "chi answer #{session_id} --question #{question[:id]} --option N"
+    end
+
+    # What a parent does with an approval.
+    DENY_AND_TELL = "deny it, and tell your user"
+
+    def approval?(question)
+      question.is_a?(Hash) && (question[:kind] || question["kind"]).to_s == "approval"
+    end
+
+    # What a wait that ended without an answer says, one line.
+    def detail(result, session_id:, timeout: nil)
+      attach = "chi --attach #{session_id}"
+      case result.status
+      when :waiting_for_answer
+        if approval?(result.question)
+          "waiting for an approval: #{first_line(result.question[:question])}; #{DENY_AND_TELL}"
+        else
+          "waiting for an answer: #{first_line(result.question&.dig(:question))}; open it: #{attach} or the web"
+        end
+      when :no_reply then "#{no_reply_line(result)}; #{attach} shows it"
+      when :error then "the worker failed: #{result.text}; #{attach} shows what happened"
+      when :worker_gone then "the worker is gone; #{attach} shows what happened"
+      when :stopped then "the session was stopped (chi sessions stop)"
+      else timeout ? "still running after #{format("%g", timeout)} s: #{attach}" : "still running: #{attach}"
+      end
+    end
+
+    # The whole question for stderr: header, text, numbered options, what
+    # else it takes, and the commands that answer it.
+    # @return [String] lines, newline-terminated
+    def question_text(pending, session_id:)
+      q = question(pending)
+      lines = ["waiting for an answer (#{q[:kind]}): #{q[:header] || first_line(q[:text])}"]
+      text_lines = q[:text].strip.lines.map(&:rstrip)
+      text_lines = text_lines.drop(1) unless q[:header]
+      lines.concat(text_lines.map { |line| "  #{line}" })
+      q[:options].each_with_index { |option, i| lines << "    #{i + 1}. #{option}" }
+      if approval?(q)
+        lines << "  allowing it is up to your user: #{DENY_AND_TELL}"
+        lines << "  deny: #{answer_with(session_id, q)}"
+      else
+        lines << "  more than one allowed: repeat --option" if q[:multi_select]
+        lines << "  free text allowed: --text" if q[:allow_freeform]
+        lines << "  answer: #{answer_with(session_id, q)}"
+        lines << "  or open it: chi --attach #{session_id} or the web"
+      end
+      lines.map { |line| "#{line}\n" }.join
+    end
+
+    def no_reply_line(result)
+      case result.outcome
+      when "failed" then result.text.to_s.strip.empty? ? "the turn failed" : "the turn failed: #{result.text.strip}"
+      when "canceled" then "the turn was canceled"
+      when "completed" then "the turn ended with no visible answer"
+      else "the turn ended without a reply (canceled, failed or empty)"
+      end
+    end
+
+    def first_line(text)
+      text.to_s.strip.lines.first.to_s.strip
+    end
+
+    def blank(value)
+      value.to_s.strip.empty? ? nil : value.to_s
+    end
+
+    def symbolize(hash)
+      hash.each_with_object({}) { |(key, value), out| out[key.to_sym] = value }
+    end
+  end
+end