samagotchi 0.33.0 → 0.34.0

data/lib/samagotchi/steer_cut.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+require_relative "steer"
+require_relative "generation_phase"
+require_relative "waiting_steer"
+
+module Samagotchi
+  # A message for the running turn cutting the generation it came during:
+  # what the generation streams (GenerationPhase, fed by #observe from the
+  # turn's stream) and a message that came too early to cut (WaitingSteer).
+  # The Engine's seam: Bridge and TerminalUI call Engine#cut_for_steer and
+  # #input_epoch, the turn thread feeds #observe and #delivered!, and the
+  # turn's end calls #finished!. Callable from any thread: GenerationPhase
+  # and WaitingSteer hold their own locks.
+  class SteerCut
+    # A chunk's thinking and text. A chunk without the lanes (no loop of
+    # ours sends one) counts as text.
+    def self.lanes(event)
+      text = event.key?(:text) ? event[:text] : event[:content]
+      { thinking: event[:thinking].to_s, text: text.to_s }
+    end
+
+    # +clock+: monotonic seconds; +controller+: the running turn's cancel
+    # controller (nil between turns), read only when a cut is due.
+    def initialize(clock:, controller:)
+      # What the running generation streams: whether a steer may cut it.
+      @phase = GenerationPhase.new(clock: clock)
+      # A message that may cut it but came too early: it cuts later.
+      @waiting = WaitingSteer.new
+      @controller = controller
+    end
+
+    # A message for the running turn from +source+ (Steer.source_for_client:
+    # nil for the user, "chi_send", "parent_agent") cuts the streaming
+    # generation when it has streamed only thinking for steer.cut_after
+    # seconds (GenerationPhase): the loops' cut path (CutPolicy) then starts
+    # the step again with the message, no nudge, no retry spent. Too early,
+    # the message waits (WaitingSteer) and cuts once the thinking passes it
+    # (#recheck, on each thinking chunk), unless a boundary hands it to the
+    # model first. A plugin's message never cuts, nor an unknown client's
+    # (automatic:<id>).
+    # Call it after the message is queued, with the #input_epoch read
+    # before queueing it. Outside any lock; a cut that lands just after the
+    # generation ended is harmless (the loop re-asks).
+    # @return [Boolean] whether a generation was cut now
+    def cut_for_steer(source, epoch: nil)
+      return false unless Steer.cuts?(source)
+
+      after = Config.get("steer.cut_after").to_i
+      return false unless after.positive?
+
+      ctrl = @controller.call
+      return false unless ctrl
+      return cut!(ctrl, source.to_s) if @phase.cuttable?(after)
+
+      Log.info(:turn, "steer_cut_waits", source: source.to_s) if @waiting.wait!(source, epoch: epoch)
+      false
+    rescue StandardError
+      false
+    end
+
+    # The drains that took input so far (WaitingSteer#epoch): read it before
+    # queueing a message for #cut_for_steer.
+    def input_epoch
+      @waiting.epoch
+    end
+
+    # The turn's stream: the generation's phase follows it, and a thinking
+    # chunk rechecks a waiting message. +progress+: a chunk's lanes
+    # (.lanes), read from it when not given.
+    def observe(event, progress = nil)
+      case event[:type]
+      when :generation_started then @phase.started!
+      when :generation_chunk
+        progress ||= self.class.lanes(event)
+        @phase.chunk!(**progress, tool_call: event[:tool_call])
+        recheck unless progress[:thinking].empty?
+      when :generation_retrying then @phase.retrying!
+      when :generation_completed, :generation_cancelled then @phase.finished!
+      end
+    end
+
+    # The turn's input went to the model: a message that waited to cut is in.
+    def delivered!
+      @waiting.delivered!
+    end
+
+    # The turn ended: no generation, nothing waiting.
+    def finished!
+      @phase.finished!
+      @waiting.clear!
+    end
+
+    private
+
+    # A thinking chunk streamed: a waiting message cuts once the thinking
+    # passes steer.cut_after.
+    def recheck
+      return unless @waiting.waiting?
+
+      after = Config.get("steer.cut_after").to_i
+      return unless after.positive? && @phase.cuttable?(after)
+
+      source = @waiting.take
+      ctrl = @controller.call
+      cut!(ctrl, source, waited: true) if source && ctrl
+    rescue StandardError
+      nil
+    end
+
+    def cut!(ctrl, source, waited: false)
+      age = @phase.age
+      cut = ctrl.cancel_generation!(:steer, { by: "steer", steer: true, source: source, reason: "a new message" })
+      if cut
+        @waiting.clear!
+        fields = { source: source, age: age&.round(1) }
+        fields[:waited] = true if waited
+        Log.info(:turn, "steer_cut", **fields)
+      end
+      cut
+    end
+  end
+end

data/lib/samagotchi/system_prompt.rb

@@ -195,7 +195,7 @@ module Samagotchi
           6. Use write for full-file rewrites or creating new files.
 
         Memory convention:
-          Project scope: one folder per git repository, shared by its worktrees and subdirectories (its path is on the "Project memories folder:" line below)
+          Project scope: one folder per git repository, shared by its worktrees and subdirectories (its path is on the "Project memories folder" line below)
           System scope:  ~/.config/samagotchi/memories/ (cross-project)
           memory_read accepts optional scope (project|system).
           memory_write requires explicit scope and entry name.
@@ -413,21 +413,33 @@ module Samagotchi
         .find { |path| File.file?(path) }
     end
 
-    # Where the session runs and which project memory folder it uses. The root
-    # line appears only when it differs from the cwd (a worktree or subdir).
+    # Where the session runs and which project memory folder it uses. Only
+    # this checkout is named: its top (at its root too, so a model doesn't
+    # take the memories folder for the project and cd there, Qwen
+    # 2026-10-06), and in a linked worktree a line that work stays in it. The repository's main
+    # checkout (MemoryPaths.project_root, which scopes memories and session
+    # lists) is never shown: a model told its path went to work there
+    # (a worktree child committed onto main, 2026-10-03 and 2026-10-06).
     # The home directory is spelled out once so the model copies the right
     # sequence, with the advice to write it as ~ or $HOME instead.
     def project_location
       cwd = Dir.pwd
-      root = MemoryPaths.project_root(cwd)
+      top = MemoryPaths.work_tree_root(cwd)
       lines = ["Current working directory:", cwd]
-      unless root == cwd
-        lines << "Project root (only where shared project memories come from; read, edit, run and commit in the current working directory above):"
-        lines << root
+      if top && top != cwd
+        lines << "Top of this checkout (where the project's commands run from; stay inside it):"
+        lines << top
+      elsif top
+        lines << "This checkout (the project's files; its commands run here):"
+        lines << top
+      end
+      if top && MemoryPaths.project_root(cwd) != top
+        lines << "This checkout is a linked git worktree: read, edit, run and commit only in it, never in the " \
+                 "repository's other checkouts."
       end
       home = Dir.home
       lines << "Home directory: #{home} (write it as ~ or $HOME in commands and paths)" unless home.to_s.empty?
-      lines << "Project memories folder:"
+      lines << "Project memories folder (your notes about the project, not its files; never work or run commands there):"
       lines << home_relative(Tools::MemoryRead.memories_dir("project"))
       lines.join("\n")
     rescue StandardError

data/lib/samagotchi/tool_declarations.rb

@@ -351,7 +351,7 @@ module Samagotchi
       },
       {
         name: "delegate",
-        description: "Hand a task to a child chi session that runs in parallel in this folder and returns only its final reply (its trace stays out of this context). The child is a normal session: it shows in the lists as a child of this one and the user can attach to it. With session, send a follow-up to one of this session's children instead. A tool call the child needs approved goes to your user as one of your own approvals; you only see how it was answered, as a line in the result. Children keep running if this turn is canceled. With wait false, chi brings each child's reply to you by itself when the child ends its turn (a delegate report, also when you are idle): don't poll it with delegate_result. To retry or redirect a child, use delegate with its session (task_* tools are for background commands, not sessions). A child stays until stopped: once its work is done, stop it with execute `chi sessions stop ID` (a follow-up with session wakes it again).",
+        description: "Hand a task to a child chi session that runs in parallel in this folder, or in cwd, and returns only its final reply (its trace stays out of this context). The child is a normal session: it shows in the lists as a child of this one and the user can attach to it. With session, send a follow-up to one of this session's children instead. A tool call the child needs approved goes to your user as one of your own approvals; you only see how it was answered, as a line in the result. Children keep running if this turn is canceled. Use wait false unless this turn can't go on without the reply: the call returns at once, you end your turn or keep working with your user, and chi brings the child's reply to you by itself as a delegate report when the child ends its turn, starting a turn for it if you are idle. After wait false don't call delegate_result for that child, not to check on it and not before ending your turn. To retry or redirect a child, use delegate with its session (task_* tools are for background commands, not sessions). A child stays until stopped: once its work is done, stop it with execute `chi sessions stop ID` (a follow-up with session wakes it again).",
         parameters: {
           type: "object",
           properties: {
@@ -367,13 +367,17 @@ module Samagotchi
               type: "string",
               description: "A child's id or prefix: send the task there as a follow-up instead of starting a new child"
             },
+            cwd: {
+              type: "string",
+              description: "The new child's working folder: a worktree or subfolder of this session's repository (create a worktree with execute `git worktree add ../<repo>-<name> -b <branch>` first). Default: this session's folder"
+            },
             wait: {
               type: "boolean",
-              description: "Wait for the reply (default true); false returns at once so several children can run side by side"
+              description: "true (default): this call waits for the reply; pick it only when this turn needs the reply to go on. false: returns at once and the reply comes later as a delegate report (also when you are idle); pick it for work that takes minutes, several children side by side, or to keep talking with your user"
             },
             timeout: {
               type: "integer",
-              description: "Maximum seconds to wait (default: 600; 0 checks once without waiting); a timed-out child keeps running"
+              description: "Maximum seconds to wait (default: 600; 0 checks once without waiting); a timed-out child keeps running and its reply still comes as a delegate report"
             }
           },
           required: ["task"]
@@ -381,7 +385,7 @@ module Samagotchi
       },
       {
         name: "delegate_result",
-        description: "Wait for a delegated child session's next reply: the child named, or this session's newest running child (name the child when a delegate report is about it). A delegate report already carries the reply: don't call this for it. Returns early if the child waits for a question the user must answer. A tool call the child needs approved goes to your user while this waits; the result says how it was answered.",
+        description: "Wait for a delegated child session's next reply, only when this turn can't go on without it: the child named, or this session's newest running child (name the child when a delegate report is about it). After delegate with wait false you don't need this: chi brings each child's reply by itself as a delegate report, also when you are idle, so end your turn or keep working instead of waiting here. A delegate report already carries the reply: don't call this for it. Returns early if the child waits for a question the user must answer. A tool call the child needs approved goes to your user while this waits; the result says how it was answered.",
         parameters: {
           type: "object",
           properties: {
@@ -391,7 +395,7 @@ module Samagotchi
             },
             timeout: {
               type: "integer",
-              description: "Maximum seconds to wait (default: 600; 0 checks once without waiting)"
+              description: "Maximum seconds to wait (default: 600; 0 checks once without waiting); on a timeout the child keeps running and its reply comes as a delegate report"
             }
           }
         }

data/lib/samagotchi/tools/builtins.rb

@@ -98,8 +98,8 @@ module Samagotchi
           ContextRead.call(call[:content], offset: call[:offset], limit: call[:limit], peers: kctx.peers)
         end,
         Delegate::NAME => lambda do |call, kctx|
-          Delegate.call(call[:content], model: call[:model], session: call[:session], wait: call[:wait],
-                                        timeout: call[:timeout], peers: kctx.peers)
+          Delegate.call(call[:content], model: call[:model], session: call[:session], cwd: call[:cwd],
+                                        wait: call[:wait], timeout: call[:timeout], peers: kctx.peers)
         end,
         DelegateResult::NAME => lambda do |call, kctx|
           DelegateResult.call(call[:content], session: call[:session], timeout: call[:timeout], peers: kctx.peers)

data/lib/samagotchi/tools/delegate.rb

@@ -4,6 +4,7 @@ require_relative "../client_id"
 require_relative "../session"
 require_relative "../config"
 require_relative "../model_profile"
+require_relative "../memory_paths"
 require_relative "peers"
 require_relative "delegate_wait"
 require_relative "../child_reports"
@@ -15,7 +16,8 @@ module Samagotchi
 
   module Tools
     # Hand a task to a child session: an ordinary chi session in its own
-    # worker, started in this session's folder with the task as its first
+    # worker, started in this session's folder (or cwd:, a worktree or
+    # subfolder of the same repository) with the task as its first
     # user message and the `delegated` system memory preloaded. It shows in
     # every list as a child of this one and the user can attach to it. With
     # session:, a follow-up to a child that exists. Only the child's final
@@ -38,10 +40,11 @@ module Samagotchi
       # @param content [String] the task (the child's user message, verbatim)
       # @param model [String, nil] the child's model (an alias works); the parent's by default
       # @param session [String, nil] a child's id or prefix: send the task there instead
+      # @param cwd [String, nil] the new child's folder (child_cwd checks it); the parent's by default
       # @param wait [Boolean, String, nil] wait for the reply (default true)
       # @param timeout [Integer, String, nil] seconds to wait (default DelegateWait::TIMEOUT_DEFAULT)
       # @param peers [Peers, nil]
-      def self.call(content, model: nil, session: nil, wait: nil, timeout: nil, peers: nil)
+      def self.call(content, model: nil, session: nil, cwd: nil, wait: nil, timeout: nil, peers: nil)
         return "Error: this session's id is not known here" unless peers&.session_id
 
         task = content.to_s.strip
@@ -52,8 +55,11 @@ module Samagotchi
         wait = parse_wait(wait)
         timeout = parse_timeout(timeout)
 
+        cwd = cwd.to_s.strip
         child_id, warning = if session.to_s.strip.empty?
-                              start_child(task, parent: parent, model: model, state_dir: sd)
+                              start_child(task, parent: parent, model: model, cwd: cwd, state_dir: sd, peers: peers)
+                            elsif !cwd.empty?
+                              "Error: cwd starts a new child; a follow-up with session keeps the child's folder"
                             else
                               follow_up(task, session: session.to_s.strip, parent: parent, state_dir: sd)
                             end
@@ -63,35 +69,58 @@ module Samagotchi
         return note + DelegateWait.call(child_id, peers: peers, timeout: timeout) if wait
 
         started = session.to_s.strip.empty? ? "Started a delegate session" : "Sent the follow-up to delegate #{child_id[0, 8]}"
-        "#{note}session: #{child_id}\nstatus: running\n#{started}; #{running_hint} " \
+        "#{note}session: #{child_id}\nstatus: running\n#{started}; #{running_hint(peers)} " \
           "It shows in chi sessions list and the web as a child of this session; the user can attach to it."
       rescue ArgumentError => e
         "Error: #{e.message}"
       end
 
-      # How the reply of a child left running comes back.
-      def self.running_hint
-        return "delegate_result waits for its reply." if ChildRing.mode == "off"
-
-        "chi brings its reply to you by itself when it ends its turn (a delegate report); don't poll with delegate_result."
+      # How the reply of a child left running comes back: a report only
+      # reaches a parent that can get one (DelegateWait.reports_mode).
+      def self.running_hint(peers)
+        case DelegateWait.reports_mode(peers)
+        when "off" then "delegate_result waits for its reply."
+        when "queue"
+          "chi adds its reply to your next turn by itself (a delegate report; you aren't woken while idle); " \
+            "don't poll with delegate_result."
+        else
+          "chi brings its reply to you by itself when it ends its turn (a delegate report), starting a turn for it " \
+            "if you are idle. Don't wait for it with delegate_result, also not to collect several children's replies: " \
+            "tell your user what started and end your turn, or keep working."
+        end
       end
       private_class_method :running_hint
 
+      # What to do when session.max_children are running: a parent that
+      # gets reports ends its turn (a report frees a slot); one that
+      # doesn't (DelegateWait.reports_mode off) waits with delegate_result.
+      def self.full_hint(peers)
+        if DelegateWait.reports_mode(peers) == "off"
+          "delegate_result waits for one; `chi sessions stop ID` stops one."
+        else
+          "End your turn: a delegate report frees a slot when a child finishes; or stop one with `chi sessions stop ID`."
+        end
+      end
+      private_class_method :full_hint
+
       # @return [String] the new child's id, or an Error: line
-      def self.start_child(task, parent:, model:, state_dir:)
+      def self.start_child(task, parent:, model:, cwd:, state_dir:, peers:)
         if parent.parent_id
           return "Error: this session is a delegate of #{parent.parent_id}; delegated sessions don't delegate further"
         end
 
+        folder = child_cwd(cwd, parent)
+        return folder if folder.start_with?("Error:")
+
         running = running_children(parent.id, state_dir: state_dir)
         max = max_children
         if running.size >= max
           ids = running.map { |s| s[:short_id] }.join(", ")
           return "Error: #{running.size} delegate#{"s" if running.size != 1} of this session #{running.size == 1 ? "is" : "are"} running " \
-                 "(the most is #{max}, #{MAX_CHILDREN_KEY}): #{ids}. delegate_result waits for one; `chi sessions stop ID` stops one."
+                 "(the most is #{max}, #{MAX_CHILDREN_KEY}): #{ids}. #{full_hint(peers)}"
         end
 
-        child = SessionManager.spawn_session(prompt: task, working_directory: parent.working_directory,
+        child = SessionManager.spawn_session(prompt: task, working_directory: folder,
                                              model_name: child_model(model, parent), memories: CHILD_MEMORIES,
                                              parent_id: parent.id, delegate: true, state_dir: state_dir)
         DelegateWait.mark_started(parent.id, child, state_dir: state_dir)
@@ -99,6 +128,64 @@ module Samagotchi
       end
       private_class_method :start_child
 
+      # The new child's folder: the parent's, or +cwd+ (relative to the
+      # parent's) when it is a folder of the parent's repository, in any of
+      # its worktrees (one project_root, from the common git dir). Outside
+      # git only a subfolder of the parent's folder. Nothing is created
+      # here: the model makes a worktree with execute, where guardrails see it.
+      # @return [String] an absolute folder, or an Error: line
+      def self.child_cwd(cwd, parent)
+        base = parent.working_directory
+        return base if cwd.empty?
+
+        folder = File.expand_path(cwd, base)
+        return "Error: cwd #{folder} is not a folder (create the worktree first)" unless File.directory?(folder)
+
+        folder = File.realpath(folder)
+        unless same_repository?(folder, base)
+          return "Error: cwd must be a folder of this session's repository (a worktree or subfolder of it), not #{folder}"
+        end
+        if MemoryPaths.in_repo?(base) && !work_tree?(folder)
+          return "Error: cwd #{folder} is not in a work tree of this session's repository (a git dir, or a bare " \
+                 "repository's folder): give a worktree's folder or a subfolder of one"
+        end
+
+        folder
+      end
+      private_class_method :child_cwd
+
+      # A folder git works in: under a checkout's top (work_tree_root), not
+      # inside the git dir (.git, .git/objects, a bare layout's .bare), and
+      # one `git rev-parse` says is in a work tree (it says false in a bare
+      # layout's container too). Read-only; IO.popen, so a spec's
+      # Process.spawn stub doesn't catch it.
+      def self.work_tree?(folder)
+        return false unless MemoryPaths.work_tree_root(folder)
+
+        git_dir = MemoryPaths.git_dir(folder)
+        return false if git_dir && within?(folder, File.realpath(git_dir))
+
+        out = IO.popen(["git", "-C", folder, "rev-parse", "--is-inside-work-tree"], err: File::NULL, &:read)
+        out.strip == "true"
+      rescue SystemCallError
+        false
+      end
+      private_class_method :work_tree?
+
+      def self.within?(path, dir) = path == dir || path.start_with?("#{dir}/")
+      private_class_method :within?
+
+      def self.same_repository?(folder, base)
+        if MemoryPaths.in_repo?(base)
+          MemoryPaths.project_root(folder) == MemoryPaths.project_root(base)
+        else
+          within?(folder, File.realpath(base))
+        end
+      rescue SystemCallError
+        false
+      end
+      private_class_method :same_repository?
+
       # @return [String] the child's id, or an Error: line
       def self.follow_up(task, session:, parent:, state_dir:)
         id = Session.resolve_id(session, state_dir: state_dir)
@@ -147,7 +234,10 @@ module Samagotchi
         SessionManager.children_of(parent_id, state_dir: state_dir).select { |s| running?(s) }
       end
 
-      # busy (a worker runs its turn), or running with a worker on its way.
+      # busy (a worker runs its turn), or running with a worker on its way
+      # (ChildrenStatus asks it too).
+      # @param summary [Hash] a children_of row, or the same keys: busy,
+      #   status, live, updated_at
       def self.running?(summary)
         return true if summary[:busy]
         return false unless summary[:status] == Session::STATUS_RUNNING && !summary[:live]
@@ -156,7 +246,6 @@ module Samagotchi
       rescue ArgumentError
         false
       end
-      private_class_method :running?
 
       def self.max_children
         value = Integer(Config.get(MAX_CHILDREN_KEY), exception: false)

data/lib/samagotchi/tools/delegate_wait.rb

@@ -9,6 +9,10 @@ require_relative "delegate_relay"
 require_relative "delegate_cursor"
 
 module Samagotchi
+  # Loaded on first use: child_reports requires this file (a circular
+  # require otherwise).
+  autoload :ChildRing, File.expand_path("../child_reports", __dir__)
+
   module Tools
     # Waiting for a delegated session's next reply, shared by delegate and
     # delegate_result: ReplyWait in the tools' words, with the status words
@@ -58,6 +62,7 @@ module Samagotchi
         key = [peers.session_id, child_id]
         cancelled = -> { peers.cancelled? }
         relay = peers.respond_to?(:relay) ? peers.relay : nil
+        reports = reports_mode(peers)
         others = relay && others_for(peers.session_id, child_id, relay, sd)
         cursor = DelegateCursors.get(peers.session_id, child_id, state_dir: sd)
         baseline = cursor.baseline
@@ -72,12 +77,12 @@ module Samagotchi
           unless wait.status == :waiting_for_answer && DelegateRelay.relayable?(relay, wait.question)
             outcomes.concat(relayed_outcomes.delete(key) || [])
             advance(peers.session_id, child_id, wait, state_dir: sd)
-            return with_outcomes(finish(wait, child_id, timeout: timeout), outcomes)
+            return with_outcomes(finish(wait, child_id, timeout: timeout, reports: reports), outcomes)
           end
 
           outcome = DelegateRelay.call(child_id, wait.question, relay: relay, state_dir: sd, more: others&.count.to_i)
           outcomes << outcome.line
-          return with_outcomes(canceled_result(child_id), outcomes) if outcome.stopped
+          return with_outcomes(canceled_result(child_id, reports: reports), outcomes) if outcome.stopped
 
           # Wait on with the child as it is now: a turn that ends with no
           # reply after the relay still ends the wait, and the relayed
@@ -104,8 +109,26 @@ module Samagotchi
         text.sub(/\A(session: [^\n]*\nstatus: [^\n]*\n)/) { "#{::Regexp.last_match(1)}#{outcomes.join("\n")}\n" }
       end
 
-      def canceled_result(child_id)
-        result(child_id, "running", "wait canceled; the child keeps running; delegate_result #{child_id} waits again")
+      # How a child's reply reaches this parent when no wait takes it:
+      # "wake" (a delegate report, a turn of its own when idle), "queue" (a
+      # report at its next step or turn, no wake) or "off" (only
+      # delegate_result). Only a worker's session reads its children's rings
+      # (its Engine gives a relay); a REPL, a -p run or a scratch session
+      # never gets a report.
+      # @param peers [Peers]
+      # @return [String] "wake", "queue" or "off"
+      def reports_mode(peers)
+        return "off" unless peers.respond_to?(:relay) && peers.relay
+
+        ChildRing.mode
+      end
+
+      def canceled_result(child_id, reports: "off")
+        if reports == "off"
+          return result(child_id, "running", "wait canceled; the child keeps running; delegate_result #{child_id} waits again")
+        end
+
+        result(child_id, "running", "wait canceled; the child keeps running; chi brings its reply as a delegate report")
       end
 
       def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -135,8 +158,10 @@ module Samagotchi
       # @param wait [ReplyWait::Result]
       # @param report [Boolean] a delegate report's text (ChildReports), not
       #   the tool's: a question's last line says chi brings the next reply
+      # @param reports [String] #reports_mode: what a timeout, a cancel or
+      #   a question tells the model about the reply to come
       # @return [String]
-      def finish(wait, child_id, timeout:, report: false)
+      def finish(wait, child_id, timeout:, report: false, reports: "off")
         status = ParentReport.status(wait)
         case wait.status
         when :done
@@ -146,16 +171,16 @@ module Samagotchi
         when :stopped
           result(child_id, status, "the child was stopped (chi sessions stop); delegate with session: #{child_id} starts it again with a message")
         when :waiting_for_answer
-          result(child_id, status, waiting_text(child_id, wait.question, report: report))
+          result(child_id, status, waiting_text(child_id, wait.question, report: report, reports: reports))
         when :canceled
-          canceled_result(child_id)
+          canceled_result(child_id, reports: reports)
         when :no_reply
           result(child_id, status, "#{no_reply_text(wait, child_id)}; its session shows what happened")
         when :worker_gone
           result(child_id, status,
                  "the child's worker is gone (it stopped or crashed); delegate with session: #{child_id} starts it again with a message")
         else
-          timeout_result(child_id, timeout)
+          timeout_result(child_id, timeout, reports: reports)
         end
       end
 
@@ -191,10 +216,24 @@ module Samagotchi
         "session: #{child_id}\nstatus: #{status}\n#{text}"
       end
 
-      def timeout_result(child_id, timeout)
+      # The cursor didn't move (#advance), so the reply still comes as a
+      # delegate report when this parent can get one.
+      def timeout_result(child_id, timeout, reports: "off")
+        head = "no reply yet after #{timeout.to_i} s; the child keeps running."
+        if reports == "off"
+          return result(child_id, "running",
+                        "#{head} delegate_result #{child_id} waits again; chi --attach #{child_id} shows it.")
+        end
+
+        comes = if reports == "queue"
+                  "chi adds its reply to your turn at its next step, or to your next turn, as a delegate report " \
+                    "(you are not woken while idle)"
+                else
+                  "chi brings its reply here by itself as a delegate report when it ends its turn (also after you end yours)"
+                end
         result(child_id, "running",
-               "no reply yet after #{timeout.to_i} s; the child keeps running. delegate_result #{child_id} waits again; " \
-               "chi --attach #{child_id} shows it.")
+               "#{head} #{comes}, so carry on or end your turn. Only if this turn can't go on without it: " \
+               "delegate_result #{child_id} waits again. chi --attach #{child_id} shows it.")
       end
 
       # The whole question, as `chi send --wait` prints it (ParentReport):
@@ -205,7 +244,8 @@ module Samagotchi
       # report back.
       # A report's last line differs (+report+): "waits again" made models
       # call delegate_result right after answering Continue.
-      def waiting_text(child_id, pending, report: false)
+      # The tool's last line follows #reports_mode.
+      def waiting_text(child_id, pending, report: false, reports: "off")
         text = "Child #{child_id} is #{ParentReport.question_text(pending, session_id: child_id)}"
         if ParentReport.continue?(pending)
           text += "The child ran out of steps before it answered. Decide: continue it (run the chi answer command " \
@@ -213,8 +253,10 @@ module Samagotchi
                   "session: #{child_id} (that drops the question); or stop it and report back to your user.\n"
         end
         return "#{text}#{REPORT_NEXT_REPLY}" if report
+        return "#{text}delegate_result #{child_id} waits again once it is answered." if reports == "off"
 
-        "#{text}delegate_result #{child_id} waits again once it is answered."
+        "#{text}Once it is answered, chi brings the child's next reply here as a delegate report; " \
+          "delegate_result #{child_id} waits for it only if this turn needs it."
       end
 
       def cut(text)

data/lib/samagotchi/turn_note.rb

@@ -36,8 +36,16 @@ module Samagotchi
     # @param restored [Boolean] the prompt went back to its sender (the
     #   failed user message is not in the conversation any more)
     # @param continued [Boolean] it was a continue turn (no user message)
-    def failed(summary, restored: false, continued: false)
+    # @param wake [String, nil] what woke it, when chi started the turn and
+    #   not the user ("the change in attached context pr-7"): the user
+    #   wrote nothing, and wakes pause until they do
+    # @param kept [String, nil] what becomes of the wake's news, after
+    #   that (a delegate report's rings stay for the user's next turn)
+    def failed(summary, restored: false, continued: false, wake: nil, kept: nil)
       tail = if restored then RESTORED
+             elsif wake
+               "The wake turn for #{one_line(wake)} was not answered; chi starts no other wake turn until the user writes." +
+                 (kept ? " #{one_line(kept)}" : "")
              elsif continued then "The continued turn stopped there."
              else "The user's last message was not answered."
              end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.33.0"
+  VERSION = "0.34.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/worker.rb

@@ -488,7 +488,8 @@ module Samagotchi
       run_engine_turn(nil, continue: true, origin: { client_id: "#{ClientId::CONTEXT_PREFIX}#{name}" },
                            id: turn_id, max_iterations: IterationLimit.for) do |result, error|
         if error
-          note = TurnNote.failed(error.respond_to?(:summary) ? error.summary : error.message)
+          note = TurnNote.failed(error.respond_to?(:summary) ? error.summary : error.message,
+                                 wake: "the change in attached context #{name}")
           @turn_flow.prompt_turn_failed(note: note)
           unmark_wake_note(turn_id, waking.note)
           @wakes_paused = true
@@ -616,7 +617,11 @@ module Samagotchi
       @turn_flow.before_prompt_turn
       run_engine_turn(nil, continue: true, origin: reports.first.origin, max_iterations: IterationLimit.for) do |result, error|
         if error
-          note = TurnNote.failed(error.respond_to?(:summary) ? error.summary : error.message)
+          # The rings stay (settle_child_reports): the user's next turn takes them.
+          note = TurnNote.failed(error.respond_to?(:summary) ? error.summary : error.message,
+                                 wake: reports.size == 1 ? "a delegate's report" : "#{reports.size} delegate reports",
+                                 kept: "chi keeps #{reports.size == 1 ? "the report and brings it" : "the reports and brings them"} " \
+                                       "again with the user's next message.")
           @turn_flow.prompt_turn_failed(note: note)
           @wakes_paused = true
         else