samagotchi 0.32.0 → 0.34.0

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../client_id"
 require_relative "../served_model"
 require_relative "../image_store"
 require_relative "../turn_note"
@@ -113,21 +114,29 @@ module Samagotchi
         " #{paint("+#{get.call(:added).to_i}", 32)} #{paint("\u2212#{get.call(:removed).to_i}", 31)}"
       end
 
-      # Prompt labels by the sender's client_id prefix (turn_events.js
-      # CLIENT_LABELS; spec/shared/labels_matrix.json).
-      CLIENT_LABELS = { "web" => "web", "tui" => "tui", "system" => "reminder", "delegate" => "delegate",
-                        "child" => "delegate report" }.freeze
-
-      # Who sent a line, by its client_id: CLIENT_LABELS by prefix, and a
-      # turn an attached context source started (context:<name>) as
-      # "context <name> changed"; +fallback+ for anything else.
+      # Prompt labels by the sender's client_id: a whole id, or a prefix
+      # (ending in ":") it starts with (turn_events.js CLIENT_LABELS;
+      # spec/shared/labels_matrix.json).
+      CLIENT_LABELS = { ClientId::WEB_PREFIX => "web", ClientId::TUI_PREFIX => "tui", ClientId::SYSTEM_PREFIX => "reminder",
+                        ClientId::DELEGATE_PREFIX => "delegate", ClientId::CHILD_PREFIX => "delegate report",
+                        ClientId::CLI_SEND => "chi send", ClientId::CLI_ANSWER => "chi answer",
+                        ClientId::PLUGIN => "plugin" }.freeze
+      # A client id chi doesn't know: not the user (ClientId.human?).
+      AUTOMATIC_LABEL = "automatic"
+
+      # Who sent a line, by its client_id: CLIENT_LABELS by the whole id or
+      # its prefix, a turn an attached context source started
+      # (context:<name>) as "context <name> changed", AUTOMATIC_LABEL for
+      # an id chi doesn't know; +fallback+ for none (the user's own).
       def client_label(client_id, fallback = "user")
         return fallback unless client_id
 
-        prefix, rest = client_id.to_s.split(":", 2)
-        return "context #{rest} changed" if prefix == Steer::CONTEXT_CLIENT_PREFIX.delete_suffix(":") && !rest.to_s.empty?
+        id = client_id.to_s
+        name = id.delete_prefix(ClientId::CONTEXT_PREFIX)
+        return "context #{name} changed" if id.start_with?(ClientId::CONTEXT_PREFIX) && !name.empty?
 
-        CLIENT_LABELS.fetch(prefix, fallback)
+        prefix = id[/\A[^:]*:/]
+        CLIENT_LABELS[id] || (prefix && CLIENT_LABELS[prefix]) || AUTOMATIC_LABEL
       end
 
       # "web> <prompt>": a prompt, labelled by who sent it; nil: the label alone.
@@ -142,7 +151,7 @@ module Samagotchi
         status = report[/^status: (.*)$/, 1]
         rest = report.split("\n").drop(2).reject { |line| line.strip.empty? || line == "---" }.first.to_s
         rest = "#{rest[0, STEER_PREVIEW - 1]}…" if rest.length > STEER_PREVIEW
-        "#{paint("#{CLIENT_LABELS["child"]}>", 35)} #{[id, status].compact.join(" ")}#{": #{rest}" unless rest.empty?}"
+        "#{paint("#{CLIENT_LABELS[ClientId::CHILD_PREFIX]}>", 35)} #{[id, status].compact.join(" ")}#{": #{rest}" unless rest.empty?}"
       end
 
       # The last prompt as a join shows it: a delegate report (a wake

data/lib/samagotchi/terminal_ui.rb

@@ -5,6 +5,7 @@ require "fileutils"
 require "io/console"
 require "reline"
 
+require_relative "client_id"
 require_relative "iteration_limit"
 require_relative "model_profile"
 require_relative "turn_note"
@@ -1281,7 +1282,7 @@ module Samagotchi
         end
 
         begin
-          parent = parent_answers? ? { client_id: Guardrails::ParentApprovals::CLIENT_ID } : {}
+          parent = parent_answers? ? { client_id: ClientId::CLI_ANSWER } : {}
           @engine.answer_question(id: prompt.id, selected: answer.selected, freeform: answer.freeform, **parent)
           close_question_widget(prompt, prompt.answer_text(answer))
           return true

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

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+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"
@@ -14,14 +16,14 @@ 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
     # reply comes back (DelegateWait), never its trace.
     class Delegate
       NAME = "delegate"
-      CLIENT_PREFIX = "delegate"
       MAX_CHILDREN_KEY = "session.max_children"
       MAX_CHILDREN_DEFAULT = 4
       # A child spawned this many seconds ago counts as running even before
@@ -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)
@@ -113,7 +200,7 @@ module Samagotchi
 
         # Only a reply after this delivery counts as the follow-up's.
         DelegateWait.mark_seen(parent.id, child, state_dir: state_dir)
-        delivered = SessionManager.deliver_turn(id, prompt: task, client_id: "#{CLIENT_PREFIX}:#{parent.id[0, 8]}",
+        delivered = SessionManager.deliver_turn(id, prompt: task, client_id: "#{ClientId::DELEGATE_PREFIX}#{parent.id[0, 8]}",
                                                     state_dir: state_dir)
         case delivered[:status]
         when :accepted then id
@@ -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/tools/execute.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../process_group"
 require_relative "output_guardrails"
 require_relative "shell"
 
@@ -95,7 +96,7 @@ module Samagotchi
 
         Open3.popen3(env || {}, *Shell.argv(command), chdir: cwd, pgroup: true) do |stdin, stdout, stderr, wait_thr|
           stdin.close
-          readers = [OutputReader.new(stdout), OutputReader.new(stderr)]
+          readers = [stdout, stderr].map { |io| ProcessGroup::PipeReader.new(io, chunk: READ_CHUNK_BYTES) }
 
           begin
             until wait_thr.join(WAIT_SLICE_SEC)
@@ -132,7 +133,7 @@ module Samagotchi
               stopped = stop_process_group(wait_thr.pid, readers)
               held_open = (stopped ? :stopped : :detached) if outcome == :grace && !stopping
             end
-            readers.each(&:finish)
+            readers.each { |reader| reader.finish(poll: STOP_POLL_INTERVAL_SEC, grace: STOP_GRACE_SEC) }
             stdout_text, stderr_text = readers.map(&:text)
           end
         end
@@ -162,95 +163,23 @@ module Samagotchi
       # has members holding the output: TERM the group, then KILL it. A process
       # that left the group (setsid) is out of reach; the pipes get closed.
       # True once the output was released, false if something still holds it.
+      # Only the group: the leader's pid is reaped, so it may name another process.
       def self.stop_process_group(pgid, readers)
-        signal_group(pgid, "TERM")
-        return true if await_readers(readers, until_time: monotonic_time + STOP_GRACE_SEC, deadline: nil,
-                                              cancelled: -> { false }) == :done
+        released = -> { readers.all?(&:done?) }
+        wait = ->(seconds) { readers.find { |r| !r.done? }&.wait(seconds) }
+        return true if ProcessGroup.stop(pgid, grace: STOP_GRACE_SEC, poll: STOP_POLL_INTERVAL_SEC, stopped: released, wait: wait)
 
-        signal_group(pgid, "KILL")
         await_readers(readers, until_time: monotonic_time + STOP_GRACE_SEC, deadline: nil, cancelled: -> { false }) == :done
       end
       private_class_method :stop_process_group
 
-      # Only the group: the leader's pid is reaped, so it may name another process.
-      def self.signal_group(pgid, signal)
-        Process.kill(signal, -pgid)
-      rescue Errno::ESRCH, Errno::EPERM
-        nil
-      end
-      private_class_method :signal_group
-
-      # Reads a pipe in chunks on its own thread, so the output read so far
-      # survives the pipe being closed under it.
-      class OutputReader
-        def initialize(io)
-          @io = io
-          @buffer = String.new(encoding: Encoding::BINARY)
-          @thread = Thread.new do
-            Thread.current.report_on_exception = false
-            loop { @buffer << io.readpartial(READ_CHUNK_BYTES) }
-          rescue IOError # EOFError is one
-            nil
-          end
-        end
-
-        def done? = !@thread.alive?
-
-        def wait(seconds) = @thread.join(seconds)
-
-        # Closes the pipe (a reader still blocked gets IOError) and ends the
-        # thread; the text is safe to read afterwards.
-        def finish
-          @thread.join(STOP_POLL_INTERVAL_SEC) unless done?
-          close_quietly
-          @thread.kill unless @thread.join(STOP_GRACE_SEC)
-        end
-
-        def text
-          @buffer.dup.force_encoding(@io.external_encoding || Encoding.default_external)
-        end
-
-        private
-
-        def close_quietly
-          @io.close unless @io.closed?
-        rescue IOError
-          nil
-        end
-      end
-      private_constant :OutputReader
-
+      # The shell still runs: TERM its group (or the shell alone, if it left
+      # the group), then KILL it once the grace is over.
       def self.terminate_process_tree(pid)
-        signal_process(pid, "TERM")
-
-        deadline = monotonic_time + STOP_GRACE_SEC
-        sleep(STOP_POLL_INTERVAL_SEC) while process_alive?(pid) && monotonic_time < deadline
-
-        signal_process(pid, "KILL") if process_alive?(pid)
+        ProcessGroup.stop(pid, grace: STOP_GRACE_SEC, poll: STOP_POLL_INTERVAL_SEC, leader: true)
       end
       private_class_method :terminate_process_tree
 
-      def self.signal_process(pid, signal)
-        Process.kill(signal, -pid)
-      rescue Errno::ESRCH, Errno::EPERM
-        begin
-          Process.kill(signal, pid)
-        rescue Errno::ESRCH, Errno::EPERM
-          nil
-        end
-      end
-      private_class_method :signal_process
-
-      def self.process_alive?(pid)
-        Process.kill(0, pid)
-        true
-      rescue Errno::ESRCH
-        false
-      rescue Errno::EPERM
-        true
-      end
-      private_class_method :process_alive?
-
       def self.monotonic_time
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end