samagotchi 0.15.0 → 0.17.0

data/lib/samagotchi/memory_bundle/profile.rb

@@ -30,8 +30,10 @@ module Samagotchi
         def failed? = !failed.empty?
       end
       # removed: members uninstalled; blocked: name => why; gone: the meta
-      # itself was removed (only once every member is).
-      UninstallResult = Struct.new(:name, :removed, :blocked, :gone, keyword_init: true)
+      # itself was removed (only once every member is); trash: member =>
+      # [memory files, the trash dir they were moved to]; warnings: the
+      # members' ("member: line").
+      UninstallResult = Struct.new(:name, :removed, :blocked, :gone, :trash, :warnings, keyword_init: true)
 
       module_function
 
@@ -127,10 +129,13 @@ module Samagotchi
         shipped = File.join(shipped_dir, name)
         manifest = File.file?(File.join(shipped, "manifest.yml")) ? Manifest.read(dir: shipped) : nil
         members = recorded(data, manifest)
-        result = UninstallResult.new(name: name, removed: [], blocked: {}, gone: false)
+        result = UninstallResult.new(name: name, removed: [], blocked: {}, gone: false, trash: {}, warnings: [])
         (members & installed_names).each do |member|
-          Uninstaller.new(name: member, force: force).run
+          uninstaller = Uninstaller.new(name: member, force: force)
+          uninstaller.run
           result.removed << member
+          result.trash[member] = [uninstaller.trashed_files, uninstaller.trash_dir] if uninstaller.trash_dir
+          result.warnings.concat(uninstaller.warnings.map { |w| "#{member}: #{w}" })
         rescue Uninstaller::UninstallError => e
           result.blocked[member] = e.message
         end

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -84,6 +84,20 @@ module Samagotchi
         end
       end
 
+      # The other installed bundles of +scope+ whose record lists the memory
+      # file +file_key+, by name (a manifest that doesn't read is left out).
+      # A project-scoped record doesn't say which project: one from another
+      # repo counts too, which errs on keeping the file.
+      def self.claimants(file_key, scope:, except: nil, dir: bundles_dir)
+        each_installed(dir: dir).filter_map do |name, data|
+          next if name == except || data[:error]
+          next unless (data[:scope].to_s.empty? ? "system" : data[:scope].to_s) == scope.to_s
+          next unless data[:files].is_a?(Hash) && data[:files].keys.map(&:to_s).include?(file_key.to_s)
+
+          name
+        end
+      end
+
       # The hex digest a manifest records, in either of its formats:
       # "sha256:<hex>" (hooks, rules, the plugin) or bare <hex> (a memory
       # file's checksum:). "" when none is recorded.

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -143,13 +143,15 @@ module Samagotchi
         row
       end
 
-      # The .md files whose local edits conflict with the shipped version.
+      # The bundle's .md files whose local edits conflict with the shipped
+      # version (a same-name file it didn't install is skipped, not merged).
       def conflicts(row, data)
         provenance = Provenance.new(name: row.name)
         target_dir = Status.resolve_target_dir(row.scope)
-        return [] unless data[:files]
+        return [] unless data[:files].is_a?(Hash)
 
-        Dir.glob(File.join(row.source_dir, "*.md")).map { |f| File.basename(f) }.sort.select do |key|
+        owned = data[:files].keys.map(&:to_s)
+        (Dir.glob(File.join(row.source_dir, "*.md")).map { |f| File.basename(f) }.sort & owned).select do |key|
           Merger.classify(base_path: provenance.base_path(key), current_path: File.join(target_dir, key),
                           incoming_path: File.join(row.source_dir, key)) == :conflict
         end

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -169,11 +169,13 @@ module Samagotchi
         result(:restored, from: version, to: version)
       end
 
-      # The files an upgrade would keep: edited here and changed in the
-      # shipped bundle (a dry run's kept).
+      # The files an upgrade would keep: installed by the bundle, edited
+      # here and changed in the shipped bundle (a dry run's kept).
       def conflicting(gem_manifest)
         provenance = Provenance.new(name: BUNDLE_NAME)
-        gem_manifest.files.keys.map(&:to_s).sort.select do |key|
+        owned = (provenance.read || {})[:files]
+        owned = owned.is_a?(Hash) ? owned.keys.map(&:to_s) : []
+        (gem_manifest.files.keys.map(&:to_s).sort & owned).select do |key|
           Merger.classify(base_path: provenance.base_path(key), current_path: File.join(MemoryPaths.system_dir, key),
                           incoming_path: File.join(GEM_BUNDLE_DIR, key)) == :conflict
         end

data/lib/samagotchi/memory_bundle/trash.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../memory_paths"
+
+module Samagotchi
+  module MemoryBundle
+    # Where a bundle operation puts the memory files it takes away
+    # (uninstall, an upgrade's dropped file): moved, never deleted, into
+    # <system memories>/.bundles/.trash/<bundle>-<YYYYmmdd-HHMMSS>/, one dir
+    # per operation (-2, -3… when one already has that name). A dot dir, so
+    # Provenance.each_installed never reads it as a bundle. Nothing prunes
+    # it: the user deletes it when sure.
+    class Trash
+      def self.root(bundles_dir: MemoryPaths.bundles_dir)
+        File.join(bundles_dir, ".trash")
+      end
+
+      # The dir, once a file was moved (nil before).
+      attr_reader :dir
+
+      def initialize(name, now: Time.now, bundles_dir: MemoryPaths.bundles_dir)
+        @name = name.to_s
+        @now = now
+        @bundles_dir = bundles_dir
+        @dir = nil
+      end
+
+      # Moves +path+ into the trash dir (created on the first call).
+      # @return [String] the file's new path
+      def move(path)
+        dest = File.join(ensure_dir, File.basename(path))
+        FileUtils.mv(path, dest)
+        dest
+      end
+
+      private
+
+      def ensure_dir
+        return @dir if @dir
+
+        base = File.join(self.class.root(bundles_dir: @bundles_dir), "#{@name}-#{@now.strftime("%Y%m%d-%H%M%S")}")
+        FileUtils.mkdir_p(File.dirname(base))
+        candidate = base
+        n = 1
+        loop do
+          Dir.mkdir(candidate)
+          break
+        rescue Errno::EEXIST
+          n += 1
+          candidate = "#{base}-#{n}"
+        end
+        @dir = candidate
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/uninstaller.rb

@@ -5,13 +5,17 @@ require_relative "../memory_paths"
 require_relative "provenance"
 require_relative "index_updater"
 require_relative "merger"
+require_relative "trash"
 
 module Samagotchi
   module MemoryBundle
     class Uninstaller
       class UninstallError < StandardError; end
 
-      attr_reader :warnings, :removed_files
+      # removed_files: the bundle's own hooks/ and plugin/ files (deleted);
+      # trashed_files: its memory files, moved to trash_dir (Trash), nil
+      # when none was moved.
+      attr_reader :warnings, :removed_files, :trashed_files
 
       def initialize(name:, scope: nil, force: false)
         @name = name
@@ -19,8 +23,12 @@ module Samagotchi
         @force = force
         @warnings = []
         @removed_files = []
+        @trashed_files = []
+        @trash = Trash.new(name)
       end
 
+      def trash_dir = @trash.dir
+
       def run
         provenance = Provenance.new(name: @name)
         data = provenance.read
@@ -40,12 +48,18 @@ module Samagotchi
           return true
         end
 
+        # A file another installed bundle lists too stays, edited or not.
+        shared = files.keys.map(&:to_s).to_h do |key|
+          [key, Provenance.claimants(key, scope: target_scope, except: @name)]
+        end.reject { |_, others| others.empty? }
+
         blocked = []
         files.each do |file_key, meta|
           file_key_str = file_key.to_s
           target_path = File.join(target_dir, file_key_str)
           base_path = provenance.base_path(file_key_str)
           next unless File.exist?(target_path)
+          next if shared.key?(file_key_str)
           if !@force && File.exist?(base_path) && Merger.current_modified?(base_path, target_path)
             blocked << file_key_str
             @warnings << "Skipped #{file_key_str}: local edits detected (use --force to remove)"
@@ -57,15 +71,23 @@ module Samagotchi
         files.each do |file_key, _meta|
           file_key_str = file_key.to_s
           target_path = File.join(target_dir, file_key_str)
+          if (others = shared[file_key_str])
+            next unless File.exist?(target_path)
+
+            @warnings << "Kept #{file_key_str}: bundle #{others.join(", ")} has it too"
+            retag(target_scope, target_path, file_key_str, others.first)
+            next
+          end
           if File.exist?(target_path)
-            FileUtils.rm_f(target_path)
-            @removed_files << file_key_str
+            @trash.move(target_path)
+            @trashed_files << file_key_str
           end
-          # Remove index line
+          # Remove index line (not fatal: a warning says so)
           begin
             IndexUpdater.remove_index(target_scope, file_key_str.delete_suffix(".md"))
             IndexUpdater.remove_index(target_scope, file_key_str) # legacy "name.md" line
-          rescue => _e
+          rescue StandardError => e
+            @warnings << "index.md: line for #{file_key_str.delete_suffix(".md")} not removed (#{e.message})"
           end
         end
 
@@ -97,6 +119,13 @@ module Samagotchi
 
       private
 
+      # A kept shared file's index line names the bundle that still has it.
+      def retag(scope, path, file_key, bundle)
+        IndexUpdater.update_index(scope, file_key.delete_suffix(".md"), File.size(path), source: bundle)
+      rescue StandardError => e
+        @warnings << "index.md: line for #{file_key.delete_suffix(".md")} not updated (#{e.message})"
+      end
+
       def resolve_target_dir(scope)
         MemoryPaths.scope_dir(scope) or raise UninstallError, "invalid scope: #{scope}"
       end

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/context.rb

@@ -18,11 +18,14 @@ module Samagotchi
     # (chat messages, timeout:, max_tokens:, cancel_controller:) and returns
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
-    # +model_name+ and +state_dir+ are what ctx.sessions forks with.
+    # +model_name+ (the session's resolved model ref, live after /model) and
+    # +state_dir+ are what ctx.sessions forks with; +model_key+ is the
+    # model's memory overlay key (ctx.model, ctx.model_key).
     # +steer+ takes (text, label), +stop_turn+ and +stop_generation+
     # (reason, label), each true when it acted on a running turn.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
-                      :ask_model, :model_name, :state_dir, :scratch, :steer, :stop_turn, :stop_generation, keyword_init: true)
+                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :steer, :stop_turn, :stop_generation,
+                      keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -86,6 +89,15 @@ module Samagotchi
       # @return [String, nil] the session's id (nil before the first one)
       def session_id = @host.session_id.call
 
+      # @return [String, nil] the model the session runs on now: its
+      #   resolved ref ("host:id"), right after /model too
+      def model = @host.model_name&.call
+
+      # @return [String, nil] the model's memory overlay key
+      #   (`<name>.<key>.md`, ModelOverlay.key_for), as memory_write
+      #   current_model_only names it
+      def model_key = @host.model_key&.call
+
       # @return [String] the session's working directory
       def cwd = @host.cwd.call || Dir.pwd
 

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

data/lib/samagotchi/relay_desk.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Samagotchi
+  # A parent worker's relays of its delegates' approvals: relay id → the
+  # child and its question, and the answer this worker's own question flow
+  # took from a UI. A child believes a relayed answer only when it asked
+  # this table for it, through the parent's Bridge (POST relay/status).
+  #
+  # Memory only: never in the session file, the event log, a snapshot, a
+  # log line or the environment, so nothing but this worker's question flow
+  # writes it. Entries are dropped KEEP_SECONDS after they settle.
+  class RelayDesk
+    KEEP_SECONDS = 600
+
+    # @param clock [#call] monotonic seconds (specs)
+    def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @clock = clock
+      @mutex = Mutex.new
+      @relays = {}
+    end
+
+    # @return [String] the new relay's id (a UUID: an id, not a secret)
+    def open(child_id:, child_question_id:)
+      id = SecureRandom.uuid
+      @mutex.synchronize do
+        prune
+        @relays[id] = { child_id: child_id.to_s, child_question_id: child_question_id.to_s, state: "open",
+                        answer: nil, by: nil, settled_at: nil }
+      end
+      id
+    end
+
+    # The parent's user (or a parent agent) answered the relay card.
+    # @param by [String] "user" or "parent_agent"
+    # @return [Boolean] false when the relay isn't open (first answer wins)
+    def record(id, selected_indices: [], freeform: nil, dismissed: false, by:)
+      @mutex.synchronize do
+        relay = @relays[id.to_s]
+        next false unless relay && relay[:state] == "open"
+
+        relay.merge!(state: "answered", by: by.to_s, settled_at: @clock.call,
+                     answer: { selected_indices: Array(selected_indices), freeform: freeform, dismissed: !!dismissed })
+        true
+      end
+    end
+
+    # The relay ended with no answer (a Stop, the child gone or answered).
+    def close(id)
+      @mutex.synchronize do
+        relay = @relays[id.to_s]
+        relay&.merge!(state: "closed", settled_at: @clock.call) if relay && relay[:state] == "open"
+      end
+      nil
+    end
+
+    # @return [Hash, nil] {child_id:, child_question_id:, state:, answer:, by:}
+    def status(id)
+      @mutex.synchronize do
+        prune
+        @relays[id.to_s]&.except(:settled_at)&.then { |relay| Marshal.load(Marshal.dump(relay)) }
+      end
+    end
+
+    private
+
+    def prune
+      now = @clock.call
+      @relays.delete_if { |_, relay| relay[:settled_at] && now - relay[:settled_at] > KEEP_SECONDS }
+    end
+  end
+end