samagotchi 0.14.0 → 0.16.0

data/lib/samagotchi/engine.rb

@@ -56,6 +56,7 @@ require_relative "thinking"
 require_relative "answer_display"
 require_relative "edit_preview"
 require_relative "question_desk"
+require_relative "relay_desk"
 require_relative "guardrail_wiring"
 require_relative "plugin_tasks"
 
@@ -161,6 +162,8 @@ module Samagotchi
         interface: -> { interface },
         user_input: ->(sid) { ArchiveStore.user_input(sid, state_dir: session_state_dir) }
       )
+      # Built here, not on first use: the turn thread and the Bridge's read it.
+      @relay_desk = RelayDesk.new
       @hooks = load_hooks_from_config
       load_hooks_from_bundles
       # The tools this session offers (the prompts' declarations and the
@@ -1232,15 +1235,25 @@ module Samagotchi
     # Open a question for the UIs and wait for its answer
     # (QuestionDesk#open_question: BLOCKS until answered or cancelled).
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
+    #   (as a Hash or as keywords)
+    # @param watch [#call, nil] closes the question with the reason it returns
     # @return [Hash, String] the answer, or {error:, …}
-    def open_question(fields)
-      @question_desk.open_question(fields)
+    def open_question(fields = nil, watch: nil, **more)
+      @question_desk.open_question({ **fields.to_h, **more }, watch: watch)
     end
 
     # Answer the pending question (called from UI thread; QuestionDesk#answer).
     # @return [Hash] normalized answer
-    def answer_question(id:, selected:, freeform: nil, client_id: nil)
-      @question_desk.answer(id: id, selected: selected, freeform: freeform, client_id: client_id)
+    def answer_question(id:, selected:, freeform: nil, client_id: nil, parent_agent: nil)
+      @question_desk.answer(id: id, selected: selected, freeform: freeform, client_id: client_id,
+                            parent_agent: parent_agent)
+    end
+
+    # Mark the pending question as relayed, or clear the mark
+    # (QuestionDesk#annotate).
+    # @return [Boolean]
+    def annotate_question(id, relayed_to:, reason: nil)
+      @question_desk.annotate(id, relayed_to: relayed_to, reason: reason)
     end
 
     def set_question_sync_handler(&block)
@@ -1293,6 +1306,30 @@ module Samagotchi
       def cwd = engine.session&.working_directory
       def state_dir = engine.peer_state_dir
       def cancelled? = !!engine.active_cancel_controller&.cancelled?
+      def relay = engine.relay_peer
+    end
+
+    # What the approval relay needs from the parent's Engine (Peers#relay):
+    # its own question flow, which every UI attached to it answers.
+    RelayPeer = Struct.new(:engine) do
+      def open_question(fields, watch: nil) = engine.open_question(fields, watch: watch)
+      def interface = engine.interface
+      def relay_desk = engine.relay_desk
+    end
+
+    # This worker's relays of its delegates' approvals (memory only).
+    # @return [RelayDesk]
+    attr_reader :relay_desk
+
+    # The relay's view of this Engine, or nil when it can't host a relay: a
+    # worker's Engine only (its Bridge is what a child verifies against;
+    # --non-interactive has no one to ask), never with a REPL's sync
+    # handler (no wait loop, no watch).
+    # @return [RelayPeer, nil]
+    def relay_peer
+      return nil unless interface == :worker && !@question_desk.sync_handler?
+
+      RelayPeer.new(self)
     end
 
     # @return [String] the state dir holding this Engine's sessions
@@ -1362,8 +1399,10 @@ module Samagotchi
     # +ended+: the end event is out (what follows is post-turn work).
     # +settings+: the kernel's LLM::TurnSettings, made in #prepare_turn and
     # set on the kernel in #generate.
+    # +id+: names the turn on :turn_started (its metrics record's id) and on
+    # its saved prompt, so a UI pairs the two whatever left the conversation.
     Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings) do
+                      :settings, :id) do
       # The turn's boundary events carry the origin only when there is one,
       # so payloads stay unchanged for callers that don't pass it.
       def tag(event) = origin ? event.merge(origin: origin) : event
@@ -1478,7 +1517,8 @@ module Samagotchi
       @guardrail_wiring.begin_turn(origin)
 
       Turn.new(session: session, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
-               controller: effective_controller, origin: origin, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC))
+               controller: effective_controller, origin: origin, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+               id: SecureRandom.uuid)
     end
     private :begin_turn
 
@@ -1492,7 +1532,7 @@ module Samagotchi
       image_refs, image_error = turn_image_refs(session, images)
       # Emit turn_started event
       bind_metrics(session)
-      turn_started = { type: :turn_started, session_id: session.id, prompt: turn.prompt }
+      turn_started = { type: :turn_started, session_id: session.id, prompt: turn.prompt, turn_id: turn.id }
       turn_started[:continue] = true if turn.continue
       turn_started[:images] = image_refs unless image_refs.empty?
       emit_event(turn.on_event, turn.tag(turn_started))
@@ -1595,7 +1635,7 @@ module Samagotchi
 
       return if turn.continue
 
-      user_message = { role: "user", content: turn.prompt }
+      user_message = { role: "user", content: turn.prompt, turn_id: turn.id }
       user_message[:images] = image_refs unless image_refs.empty?
       turn.messages << user_message
       session.last_prompt = turn.prompt
@@ -1689,17 +1729,15 @@ module Samagotchi
     # continue resumes from them rather than after a made-up reply.
     def kept_messages(turn, result, seconds)
       conversation = result.conversation if result.conversation.is_a?(Array)
-      # Nothing visible (the native loop: no text; the chat loop: its
-      # placeholder text) is a turn the model should know ended that way.
+      # Nothing visible (no text) is a turn the model should know ended
+      # that way: the note, and nothing made up as its answer. The note's
+      # marker is for the UIs (the notice, and the empty steps after a
+      # reload); it goes on the result's conversation too (the REPL keeps it).
+      # A retry's nudge at the tail goes: this note says it all.
       if result.empty_answer?
-        # The placeholder is for the UIs (a new array: it must not leak
-        # into the result); the note is for the model, so it goes on the
-        # result's conversation too.
-        # A retry's nudge at the tail goes: this note says it all.
-        note = TurnNote.empty
+        note = TurnNote.empty(retries: result.empty_retries, steps: result.empty_steps)
         conversation&.replace(TurnNote.without_trailing(conversation))
         saved = TurnNote.without_trailing(conversation || turn.session.messages)
-        saved << { role: "model", content: "[No response]" } if result.output.to_s.strip.empty?
         conversation << note if conversation
         saved + [note]
       elsif result.canceled? && conversation
@@ -1898,7 +1936,7 @@ module Samagotchi
     # @param result [LLM::ModelResult]
     # @return [Hash]
     def turn_summary(result)
-      {
+      summary = {
         output: result.output.to_s,
         exhausted: result.exhausted?,
         resumable: result.resumable?,
@@ -1906,6 +1944,9 @@ module Samagotchi
         tool_activity: Array(result.tool_activity).map(&:dup),
         context_status: result.context_status&.dup
       }
+      # No answer: every UI shows its notice (TurnNote.empty_answer_line).
+      summary[:empty_answer] = { retries: result.empty_retries.to_i } if result.empty_answer?
+      summary
     end
 
     # ── Session messages API ───────────────────────────────────────────────

data/lib/samagotchi/kernel_loop.rb

@@ -219,7 +219,7 @@ module Samagotchi
     # the prefill, and what the caller gave.
     Turn = Struct.new(:conversation, :context, :empty_retry, :tool_activity, :buffer, :qwen_attempts, :qwen_partial,
                       :prefill, :pending_tool_calls, :model_name, :pending_input, :on_stream_event,
-                      :cancel_controller, :cap, :emit, :iteration, keyword_init: true)
+                      :cancel_controller, :cap, :emit, :iteration, :empty_steps, :ended_empty, keyword_init: true)
     # One request: the prompt and its images as sent, the images' token
     # estimate, and the window it was measured against.
     Request = Struct.new(:prompt, :images, :image_tokens, :window, keyword_init: true)
@@ -234,7 +234,7 @@ module Samagotchi
       conversation = prepare_conversation(messages)
       Turn.new(
         conversation: conversation, context: ContextStatus.new(conversation: conversation),
-        empty_retry: EmptyAnswerRetry.new, tool_activity: [], buffer: +"", qwen_attempts: 0, qwen_partial: nil,
+        empty_retry: EmptyAnswerRetry.new, empty_steps: [], tool_activity: [], buffer: +"", qwen_attempts: 0, qwen_partial: nil,
         # Qwen with thinking off: an empty thought after the cue, so the model
         # answers at once. Kept in the turn's model messages, so each tool-loop
         # prompt starts with what the server already has cached.
@@ -418,11 +418,18 @@ module Samagotchi
       # The empty generation goes (its thinking would be sent again and
       # prime the same loop); an empty answer that will be retried is no
       # answer site, so a plugin's steer joins the retry.
-      turn.conversation.pop if retry_empty
+      turn.empty_steps << turn.conversation.pop if retry_empty
       # Queued steering keeps the turn going: the model answers the
       # injected message instead of stopping here.
       return :next if inject_pending_input!(turn, answer: retry_empty ? nil : answer)
 
+      # The last one goes too: earlier thinking is stripped from the prompt,
+      # so it would be an empty assistant turn there. The UIs draw it from
+      # the result's empty_steps.
+      if empty && !retry_empty
+        turn.empty_steps << turn.conversation.pop
+        turn.ended_empty = true
+      end
       if retry_empty
         turn.empty_retry.nudge!(turn.conversation, TurnNote.empty_retry,
                                 emit: turn.emit, iteration: turn.iteration, finish_reason: generation.finish_reason,
@@ -452,7 +459,9 @@ module Samagotchi
     # then the answer shows only its text.
     def finish(turn)
       exhausted = turn.pending_tool_calls && tool_response_turn?(turn.conversation.last)
-      output = strip_thought_blocks(last_model_content(turn.conversation))
+      # An empty answer left the conversation: an earlier model message
+      # isn't this turn's answer.
+      output = turn.ended_empty ? "" : strip_thought_blocks(last_model_content(turn.conversation))
       output = parser.strip_tool_calls(output) if exhausted
       LLM::ModelResult.new(
         text: PromptLiteralGuard.restore(output, profile: @profile).to_s,
@@ -460,7 +469,9 @@ module Samagotchi
         exhausted: exhausted,
         pending_tool_calls: turn.pending_tool_calls,
         tool_activity: turn.tool_activity,
-        context_status: turn.context.display
+        context_status: turn.context.display,
+        empty_steps: turn.empty_steps,
+        empty_retries: turn.empty_retry.attempts
       )
     end
 

data/lib/samagotchi/llm/chat_loop.rb

@@ -193,9 +193,11 @@ module Samagotchi
       # The shape the engine persists: role and content (parts stay an
       # Array), plus a model turn's tool_calls and thinking (the host's
       # reasoning, never sent back), a result's tool_call_id, the image
-      # refs of a user message or a tool result, and a plugin tool result's
-      # tool_params and tool_labels (the live row's params line and label,
-      # never sent back), and an edit/write result's tool_diffs (never sent).
+      # refs of a user message or a tool result, a prompt's turn_id (Engine,
+      # never sent), and a plugin tool result's tool_params and tool_labels
+      # (the live row's params line and label, never sent back), an
+      # edit/write result's tool_diffs (never sent), and an empty-answer
+      # note's marker (TurnNote.empty, never sent).
       def plain(conversation)
         conversation.map do |entry|
           content = entry[:content].is_a?(Array) ? entry[:content] : entry[:content].to_s
@@ -203,9 +205,12 @@ module Samagotchi
           message[:tool_calls] = entry[:tool_calls] if entry[:tool_calls].is_a?(Array) && !entry[:tool_calls].empty?
           message[:tool_call_id] = entry[:tool_call_id] if entry[:tool_call_id]
           message[:images] = entry[:images] if entry[:images].is_a?(Array) && !entry[:images].empty?
+          message[:turn_id] = entry[:turn_id] if entry[:turn_id]
           message[:thinking] = entry[:thinking] if entry[:thinking].is_a?(String) && !entry[:thinking].empty?
           ToolResponse::SAVED_KEYS.each { |key| message[key] = entry[key] if entry[key] }
           message[TurnNote::RETRY_NUDGE] = true if TurnNote.retry_nudge?(entry)
+          marker = TurnNote.empty_answer(entry)
+          message[TurnNote::EMPTY_ANSWER] = marker if marker
           message[AnswerDisplay::KEY] = entry[AnswerDisplay::KEY] if entry[AnswerDisplay::KEY]
           ContextNote::KEYS.each { |key| message[key] = entry[key] if entry.key?(key) }
           message
@@ -300,11 +305,12 @@ module Samagotchi
           @pending_input = pending_input
           @tool_activity = []
           @empty_retry = EmptyAnswerRetry.new
+          # The empty generations, never saved: the UIs draw the turn's
+          # steps from them (ModelResult#empty_steps).
+          @empty_steps = []
           @context = ContextStatus.new(conversation: conversation)
         end
 
-        EMPTY_ANSWER = "(the model returned an empty answer)"
-
         def call(max_iterations:, cap:)
           last_text = ""
           exhausted = true
@@ -338,11 +344,13 @@ module Samagotchi
               # plugin's steer joins the retry instead of being dropped, and
               # queued input (a user's line, a steer) goes in place of the nudge.
               next if inject_pending_input(iteration, answer: retry_empty ? nil : last_text)
+
+              # An empty answer (content "" + stop, seen from a remote host)
+              # ends the turn with no text: the UIs show their notice.
+              @empty_steps << with_thinking({ role: "model", content: "" }, response) if empty
               next if retry_empty && nudge_empty_answer(iteration, response)
 
-              # Shown, not saved: an empty answer (content "" + stop, seen from
-              # a remote host) would otherwise end the turn with nothing.
-              last_text = EMPTY_ANSWER if empty
+              last_text = "" if empty
               exhausted = false
               break
             end
@@ -571,7 +579,7 @@ module Samagotchi
 
         def result(text, exhausted:)
           ModelResult.new(text: text, conversation: @loop.plain(@conversation), exhausted: exhausted,
-                          tool_activity: @tool_activity, empty_answer: text == EMPTY_ANSWER,
+                          tool_activity: @tool_activity, empty_steps: @empty_steps, empty_retries: @empty_retry.attempts,
                           context_status: @context.display)
         end
 

data/lib/samagotchi/llm/model_result.rb

@@ -9,13 +9,19 @@ module Samagotchi
     # .canceled?, .cancellation_reason, .exhausted?, .resumable?,
     # .empty_answer?, plus the native loop's .tool_activity, .context_status
     # and .pending_tool_calls, which the interactive renderer needs.
+    #
+    # A turn with no answer also carries .empty_steps (its empty
+    # generations as model messages, which the loops keep out of the
+    # conversation) and .empty_retries (the retries spent): the Engine saves
+    # them on the turn's note for the UIs (TurnNote.empty).
     class ModelResult
       attr_reader :text, :conversation, :canceled, :cancellation_reason, :exhausted,
-                  :tool_activity, :context_status, :pending_tool_calls
+                  :tool_activity, :context_status, :pending_tool_calls, :empty_steps, :empty_retries
 
       def initialize(text:, conversation: nil, canceled: false, cancellation_reason: nil, exhausted: false,
-                     tool_activity: [], context_status: nil, pending_tool_calls: false, empty_answer: false)
-        @empty_answer = empty_answer
+                     tool_activity: [], context_status: nil, pending_tool_calls: false, empty_steps: [], empty_retries: 0)
+        @empty_steps = Array(empty_steps)
+        @empty_retries = empty_retries.to_i
         @text = text
         @conversation = conversation
         @canceled = canceled
@@ -35,13 +41,12 @@ module Samagotchi
         !!canceled
       end
 
-      # The turn ended with nothing visible: no text, or the chat loop's
-      # placeholder (empty_answer:). A cancelled turn or one that can be
-      # continued is not an empty answer.
+      # The turn ended with nothing visible (no text). A cancelled turn or
+      # one that can be continued is not an empty answer.
       def empty_answer?
         return false if canceled? || resumable?
 
-        !!@empty_answer || text.to_s.strip.empty?
+        text.to_s.strip.empty?
       end
 
       def exhausted?

data/lib/samagotchi/log_subscriber.rb

@@ -27,6 +27,7 @@ module Samagotchi
       question_requested: [],
       question_answered: %i[id],
       question_cancelled: %i[id reason],
+      question_relay: %i[id reason],
       generation_cancelled: %i[iteration],
       empty_answer_retry: %i[iteration attempt of finish_reason thinking_chars stopped_by]
     }.freeze

data/lib/samagotchi/parent_report.rb

@@ -145,6 +145,13 @@ module Samagotchi
     # What a parent does with an approval.
     DENY_AND_TELL = "deny it, and tell your user"
 
+    # The other way: the user answers it in chi (the web's bell and badge
+    # say it waits), and a wait with no message waits past it.
+    def leave_open(session_id)
+      "or leave it open: tell your user it waits in chi web (session #{session_id[0, 8]}); " \
+        "chi send --wait --format json #{session_id} waits until they answer"
+    end
+
     def approval?(question)
       question.is_a?(Hash) && (question[:kind] || question["kind"]).to_s == "approval"
     end
@@ -180,6 +187,7 @@ module Samagotchi
       if approval?(q)
         lines << "  allowing it is up to your user: #{DENY_AND_TELL}"
         lines << "  deny: #{answer_with(session_id, q)}"
+        lines << "  #{leave_open(session_id)}"
       else
         lines << "  more than one allowed: repeat --option" if q[:multi_select]
         lines << "  free text allowed: --text" if q[:allow_freeform]

data/lib/samagotchi/plugin_session_state.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "paths"
+require_relative "session"
+
+module Samagotchi
+  # A plugin's state for one session, by convention under its data dir
+  # (ctx.data_dir): sessions/<id>.json or sessions/<id>/. It goes when the
+  # session does (SessionManager.delete_session: the CLI, the web, a
+  # discarded empty session; SessionRetention's prune), so no bundle keeps
+  # state for sessions that are gone (check-in's /checkin settings).
+  module PluginSessionState
+    module_function
+
+    # @return [Array<String>] the paths removed
+    def remove(session_id, env: ENV)
+      id = session_id.to_s
+      # Only a plain id: anything else could name a path outside the dir.
+      return [] unless Session.valid_id?(id)
+
+      Dir.glob(File.join(Paths.state_dir(env: env), "plugins", "*", "sessions")).flat_map do |dir|
+        [File.join(dir, "#{id}.json"), File.join(dir, id)].select { |path| File.exist?(path) }
+                                                         .each { |path| FileUtils.rm_rf(path) }
+      end
+    rescue SystemCallError
+      []
+    end
+  end
+end

data/lib/samagotchi/question_desk.rb

@@ -36,6 +36,9 @@ module Samagotchi
       end
     end
 
+    # Seconds between two looks of an open question's watch (#open_question).
+    WATCH_INTERVAL = 0.5
+
     DISMISSED_NOTE = "The user dismissed the question without answering. Don't do what you asked about, " \
                      "or anything else that changes files or state. Finish your reply with what you found " \
                      "and what you would do, and wait."
@@ -73,11 +76,13 @@ module Samagotchi
     # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
     # @return [String] normalized answer JSON
     def request(payload)
-      result = open_question(**payload.slice(:question, :options, :header),
-                             multi_select: !!payload[:multi_select], allow_freeform: !!payload[:allow_freeform])
+      result = open_question({ **payload.slice(:question, :options, :header),
+                               multi_select: !!payload[:multi_select], allow_freeform: !!payload[:allow_freeform] })
       # Dismissed (the card's dismiss, Esc): an answer of its own, not a
       # tool failure the model learns to avoid the tool from.
       result = { dismissed: true, id: result[:id], note: DISMISSED_NOTE } if result.is_a?(Hash) && result[:error] == "no answer"
+      # Who answered is for the relay, not the model's tool result.
+      result = result.except(:by) if result.is_a?(Hash)
       result.is_a?(String) ? result : JSON.generate(result)
     end
 
@@ -87,9 +92,13 @@ module Samagotchi
     # The fields go to pending as given (no cleaning), extra keys
     # included, so a caller can add its own (kind:, approval:).
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
+    # @param watch [#call, nil] asked every WATCH_INTERVAL seconds while the
+    #   question waits (outside the lock): a String closes the question with
+    #   that reason, announced and returned as a cancel; nil keeps waiting.
+    #   An answer recorded first wins. Not on the sync-handler path.
     # @return [Hash, String] the answer {id:, selected:, freeform:, selected_indices:},
     #   or {error:, …}; a String when a sync handler returned text itself
-    def open_question(fields)
+    def open_question(fields, watch: nil)
       id = SecureRandom.uuid
       pending = { id: id, **fields, status: "pending", created_at: Time.now.iso8601(3) }.compact
 
@@ -150,20 +159,15 @@ module Samagotchi
       end
 
       # Block until answered/cancelled (cross-thread path: WEB/Bridge/background worker)
+      closed_reason = wait_for_answer(watch)
       answer = nil
       cancelled_reason = nil
       @lock.synchronize do
-        loop do
-          break if @answer
-          break if cancel_controller&.cancelled?
-          break if @pending.nil? || @pending[:status] != "pending"
-
-          # Wait with timeout to check cancel; 0.2s matches reminder poll
-          @cv.wait(0.2)
-        end
         answer = @answer
         controller = cancel_controller
-        cancelled_reason = controller.reason.to_s if answer.nil? && controller&.cancelled?
+        if answer.nil?
+          cancelled_reason = closed_reason || (controller.reason.to_s if controller&.cancelled?)
+        end
         @pending = nil
       end
       # Saved and announced outside the question lock (see the sync path).
@@ -185,16 +189,19 @@ module Samagotchi
     # @param id [String] pending id
     # @param selected [Array<String>] values/labels
     # @param freeform [String, nil]
-    # @param client_id [String, nil] who answers; chi answer's (a parent
-    #   agent) is held to guardrails.parent_approvals on an approval
-    # @return [Hash] normalized answer
+    # @param client_id [String, nil] who answers
+    # @param parent_agent [Boolean, nil] the answer is a parent agent's, so
+    #   it is held to guardrails.parent_approvals on an approval and doesn't
+    #   bring the session back to the lists; nil: chi answer's client id says so
+    # @return [Hash] normalized answer; a parent agent's carries by: "parent_agent"
     # @raise [NotPending, ArgumentError, Refused]
-    def answer(id:, selected:, freeform: nil, client_id: nil)
+    def answer(id:, selected:, freeform: nil, client_id: nil, parent_agent: nil)
       sel = Array(selected).map { |v| v.to_s.strip }.reject(&:empty?)
       fm = freeform.to_s.strip
       fm = nil if fm.empty?
+      parent_agent = client_id.to_s == Guardrails::ParentApprovals::CLIENT_ID if parent_agent.nil?
       # Read before the lock (config may touch the disk); this worker's own.
-      parent_setting = Guardrails::ParentApprovals.setting if client_id.to_s == Guardrails::ParentApprovals::CLIENT_ID
+      parent_setting = Guardrails::ParentApprovals.setting if parent_agent
       @lock.synchronize do
         pending = @pending
         raise NotPending, "no pending question" unless pending
@@ -228,19 +235,50 @@ module Samagotchi
         answer = { id: id.to_s, selected: sel, freeform: fm }
         # Derive indices for convenience
         answer[:selected_indices] = indices.compact
+        answer[:by] = "parent_agent" if parent_agent
         @answer = answer
         @cv.broadcast
         answer
       end.tap do
         # A human answered: the session is back in the lists (ArchiveStore).
-        @user_input.call(session&.id)
+        @user_input.call(session&.id) unless parent_agent
+      end
+    end
+
+    # Mark the pending question as relayed to a parent session's user, or
+    # clear the mark (relayed_to: nil): saved with it and announced as
+    # :question_relay, so every UI shows where else it can be answered. Under
+    # the question lock, so the save never lands after the turn thread
+    # cleared the question.
+    # @param relayed_to [Hash, nil] {parent_id:, parent_short:, relay_id:}
+    # @param reason [String, nil] why a mark was cleared (parent_gone, …)
+    # @return [Boolean] false when +id+ isn't the question pending now
+    def annotate(id, relayed_to:, reason: nil)
+      marked = @lock.synchronize do
+        pending = @pending
+        next nil unless pending && pending[:id].to_s == id.to_s
+        next nil if @answer || pending[:status].to_s != "pending"
+
+        relayed_to ? pending[:relayed_to] = relayed_to : pending.delete(:relayed_to)
+        if session
+          session.pending_question = pending.dup
+          begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
+        end
+        pending[:id]
       end
+      return false unless marked
+
+      emit({ type: :question_relay, id: marked, relayed_to: relayed_to, reason: reason }.compact.merge(relayed_to: relayed_to))
+      true
     end
 
     def sync_handler=(block)
       @sync_handler = block
     end
 
+    # @return [Boolean] a REPL answers inline (no wait loop)
+    def sync_handler? = !@sync_handler.nil?
+
     # Cancel the pending question (e.g. /cancel, a dismiss). Announces which
     # one, so every UI closes it; with none pending there is nothing to
     # announce. A question already answered (the turn thread hasn't taken the
@@ -292,6 +330,47 @@ module Samagotchi
 
     private
 
+    # Wait until the question is answered, cancelled or closed by +watch+.
+    # @return [String, nil] the watch's close reason
+    def wait_for_answer(watch)
+      next_watch = monotonic + WATCH_INTERVAL
+      loop do
+        done = @lock.synchronize do
+          next true if @answer || cancel_controller&.cancelled?
+          next true if @pending.nil? || @pending[:status] != "pending"
+
+          # Wait with timeout to check cancel; 0.2s matches reminder poll
+          @cv.wait([0.2, watch ? next_watch - monotonic : 0.2].min.clamp(0.0, 0.2))
+          false
+        end
+        return nil if done
+        next unless watch && monotonic >= next_watch
+
+        next_watch = monotonic + WATCH_INTERVAL
+        reason = run_watch(watch)
+        next unless reason
+
+        closed = @lock.synchronize do
+          next false if @answer || @pending.nil? || @pending[:status] != "pending"
+
+          @pending[:status] = "cancelled"
+          true
+        end
+        return reason if closed
+      end
+    end
+
+    # The watch's close reason; one that raises closes nothing.
+    def run_watch(watch)
+      reason = watch.call
+      reason&.to_s
+    rescue StandardError => e
+      Log.warn(:turn, "question_watch_failed", error: e.class.name, message: e.message)
+      nil
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
     def session = @session_lookup.call
     def state_dir = @state_dir_lookup.call
     def cancel_controller = @cancel_controller_lookup.call

data/lib/samagotchi/relay.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "guardrails/approval"
+
+module Samagotchi
+  # A delegate's approval reopened as the parent session's own (the
+  # approval relay): the same kind "approval" and the same approval facts,
+  # so every UI shows it as it shows the parent's own approvals, the diff
+  # included, and Guardrails::ParentApprovals judges it the same way. The
+  # question text names the delegate and its task over the child's own
+  # text; `relay:` says which child and which of its questions it answers.
+  # A relay of a relay (a grandchild's) grows relay.chain.
+  module Relay
+    # How much of the child's task the card keeps, and the question line.
+    TASK_CHARS = 200
+    TASK_LINE_CHARS = 80
+
+    module_function
+
+    # @param child [Session] the child as loaded (its id, its first prompt)
+    # @param pending [Hash] the child's pending question (string keys inside
+    #   when it came from a saved session)
+    # @param relay_id [String] RelayDesk's id
+    # @param more [Integer] other delegates' approvals waiting behind this one
+    # @return [Hash] Engine#open_question fields
+    def card(child, pending, relay_id:, more: 0)
+      pending = deep_symbolize(pending)
+      facts = pending[:approval].is_a?(Hash) ? pending[:approval] : {}
+      short = child.id.to_s[0, 8]
+      inner = pending[:relay].is_a?(Hash) ? pending[:relay] : nil
+      chain = inner ? [*Array(inner[:chain]), short] : [short]
+      asked = inner ? inner[:asked].to_s : pending[:question].to_s
+      task = inner ? inner[:task].to_s : task_of(child)
+      who = chain.reverse.join(" → ")
+      {
+        question: question_text(who, task, asked),
+        options: relabel(Array(pending[:options]), facts[:scopes], who),
+        header: header(who, more),
+        multi_select: false,
+        allow_freeform: pending.key?(:allow_freeform) ? !!pending[:allow_freeform] : true,
+        kind: Guardrails::Approval::KIND,
+        approval: facts,
+        relay: { id: relay_id, child_id: child.id, child_short: short, child_question_id: pending[:id].to_s,
+                 task: task, chain: chain, asked: asked, more: more.to_i }
+      }
+    end
+
+    # delegate ab12 ("fix the flaky spec in …") asks:
+    #   execute: git push origin main
+    #     in /path/repo (repo samagotchi, branch main)
+    def question_text(who, task, asked)
+      line = task.empty? ? "delegate #{who} asks:" : "delegate #{who} (#{cut(task, TASK_LINE_CHARS).inspect}) asks:"
+      [line, *asked.lines.map { |l| "  #{l.chomp}" }].join("\n")
+    end
+
+    def header(who, more)
+      text = "Approve delegate #{who}'s tool call?"
+      more.to_i.positive? ? "#{text} (+#{more} more delegate#{"s" if more.to_i > 1} waiting)" : text
+    end
+
+    # The child's options, by index: "session" is the child's session, so
+    # it says whose; "once", "repo", "rule" and Deny keep their labels (the
+    # approvals store is shared, a session scope keys on the child's id).
+    def relabel(options, scopes, who)
+      scopes = Array(scopes)
+      options.each_with_index.map do |label, index|
+        scopes[index].to_s == "session" ? "Allow this call for delegate #{who}'s session" : label.to_s
+      end
+    end
+
+    # The child's task: its first prompt, on one line, cut.
+    def task_of(child)
+      raw = [child.first_preview, child.last_prompt].map(&:to_s).find { |text| !text.strip.empty? }
+      cut(raw.to_s.gsub(/\s+/, " ").strip, TASK_CHARS)
+    end
+
+    def cut(text, limit) = text.length > limit ? "#{text[0, limit - 1]}…" : text
+
+    # Session.load symbolizes only top-level keys.
+    def deep_symbolize(value)
+      case value
+      when Hash then value.to_h { |key, inner| [key.to_sym, deep_symbolize(inner)] }
+      when Array then value.map { |inner| deep_symbolize(inner) }
+      else value
+      end
+    end
+  end
+end