samagotchi 0.87.0 → 0.89.0

data/lib/samagotchi/bundle_command/try/trace.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../analytics_file"
+require_relative "../../session_metrics"
+
+module Samagotchi
+  class BundleCommand
+    module Try
+      Trace = Data.define(
+        :session_id, :exit_code, :answer, :tools, :notices, :cards, :questions, :denied,
+        :interactive_blocked, :used_memories, :tokens, :cost, :cost_is_estimate, :model, :sandbox, :stderr_tail
+      )
+
+      class TraceReader
+        DENIAL_TEXT = "No one to approve it (non-interactive run)."
+        SESSION_ID = /\A[A-Za-z0-9_-]+\z/
+        STDERR_LIMIT = 4000
+
+        def initialize(state_home:, session_id:)
+          @state_home = state_home
+          @session_id = session_id if session_id.to_s.match?(SESSION_ID)
+        end
+
+        def read(exit_code:, answer:, stderr:, sandbox:)
+          return empty_trace(exit_code, answer, stderr, sandbox) unless @session_id
+
+          sessions_dir = File.join(@state_home, "samagotchi", "sessions")
+          session_path = File.join(sessions_dir, "#{@session_id}.json")
+          session_dir = File.join(sessions_dir, @session_id)
+          session = json_file(session_path) || {}
+          messages = Array(session["messages"]).select { |message| message.is_a?(Hash) }
+          analytics = AnalyticsFile.read(session_dir) || {}
+          entries = card_entries(session_dir)
+          tool_rows, denied = tools(messages, analytics)
+          summary = SessionMetrics.saved_summary(session_dir)
+          cost, estimate = cost_summary(summary)
+          questions = entries.select { |entry| entry["type"] == "question" }
+          notices = entries.select { |entry| entry["type"] == "hook_notice" }
+          cards = entries.select { |entry| entry["type"] == "card" }
+          blocked_count = questions.count { |question| unanswerable?(question) } + denied.size
+
+          Trace.new(
+            session_id: @session_id, exit_code: exit_code, answer: answer.to_s, tools: tool_rows, notices: notices,
+            cards: cards, questions: questions, denied: denied, interactive_blocked: blocked_count.positive?,
+            used_memories: Array(session["used_memory_names"]), tokens: {
+                                                                  prompt: summary&.prompt_sum, completion: summary&.completion_sum
+                                                                },
+            cost: cost, cost_is_estimate: estimate, model: session["model_name"], sandbox: sandbox,
+            stderr_tail: tail(stderr)
+          )
+        end
+
+        private
+
+        def empty_trace(exit_code, answer, stderr, sandbox)
+          Trace.new(session_id: nil, exit_code: exit_code, answer: answer.to_s, tools: [], notices: [], cards: [],
+                    questions: [], denied: [], interactive_blocked: false, used_memories: [], tokens: {
+                      prompt: nil, completion: nil
+                    }, cost: nil, cost_is_estimate: false, model: nil, sandbox: sandbox, stderr_tail: tail(stderr))
+        end
+
+        def tools(messages, analytics)
+          records = Array(analytics["tool_records"]).select { |record| record.is_a?(Hash) }
+                                                    .to_h do |record|
+            [[record["iteration"].to_i, record["call_index"].to_i], record]
+          end
+          tool_responses = messages.select { |message| %w[tool_response tool].include?(message["role"]) }
+          denied = []
+          index = 0
+          iteration = 0
+          rows = messages.flat_map do |message|
+            next [] unless %w[model assistant].include?(message["role"])
+
+            iteration += 1
+            Array(message["tool_calls"]).each_with_index.filter_map do |call, call_index|
+              next unless call.is_a?(Hash)
+
+              index += 1
+              record = records[[iteration, call_index + 1]]
+              id = call["id"]
+              response = tool_responses.find { |entry| entry["tool_call_id"] == id } if id
+              response ||= tool_responses[index - 1] unless id
+              is_denied = response && response["content"].to_s.include?(DENIAL_TEXT)
+              denied << index if is_denied
+              status = is_denied ? "denied" : record&.dig("status").to_s
+              status = "unknown" if status.empty?
+              {
+                index: index,
+                name: record&.[]("called_as") || record&.[]("tool") || call_name(call),
+                args: argument_text(call),
+                status: status,
+                duration_ms: record&.[]("duration_ms").to_i
+              }
+            end
+          end
+          [rows, denied]
+        end
+
+        def call_name(call)
+          function = call["function"].is_a?(Hash) ? call["function"] : {}
+          call["name"] || function["name"] || "tool"
+        end
+
+        def argument_text(call)
+          function = call["function"].is_a?(Hash) ? call["function"] : {}
+          args = call["arguments"] || function["arguments"] || {}
+          args = JSON.parse(args) if args.is_a?(String)
+          if args.is_a?(Hash)
+            preferred = %w[command content path url query].filter_map { |key| args[key] }.first
+            args = preferred || JSON.generate(args)
+          end
+          args.to_s.gsub(/\s+/, " ").strip[0, 200]
+        rescue JSON::ParserError
+          args.to_s.gsub(/\s+/, " ").strip[0, 200]
+        end
+
+        def card_entries(session_dir)
+          data = json_file(File.join(session_dir, "cards.json"))
+          entries = data.is_a?(Hash) ? data["entries"] : []
+          Array(entries).select { |entry| entry.is_a?(Hash) }
+        end
+
+        def unanswerable?(question)
+          question["cancelled"] && question["reason"] == "non_interactive"
+        end
+
+        def cost_summary(summary)
+          return [nil, false] unless summary
+
+          reported = summary.cost_sum.to_f
+          estimate = summary.cost_estimate_sum.to_f
+          return [reported, false] if reported.positive?
+          return [nil, false] unless estimate.positive?
+
+          [estimate, true]
+        end
+
+        def json_file(path)
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError, SystemCallError
+          nil
+        end
+
+        def tail(text)
+          value = text.to_s
+          value.length > STDERR_LIMIT ? value[-STDERR_LIMIT, STDERR_LIMIT] : value
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/bundle_command.rb

@@ -10,7 +10,7 @@ module Samagotchi
   # subcommands have their own flags).
   class BundleCommand
     USAGE = <<~TEXT
-      Usage: chi bundle <install|upgrade|uninstall|status|diff|list|build|trash|new|test|check> [options]
+      Usage: chi bundle <install|upgrade|uninstall|status|diff|list|build|trash|new|test|check|try> [options]
 
         install <source> [--scope system|project] [--force]
           Install a memory bundle from a directory, zip, tar archive, or git URL.
@@ -52,17 +52,26 @@ module Samagotchi
         check [PATH] [--fix] [--set KEY=VALUE]
           Check a bundle you're writing (default: the current dir): manifest, files, sha256 lines,
           requires_chi, and an install + load in a sandbox. --fix rewrites stale sha256 lines.
+
+        try PATH -p TEXT [options]
+          Run one non-interactive model turn with a bundle installed in an isolated sandbox.
     TEXT
 
     # Each subcommand's --help (and only --help: -h and help are taken as
     # the source or name).
     INSTALL_HELP = <<~TEXT
       Usage: chi bundle install <source> [--scope system|project] [--force]
+             chi bundle install --dev PATH
 
         install <source> [--scope system|project] [--force]
           Install a memory bundle from a directory, zip, tar archive, or git URL,
           or a bundle shipped with chi by name (see: chi bundle list).
           --force overwrites existing entries; default skips them.
+        install --dev PATH
+          Install the bundle in the local directory PATH as a link to it: its plugin, hooks, rules and scripts
+          are PATH's own files (an edit applies at the next worker or chi web restart, with no re-install) and
+          their sha256 isn't checked, for this bundle only. Its memories are copied; re-install with --force to
+          pick up memory edits. Upgrade refuses it; uninstall removes the link, never PATH's files.
     TEXT
     UPGRADE_HELP = "Usage: chi bundle upgrade <source> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]"
     UNINSTALL_HELP = "Usage: chi bundle uninstall <bundle> [--scope system|project] [--force]"
@@ -108,6 +117,19 @@ module Samagotchi
         --set KEY=VALUE  a setting for the load (config.yml bundles: <name>: KEY), repeatable
         Exit status: 0 no errors, 1 errors, 2 usage.
     TEXT
+    TRY_HELP = <<~TEXT
+      Usage: chi bundle try PATH -p TEXT [--model NAME] [--memory NAME] [--mute NAME] [--toolkit NAME]
+             [--thinking LEVEL] [--set KEY=VALUE] [--json] [--keep] [--timeout SECONDS]
+
+        Install PATH and run one non-interactive turn in an isolated temporary config, state and work directory.
+        The user's hosts, keys and ordinary runtime settings are retained; their bundles, hooks, guardrails,
+        memories, prompt additions, sessions and attached context sources are not. Shipped guardrails and a
+        $1 cost cap are installed for the run. --set KEY=VALUE sets the tried bundle's config.yml bundles entry;
+        --set cost-cap.cap=N overrides the cap (unlike chi --set BUNDLE.KEY=VALUE, these are config settings).
+        --memory and --mute accept comma-separated names and repeat. --keep retains the sandbox and debug log.
+        --json prints the experimental machine-readable trace.
+        Exit status: child turn's status; 1 on install failure or timeout; 2 for usage; 130 on Ctrl-C.
+    TEXT
 
     # The subcommands' flags: --help only; a word not starting with -- is
     # a positional (install's source, -h included). --scope takes whatever
@@ -115,8 +137,12 @@ module Samagotchi
     INSTALL_FLAGS = CLI::Flags.new(help: %w[--help], flag_pattern: /\A--/) do |f|
       f.value "--scope"
       f.switch "--force"
+      f.switch "--dev"
+    end
+    UNINSTALL_FLAGS = CLI::Flags.new(help: %w[--help], flag_pattern: /\A--/) do |f|
+      f.value "--scope"
+      f.switch "--force"
     end
-    UNINSTALL_FLAGS = INSTALL_FLAGS
     UPGRADE_FLAGS = CLI::Flags.new(help: %w[--help], flag_pattern: /\A--/) do |f|
       f.value "--scope"
       f.switch "--force"
@@ -135,6 +161,19 @@ module Samagotchi
       f.switch "--fix"
       f.value "--set", key: :set, repeat: true
     end
+    TRY_FLAGS = CLI::Flags.new(help: %w[--help], flag_pattern: /\A-/) do |f|
+      f.value "-p", "--prompt", key: :prompt
+      f.value "--model"
+      f.value "--memory", repeat: true
+      f.value "--mute", repeat: true
+      f.value "--toolkit"
+      f.value "--thinking"
+      f.value "--set", repeat: true
+      f.switch "--json"
+      f.switch "--keep"
+      f.value "--timeout"
+      f.refuse "--attach", "--shared", "chi bundle try can't use --attach or --shared"
+    end
     TRASH_FLAGS = CLI::Flags.new(help: %w[--help], flag_pattern: /\A--/) do |f|
       f.switch "--empty"
       f.switch "--dry-run"
@@ -169,8 +208,9 @@ module Samagotchi
       when "new" then new_bundle(@argv[1..])
       when "test" then test_bundle(@argv[1..])
       when "check" then check(@argv[1..])
+      when "try" then try_bundle(@argv[1..])
       else
-        @stderr.puts "Unknown bundle subcommand: #{sub}. Use: install, upgrade, uninstall, status, diff, list, build, trash, new, test, check"
+        @stderr.puts "Unknown bundle subcommand: #{sub}. Use: install, upgrade, uninstall, status, diff, list, build, trash, new, test, check, try"
         CLI::Exit::USAGE
       end
     end
@@ -185,11 +225,21 @@ module Samagotchi
       source = parsed.args.last
       scope = opts[:scope]
       force = opts.fetch(:force, false)
+      dev = opts.fetch(:dev, false)
       if source.nil? || source.empty?
         @stderr.puts "Usage: chi bundle install <source> [--scope system|project] [--force]"
         return CLI::Exit::USAGE
       end
-      expanded_source = expand_source(source)
+      if dev && (Samagotchi::MemoryBundle::SourceNormalizer.git_url?(source) || !File.directory?(source))
+        @stderr.puts "chi bundle install --dev takes a local directory (the bundle's source), not #{source}"
+        return CLI::Exit::USAGE
+      end
+      expanded_source = dev ? File.realpath(source) : expand_source(source)
+      if dev && File.dirname(expanded_source) == File.realpath(Samagotchi::MemoryBundle::SourceNormalizer::SHIPPED_DIR)
+        @stderr.puts "chi bundle install --dev cannot be used with chi-shipped bundles or profiles; " \
+                     "use chi bundle install #{File.basename(expanded_source)} instead"
+        return CLI::Exit::USAGE
+      end
       if Samagotchi::MemoryBundle::Profile.shipped_meta?(expanded_source)
         return install_profile(expanded_source, scope: scope, force: force, dry_run: false, word: "Install")
       end
@@ -198,7 +248,7 @@ module Samagotchi
       return 1 unless prepared
       return 1 if installed_under_another_name?(expanded_source, bundle_name, prepared, "Install")
 
-      installer = installer_for(expanded_source, bundle_name, prepared: prepared, scope: scope, force: force)
+      installer = installer_for(expanded_source, bundle_name, prepared: prepared, scope: scope, force: force, dev: dev)
       run_installer(installer, failed: "Install") do |manifest|
         print_hooks_and_plugin(manifest)
         print_provenance(bundle_name, manifest)
@@ -457,7 +507,7 @@ module Samagotchi
           @stdout.puts "Bundle '#{name}' not installed."
           return 0
         end
-        @stdout.puts "Bundle: #{name} v#{st[:provenance].version} scope=#{status_scope(st)} installed=#{st[:provenance].installed_at}"
+        @stdout.puts "Bundle: #{name} v#{st[:provenance].version}#{dev_label(st[:provenance])} scope=#{status_scope(st)} installed=#{st[:provenance].installed_at}"
         if st[:scope_error]
           @stdout.puts "Target: (unknown scope: this chi can't resolve it; upgrade chi or reinstall the bundle)"
         else
@@ -519,12 +569,19 @@ module Samagotchi
           plugin_info = plugin ? " plugin=#{plugin[:file]}" : ""
           includes = st[:provenance].includes
           includes_info = includes ? " includes=#{includes.join(",")}" : ""
-          @stdout.puts "  #{bname} v#{st[:provenance].version} scope=#{status_scope(st)} files=#{st[:files].size}#{hook_info}#{plugin_info}#{includes_info} issues=#{mods}"
+          @stdout.puts "  #{bname} v#{st[:provenance].version}#{dev_label(st[:provenance])} scope=#{status_scope(st)} files=#{st[:files].size}#{hook_info}#{plugin_info}#{includes_info} issues=#{mods}"
         end
       end
       0
     end
 
+    # " dev → /path (missing)" when a dev install's source isn't there, else "".
+    def dev_label(record)
+      return "" unless record.dev
+
+      " dev → #{record.source}#{" (missing)" unless File.directory?(record.source)}"
+    end
+
     # "team (unknown)" for a scope this chi can't resolve (Status#bundle_status).
     def status_scope(st) = st[:scope_error] ? "#{st[:scope]} (unknown)" : st[:scope]
 
@@ -844,7 +901,7 @@ module Samagotchi
       parsed = parse_flags(CHECK_FLAGS, rest, "check", help: CHECK_HELP)
       return parsed if parsed.is_a?(Integer)
 
-      settings = check_settings(parsed.options.fetch(:set, [])) or return CLI::Exit::USAGE
+      settings = check_settings(parsed.options.fetch(:set, []), label: "check") or return CLI::Exit::USAGE
       if parsed.args.size > 1
         @stderr.puts "chi bundle check takes one PATH (#{parsed.args.join(" ")})"
         return CLI::Exit::USAGE
@@ -858,14 +915,163 @@ module Samagotchi
       Check.new(dir, fix: parsed.options.fetch(:fix, false), settings: settings, stdout: @stdout).run
     end
 
+    def try_bundle(rest)
+      parsed = parse_flags(TRY_FLAGS, rest, "try", help: TRY_HELP)
+      return parsed if parsed.is_a?(Integer)
+
+      options = parsed.options
+      if options[:prompt].nil? || parsed.args.size != 1
+        @stderr.puts "Usage: chi bundle try PATH -p TEXT [options]"
+        return CLI::Exit::USAGE
+      end
+      path = parsed.args.first
+      unless File.directory?(path)
+        @stderr.puts "chi bundle try: #{path} isn't a folder"
+        return CLI::Exit::USAGE
+      end
+      if options.values_at(:model, :toolkit, :thinking, :memory, :mute).flatten.compact.any?(&:empty?)
+        @stderr.puts "chi bundle try: model, toolkit, thinking, memory and mute values cannot be empty"
+        return CLI::Exit::USAGE
+      end
+      require_relative "thinking"
+      if options[:thinking] && !Thinking::LEVELS.map(&:to_s).include?(options[:thinking])
+        @stderr.puts "chi bundle try: --thinking takes #{Thinking::LEVELS.join(", ")}, not #{options[:thinking]}"
+        return CLI::Exit::USAGE
+      end
+
+      timeout = parse_try_timeout(options[:timeout])
+      return CLI::Exit::USAGE unless timeout
+
+      set_pairs = []
+      cost_cap = 1
+      cost_cap_override = false
+      require_relative "bundle_session_settings"
+      Array(options[:set]).each do |pair|
+        key, sep, value = pair.partition("=")
+        if sep.empty?
+          @stderr.puts "chi bundle try: --set takes KEY=VALUE, not #{pair}"
+          return CLI::Exit::USAGE
+        end
+        if key == "cost-cap.cap"
+          cost_cap = BundleSessionSettings.typed(value)
+          cost_cap_override = true
+          unless (cost_cap.is_a?(Numeric) && cost_cap >= 0) || cost_cap == false
+            @stderr.puts "chi bundle try: --set cost-cap.cap takes a non-negative number or off"
+            return CLI::Exit::USAGE
+          end
+        else
+          set_pairs << pair
+        end
+      end
+      settings = check_settings(set_pairs, label: "try")
+      return CLI::Exit::USAGE unless settings
+
+      require_relative "bundle_command/try/sandbox"
+      require_relative "bundle_command/try/run"
+      require_relative "bundle_command/try/trace"
+      sandbox = nil
+      begin
+        sandbox = Try::Sandbox.new(path, bundle_settings: settings, cost_cap: cost_cap,
+                                   cost_cap_override: cost_cap_override)
+        sandbox.install
+        result = Try::Run.new(sandbox).run(prompt: options[:prompt], options: options, timeout: timeout)
+        trace = Try::TraceReader.new(state_home: sandbox.state_home, session_id: result.session_id)
+                              .read(exit_code: result.exit_status, answer: result.stdout, stderr: result.stderr,
+                                    sandbox: options[:keep] ? sandbox.root : nil)
+        render_try_trace(trace, json: options[:json], child_stderr: result.stderr)
+        @stderr.puts "chi bundle try: timed out after #{timeout} seconds" if result.timed_out
+        result.exit_status
+      rescue Try::Sandbox::Error => e
+        @stderr.puts e.message
+        e.status
+      ensure
+        report_try_sandbox(sandbox) if options[:keep] && sandbox
+        sandbox&.cleanup unless options[:keep]
+      end
+    end
+
+    def render_try_trace(trace, json:, child_stderr:)
+      error_lines = child_stderr.lines.reject { |line| line.start_with?("Session: ") }
+      @stderr.write(error_lines.join)
+      if json
+        render_trace_lines(trace, @stderr, include_answer: false)
+        @stdout.puts JSON.generate(trace.to_h.transform_keys(&:to_s))
+      else
+        render_trace_lines(trace, @stdout, include_answer: true)
+      end
+    end
+
+    def report_try_sandbox(sandbox)
+      @stderr.puts "sandbox: #{sandbox.root}"
+      @stderr.puts "debug log: #{File.join(sandbox.state_home, "samagotchi", "samagotchi.log")}"
+    end
+
+    def render_trace_lines(trace, output, include_answer:)
+      output.puts "tools:"
+      trace.tools.each do |tool|
+        output.puts format("  %d %-16s %-7s %dms  %s", tool[:index], tool[:name], tool[:status],
+                           tool[:duration_ms], JSON.generate(tool[:args].to_s[0, 60]))
+      end
+      trace.notices.each { |notice| output.puts "notices: [#{notice["hook"] || "hook"}] #{notice["text"]}" }
+      trace.cards.each do |card|
+        output.puts "card: #{[card["title"], card["body"]].compact.join(" — ")}"
+      end
+      trace.questions.each do |entry|
+        question = entry.dig("pending_question", "question").to_s
+        outcome = if entry["cancelled"] && entry["reason"] == "non_interactive"
+                    "unanswerable (non_interactive)"
+                  elsif entry["cancelled"]
+                    "cancelled (#{entry["reason"]})"
+                  elsif entry["answer"]
+                    "answered"
+                  else
+                    "unanswered"
+                  end
+        output.puts "questions: #{JSON.generate(question)} -> #{outcome}"
+      end
+      if trace.interactive_blocked
+        count = trace.denied.size + trace.questions.count { |question| question["cancelled"] && question["reason"] == "non_interactive" }
+        output.puts "warn: #{count} question(s)/call(s) couldn't be answered"
+      end
+      if include_answer
+        answer_lines = trace.answer.lines
+        output.puts "answer:"
+        answer_lines.first(10).each { |line| output.puts "  #{line.chomp}" }
+        output.puts "  … (truncated)" if answer_lines.size > 10
+      end
+      tokens = trace.tokens
+      prompt = tokens[:prompt] || "unknown"
+      completion = tokens[:completion] || "unknown"
+      cost = if trace.cost
+               "#{"~" if trace.cost_is_estimate}$#{format("%.4f", trace.cost)}"
+             else
+               "unknown"
+             end
+      output.puts "tokens: #{prompt} in / #{completion} out  cost #{cost}  exit #{trace.exit_code}" \
+                  "#{"  (#{trace.session_id})" if trace.session_id}"
+    end
+
+    def parse_try_timeout(value)
+      return 300 unless value
+
+      timeout = Float(value)
+      return timeout if timeout.positive? && timeout.finite?
+
+      @stderr.puts "chi bundle try: --timeout must be a positive number"
+      nil
+    rescue ArgumentError
+      @stderr.puts "chi bundle try: --timeout must be a positive number"
+      nil
+    end
+
     # --set KEY=VALUE values as typed (BundleSessionSettings.typed), or nil
     # after saying what's wrong.
-    def check_settings(pairs)
+    def check_settings(pairs, label:)
       require_relative "bundle_session_settings"
       pairs.each_with_object({}) do |pair, out|
         key, sep, value = pair.partition("=")
         unless !sep.empty? && key.match?(BundleSessionSettings::KEY)
-          @stderr.puts "chi bundle check: --set takes KEY=VALUE, not #{pair}"
+          @stderr.puts "chi bundle #{label}: --set takes KEY=VALUE, not #{pair}"
           return nil
         end
         out[key] = BundleSessionSettings.typed(value)

data/lib/samagotchi/bundle_session_settings.rb

@@ -176,6 +176,8 @@ module Samagotchi
       file = File.join(dir, name, "plugin", bundle.plugin.file.to_s)
       return "the file is missing" unless File.file?(file)
 
+      return nil if MemoryBundle::Provenance.unchecked?(bundle.plugin.sha256)
+
       expected = MemoryBundle::Provenance.recorded_sha(bundle.plugin.sha256)
       return "no sha256 recorded for it (reinstall the bundle)" if expected.empty?
 

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.87.0
+version: 0.89.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/child_reports.rb

@@ -130,7 +130,13 @@ module Samagotchi
     # (DelegateWait.finish, its report variant), the cursor it moves the child to,
     # and the cursor it was read from (a commit after the model moved it
     # itself, with delegate_result, leaves it alone).
-    Report = Data.define(:child_id, :text, :before, :after, :rings, :claim_id) do
+    # +relay+: the child's question when it goes to the parent's user
+    # (Tools::DelegateRelay.relay?): #resolve relays it on the turn thread
+    # and gives the report its outcome line; +text+ is the question's
+    # report until then (what a parent with no relay gets).
+    Report = Data.define(:child_id, :text, :before, :after, :rings, :claim_id, :relay) do
+      def initialize(relay: nil, **) = super
+
       def line(mark: nil) = Steer::Line.new(text: text, source: ChildReports::SOURCE, mark: mark)
       def origin = { client_id: "#{ClientId::CHILD_PREFIX}#{child_id[0, 8]}" }
     end
@@ -146,14 +152,19 @@ module Samagotchi
       Tools::DelegateCursors.clear_report_claims(@session_id, state_dir: @state_dir)
       # child id → the Report this turn took for it (rings merged).
       @taken = {}
+      # child id → the question id whose relay card a Stop closed (#hold_back).
+      @held = {}
     end
 
+    # The user's next input: questions held back after a Stop are offered again.
+    def release_holds = @held.clear
+
     # Whether a ring this turn hasn't taken waits (the idle loop's check).
     def waiting?
       return false if ChildRing.mode == "off"
 
       taken = taken_rings
-      ring_files.any? { |file| !taken.include?(file) }
+      ring_files.any? { |file| !taken.include?(file) && !held?(file) }
     end
 
     # The reports for rings this turn hasn't taken yet, recorded as taken.
@@ -164,7 +175,7 @@ module Samagotchi
       return [] if ChildRing.mode == "off"
 
       taken = taken_rings
-      fresh = ring_files.reject { |file| taken.include?(file) }
+      fresh = ring_files.reject { |file| taken.include?(file) || held?(file) }
       by_child = fresh.group_by { |file| SessionInbox.read_ring(file)&.dig(:child_id) }
       by_child.filter_map do |child_id, rings|
         report = child_id && report_for(child_id, rings)
@@ -207,8 +218,79 @@ module Samagotchi
       @taken = {}
     end
 
+    # A report whose question goes to the parent's user, settled: relayed
+    # through +relay+ (DelegateRelay.call: blocks until the card is
+    # answered, closed or the turn stopped) and given the outcome line as
+    # its text. Runs on the turn thread, before the boundary merges it.
+    # The child's question answered since the ring was taken opens no card;
+    # nor does one already answered on a relay (RelayDesk#settled?).
+    # @param relay [#open_question, #relay_desk, nil] Engine#relay_peer;
+    #   nil: the report's question text, as without P4's relay
+    # @return [Report, nil] nil when the parent's turn was stopped with the
+    #   card open: the report is released (its ring and the cursor stay), so
+    #   the next turn offers it again
+    def resolve(report, relay:)
+      return report unless report.relay
+      return report.with(relay: nil) unless relay
+
+      question = report.relay
+      what = question.header.to_s.empty? ? question.hook.to_s : question.header.to_s
+      line = if Session.load(report.child_id, state_dir: @state_dir).pending_question&.id.to_s != question.id.to_s
+               Tools::DelegateRelay.line(what, "answered on the child", hook: true)
+             elsif relay.relay_desk.settled?(report.child_id, question.id)
+               Tools::DelegateRelay.line(what, "answered on a relay already; it waits for the user on the child", hook: true)
+             else
+               outcome = Tools::DelegateRelay.call(report.child_id, question, relay: relay, state_dir: @state_dir)
+               return hold_back(report) if outcome.stopped
+
+               outcome.line
+             end
+      resolved = report.with(relay: nil, text: relayed_text(report.child_id, line))
+      @taken[report.child_id] = resolved if @taken[report.child_id]&.claim_id == report.claim_id
+      resolved
+    rescue ArgumentError => e
+      # The child is gone (or a bug): its question's report, as without a relay.
+      Log.info(:worker, "delegate_relay_unresolved", child: report.child_id[0, 8], error: e.message)
+      report.with(relay: nil)
+    end
+
+    # A relay report the parent's turn stopped on, or one behind it in the
+    # same take: released (its ring and the cursor stay) and held back, so
+    # no wake turn offers that question again until the user's next input
+    # (#release_holds); other children's rings go on.
+    # @return [nil]
+    def hold_back(report)
+      @held[report.child_id] = report.relay.id.to_s
+      release_report(report)
+    end
+
     private
 
+    # A ring of a child whose held-back question still waits.
+    def held?(file)
+      child_id = SessionInbox.read_ring(file)&.dig(:child_id)
+      question_id = @held[child_id] or return false
+      Session.load(child_id, state_dir: @state_dir).pending_question&.id.to_s == question_id
+    rescue ArgumentError
+      false
+    end
+
+    # A relayed question's report: the outcome line, then the next reply's
+    # promise (as a report's question text ends).
+    def relayed_text(child_id, line)
+      Tools::DelegateWait.result(child_id, "question", "#{line}\n#{Tools::DelegateWait::REPORT_NEXT_REPLY}")
+    end
+
+    # One taken report back: its cursor claim goes, its rings stay untaken.
+    # @return [nil]
+    def release_report(report)
+      @taken.delete(report.child_id)
+      Tools::DelegateCursors.update(@session_id, report.child_id, state_dir: @state_dir) do |cursor|
+        cursor.report_claim&.fetch("id", nil) == report.claim_id ? cursor.with(report_claim: nil) : cursor
+      end
+      nil
+    end
+
     def taken_rings
       @taken.values.flat_map(&:rings)
     end
@@ -260,22 +342,33 @@ module Samagotchi
       # a later wait on it would repeat its reply.
       after = after.with(report_claim: claim)
       text = Tools::DelegateWait.finish(wait, child_id, timeout: 0, report: true)
-      Report.new(child_id: child_id, text: text, before: before, after: after, rings: rings, claim_id: claim_id)
+      Report.new(child_id: child_id, text: text, before: before, after: after, rings: rings, claim_id: claim_id,
+                 relay: relay?(wait) ? wait.question : nil)
     rescue ArgumentError
       nil # the child is gone
     end
 
     # A reply, a turn that left none, a crash, or a question the parent's
-    # model decides (its own ask_user_question, the step-limit continue).
-    # Approvals and hooks' questions are the user's, on the child's card.
+    # model decides (its own ask_user_question, the step-limit continue, a
+    # hook's question). Approvals are the user's (the relay, while the
+    # parent waits; else on the child's card).
     def reportable?(wait)
       case wait.status
       when :done, :no_reply, :error then true
-      when :waiting_for_answer then [nil, "", "continue"].include?(wait.question&.kind&.to_s)
+      when :waiting_for_answer then REPORTED_KINDS.include?(wait.question&.kind&.to_s)
       else false
       end
     end
 
+    REPORTED_KINDS = [nil, "", "continue", Tools::DelegateRelay::HOOK_KIND].freeze
+
+    # Whether the child's question goes to this parent's user rather than
+    # its model (Tools::DelegateRelay.relay?, under the child's strategy).
+    def relay?(wait)
+      wait.status == :waiting_for_answer && wait.question.kind.to_s == Tools::DelegateRelay::HOOK_KIND &&
+        Tools::DelegateRelay.relay?(wait.question, strategy: Guardrails::ParentPolicy.for_session(wait.session))
+    end
+
     def delete_rings(rings)
       rings.each { |file| FileUtils.rm_f(file) }
     end