samagotchi 0.92.0 → 0.94.0

data/lib/samagotchi/session.rb

@@ -15,6 +15,7 @@ require_relative "prompt_note"
 
 require_relative "paths"
 require_relative "project_scope"
+require_relative "guardrails/parent_levels"
 
 module Samagotchi
   # archive_store requires this file.
@@ -228,19 +229,19 @@ module Samagotchi
     # it (SessionSetup.of), a delegate child takes its parent's.
     attr_reader :parent_answers
 
-    # @param value [String, Symbol, nil] stripped and downcased; "" and
-    #   "default" are none; a value that isn't a level is kept as written
+    # @param value [String, Symbol, nil] read as
+    #   Guardrails::ParentPolicy.parse_level: a level, or nil for none ("",
+    #   "default"); a value that isn't a level is kept as written, stripped
     #   (read as hard: ParentPolicy.session_level)
     def parent_answers=(value)
-      word = value.to_s.strip
-      word = word.downcase if PARENT_ANSWERS_WORDS.include?(word.downcase)
-      @parent_answers = word.empty? || word == "default" ? nil : word
+      level = Guardrails::ParentPolicy.parse_level(value)
+      @parent_answers = case level
+                        when :unset then nil
+                        when :invalid then value.to_s.strip
+                        else level
+                        end
     end
 
-    # The levels and "default" (Guardrails::ParentPolicy::ORDER and UNSET;
-    # not required here: that file loads the guardrails).
-    PARENT_ANSWERS_WORDS = %w[hard standard soft default].freeze
-
     # The hook that stopped the last turn (stop_turn, or a cut with no retry
     # left), e.g. "loop-guard"; nil when it ended otherwise.
     def stopped_by

data/lib/samagotchi/session_inbox.rb

@@ -289,8 +289,11 @@ module Samagotchi
     # turn takes it (the Bridge's POST turn/dequeue, under the event log):
     # only one that waits for the turn's end (a queue or an image message,
     # #waits_for_turn_end?); a next-step file may be merged at any boundary.
-    # The file is claimed first, as the drain does (the rename is the race's
-    # one winner), then deleted, and its tombstone written.
+    # Its tombstone is written first, then the file claimed as the drain
+    # does (the rename is the race's one winner) and deleted; a claim a
+    # turn won takes the tombstone back. Tombstone first: a ReplyWait look
+    # that finds the file claimed and no tombstone knows a turn took it
+    # (never a removal half done, which it would read as a merge).
     # @return [Array(Symbol, Input)] [:removed, the input it held],
     #   [:not_queued, nil] for a next-step file, [:claimed, nil] when a
     #   turn took it (its *.json.processing is there), [:none, nil] for
@@ -304,10 +307,24 @@ module Samagotchi
         next unless data.is_a?(Hash) && data["enqueued_id"] == id
         return [:not_queued, nil] unless Array(data["images"]).any? || Delivery.queue?(data["delivery"])
 
-        claimed = claim_input_file(file) or return [:claimed, nil]
-        input = read_input(claimed)
         mark_removed(session_dir, id)
-        FileUtils.rm_f(claimed)
+        unless (claimed = claim_input_file(file))
+          unmark_removed(session_dir, id)
+          return [:claimed, nil]
+        end
+        # The claimed file goes whatever the read does: a claimed file left
+        # with the tombstone would read as a removal still under way
+        # (ReplyWait) until the wait's timeout. One that can't be read was
+        # still taken back (no prompt to give). A process killed between
+        # the claim and this delete leaves both: that wait then times out,
+        # never a wrong answer (a stale *.json.processing is never run).
+        input = begin
+          read_input(claimed)
+        rescue SystemCallError
+          UNREADABLE_INPUT
+        ensure
+          FileUtils.rm_f(claimed)
+        end
         return [:removed, input]
       rescue JSON::ParserError, SystemCallError
         next
@@ -316,7 +333,7 @@ module Samagotchi
     end
 
     # Whether a claimed input file (*.json.processing: a turn's, now or
-    # left by a crash) carries +id+.
+    # left by a crash, or a removal's before it deletes it) carries +id+.
     def self.claimed_input?(session_dir, id)
       Dir.glob(File.join(session_dir, INPUT_DIR, "*.json.processing")).any? do |file|
         data = JSON.parse(File.read(file))
@@ -325,7 +342,6 @@ module Samagotchi
         false
       end
     end
-    private_class_method :claimed_input?
 
     def self.mark_removed(session_dir, id)
       return unless ENQUEUED_ID_NAME.match?(id)
@@ -338,8 +354,15 @@ module Samagotchi
     end
     private_class_method :mark_removed
 
+    def self.unmark_removed(session_dir, id)
+      FileUtils.rm_f(File.join(session_dir, INPUT_DIR, REMOVED_DIR, id)) if ENQUEUED_ID_NAME.match?(id)
+    end
+    private_class_method :unmark_removed
+
     # @return [Boolean] whether the queued input +enqueued_id+ was removed
-    #   before it ran (#take_queued_input's tombstone)
+    #   before it ran (#take_queued_input's tombstone), or is being removed:
+    #   the tombstone goes first, so while its claimed file is still there
+    #   (#claimed_input?) the removal may yet lose to a turn's claim
     def self.removed?(session_dir, enqueued_id)
       id = enqueued_id.to_s
       ENQUEUED_ID_NAME.match?(id) && File.exist?(File.join(session_dir, INPUT_DIR, REMOVED_DIR, id))

data/lib/samagotchi/session_manager.rb

@@ -80,7 +80,7 @@ module Samagotchi
 
       def initialize(session_id)
         @session_id = session_id
-        super("session #{session_id} is owned by an interactive TUI")
+        super("session #{session_id} is open in a chi REPL; close it there first")
       end
     end
 
@@ -1140,6 +1140,39 @@ module Samagotchi
     # How long a turn waits for the Bridge of a worker a resume just spawned.
     TURN_BRIDGE_WAIT = 5.0
 
+    # What #deliver_turn did with a message.
+    # +status+ :accepted; :refused (the Bridge refused it, or a queue would
+    # reach a worker that doesn't queue); :timeout (the Bridge took it and
+    # never answered); :failed (the input file couldn't be written).
+    # +via+ :bridge (the worker's Bridge answered) or :file (the input-file
+    # fallback); nil when nothing went in.
+    # +ack+ the Bridge's reply body, or the file's {"status", "enqueued_id",
+    # "session_id"}: string keys either way, {} for none.
+    # +code+ a refusal's HTTP status.
+    DeliverResult = Data.define(:status, :via, :ack, :code) do
+      def initialize(status:, via: nil, ack: {}, code: nil) = super(status:, via:, ack: ack || {}, code:)
+
+      def accepted? = status == :accepted
+
+      # Sent as an input file (no Bridge): its turn and outcome carry the
+      # file's enqueued_id, which a wait follows (chi send --wait).
+      def file? = via == :file
+
+      # @return [String, nil] the id the message's turn will carry
+      def enqueued_id
+        id = ack["enqueued_id"].to_s
+        id.empty? ? nil : id
+      end
+
+      # Whether the worker took the line as a session command (a POST /turn
+      # answered with its command_id).
+      def command? = !ack["command_id"].to_s.empty?
+
+      def error = ack["error"]
+
+      def detail = ack["detail"]
+    end
+
     # Hand a user message to the session the way a UI does, for the web
     # composer and `chi send` alike: wakes the worker when none runs, posts
     # through its Bridge so every live UI sees :turn_enqueued, and falls back
@@ -1153,14 +1186,12 @@ module Samagotchi
     #   stand-in (the web's specs); #session_owner is optional
     # @param bridge [#call, nil] returns the BridgeClient or nil; defaults to
     #   the session's sidecar, waiting TURN_BRIDGE_WAIT for a new worker's
-    # @return [Hash] {status: :accepted, ack: Hash} (the Bridge's reply, or
-    #   {status:, enqueued_id:, session_id:} for a file), {status: :refused,
-    #   code:, ack:} when the Bridge refused the request (any 4xx with an
+    # @return [DeliverResult] :accepted (via the Bridge or a file),
+    #   :refused when the Bridge refused the request (any 4xx with an
     #   error: bad images, a delivery it doesn't run) or a queue would reach
-    #   a worker that doesn't queue (no file then: it would steer),
-    #   {status: :timeout, ack:} when it took the request but never answered
-    #   (no file then), or {status: :failed} when the input file couldn't be
-    #   written
+    #   a worker that doesn't queue (no file then: it would steer), :timeout
+    #   when it took the request but never answered (no file then), or
+    #   :failed when the input file couldn't be written
     # @raise [OwnedByTUI] a chi REPL owns the session
     # @raise [ArgumentError] no such session
     def self.deliver_turn(session_id, prompt:, client_id: nil, images: [], delivery: nil, state_dir: nil, manager: self,
@@ -1180,7 +1211,7 @@ module Samagotchi
           options[:delivery] = delivery unless Delivery.next_step?(delivery)
           reply = client.post_turn(**options)
           ack = reply.json
-          return { status: :accepted, ack: ack } if reply.status == 202 && ack.is_a?(Hash)
+          return DeliverResult.new(status: :accepted, via: :bridge, ack: ack) if reply.status == 202 && ack.is_a?(Hash)
           # Read after its deadline and dropped: a file would run it after all.
           return turn_timeout if ack.is_a?(Hash) && ack["error"] == "deadline_passed"
           # Any other 4xx with an error is a refusal (bad images, a delivery
@@ -1189,7 +1220,7 @@ module Samagotchi
           # limit, a big piped chi send) and a 5xx keep the file fallback
           # below, which carries the delivery (a queue too).
           if (400..499).cover?(reply.status) && reply.status != 413 && ack.is_a?(Hash) && ack["error"]
-            return { status: :refused, code: reply.status, ack: ack }
+            return DeliverResult.new(status: :refused, via: :bridge, code: reply.status, ack: ack)
           end
         rescue Errno::ETIMEDOUT
           # The Bridge drops a turn it reads after the request's deadline
@@ -1205,7 +1236,7 @@ module Samagotchi
       input[:images] = images unless images.empty?
       input[:delivery] = delivery unless Delivery.next_step?(delivery)
       path = manager.write_turn_input(session_id, **input)
-      return { status: :failed } unless path
+      return DeliverResult.new(status: :failed) unless path
 
       owner = delivery_owner(manager, session_id, state_dir)
       # A TUI that took the session between the resume and the write never
@@ -1218,7 +1249,8 @@ module Samagotchi
       # wake a new one. (The exiting worker also looks for input it left;
       # one the first resume spawned that is still starting is left be.)
       manager.resume_session(session_id, state_dir: state_dir) if owner.nil?
-      { status: :accepted, ack: { status: "accepted", enqueued_id: enqueued_id, session_id: session_id } }
+      DeliverResult.new(status: :accepted, via: :file,
+                        ack: { "status" => "accepted", "enqueued_id" => enqueued_id, "session_id" => session_id })
     end
 
     # Whether the session's live worker runs delivery: queue (its sidecar
@@ -1230,12 +1262,13 @@ module Samagotchi
     end
 
     private_class_method def self.queue_unavailable
-      { status: :refused, code: 409, ack: Delivery::QUEUE_UNAVAILABLE }
+      DeliverResult.new(status: :refused, code: 409, ack: Delivery::QUEUE_UNAVAILABLE)
     end
 
     private_class_method def self.turn_timeout
-      { status: :timeout, ack: { "error" => "worker_timeout",
-                                 "detail" => "the session's worker did not answer, so the message was not sent" } }
+      DeliverResult.new(status: :timeout, via: :bridge,
+                        ack: { "error" => "worker_timeout",
+                               "detail" => "the session's worker did not answer, so the message was not sent" })
     end
 
     private_class_method def self.delivery_owner(manager, session_id, state_dir)

data/lib/samagotchi/session_metrics.rb

@@ -7,6 +7,7 @@ require "fileutils"
 require "securerandom"
 require_relative "analytics_file"
 require_relative "atomic_file"
+require_relative "log"
 require_relative "token_usage"
 require_relative "model_price"
 require_relative "session"
@@ -278,6 +279,8 @@ module Samagotchi
       # in snapshot order. Taken before @mutex, never under it: the write's
       # IO doesn't hold up the events.
       @persist_mutex = Mutex.new
+      # The error classes #persist has logged (under @persist_mutex).
+      @persist_failures = Set.new
       @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
       @wall_clock = wall_clock || -> { Time.now }
       @session_id = nil
@@ -481,7 +484,8 @@ module Samagotchi
 
     # Persist the summary snapshot, with every record, to a sibling
     # analytics.json in the session directory. Atomic write; failures are
-    # swallowed (analytics must never break the running session).
+    # swallowed (analytics must never break the running session), each
+    # error class logged once (WARN turn analytics_persist_failed).
     # @param state_dir [String, nil]
     # @param running_turn [Boolean] also save the running turn's record so
     #   far (a worker's turn checkpoint): as the turn a worker killed now
@@ -490,13 +494,28 @@ module Samagotchi
     #   turn's own end writes over it. Only the file has it.
     # @return [Boolean] true on success
     def persist(state_dir: nil, running_turn: false)
-      @persist_mutex.synchronize { persist_now(state_dir, running_turn) }
-    rescue StandardError
+      @persist_mutex.synchronize do
+        persist_now(state_dir, running_turn)
+      rescue StandardError => e
+        note_persist_failure(e)
+        false
+      end
+    rescue StandardError # a ThreadError from the mutex, a log that raised: still never raises
       false
     end
 
     private
 
+    # Logs a #persist failure the first time its error class is seen (under
+    # the persist mutex): side requests and checkpoints persist too, so a
+    # lasting failure (a full disk, a read-only dir) would log on every one.
+    def note_persist_failure(error)
+      return if @persist_failures.include?(error.class)
+
+      @persist_failures << error.class
+      Log.warn(:turn, "analytics_persist_failed", error: error.class.name, msg: error.message.to_s[0, 300])
+    end
+
     # #persist's work, under the persist mutex.
     def persist_now(state_dir, running_turn)
       sid, data, turn_count = @mutex.synchronize do

data/lib/samagotchi/sessions_command.rb

@@ -365,9 +365,9 @@ module Samagotchi
         begin
           id = Samagotchi::Session.resolve_id(given)
           released = Samagotchi::SessionManager.stop_session(id, wait: 10)
-        rescue Samagotchi::SessionManager::OwnedByTUI
+        rescue Samagotchi::SessionManager::OwnedByTUI => e
           @stdout.flush
-          @stderr.puts "session #{id} is open in a chi REPL; close it there first"
+          @stderr.puts e.message
           next false
         rescue ArgumentError => e
           @stdout.flush
@@ -394,9 +394,9 @@ module Samagotchi
         begin
           id = Samagotchi::Session.resolve_id(given)
           result = Samagotchi::SessionManager.restart_session(id)
-        rescue Samagotchi::SessionManager::OwnedByTUI
+        rescue Samagotchi::SessionManager::OwnedByTUI => e
           @stdout.flush
-          @stderr.puts "session #{id} is open in a chi REPL; close it there first"
+          @stderr.puts e.message
           next false
         rescue Samagotchi::SessionManager::RestartRefused => e
           @stdout.flush

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -1639,9 +1639,9 @@ module Samagotchi
       end
 
       def reminder_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::SYSTEM_PREFIX)
-      def report_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::CHILD_PREFIX)
-      def context_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::CONTEXT_PREFIX)
-      def task_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::TASK_PREFIX)
+      def report_origin?(origin) = ClientId.origin(origin[:client_id]) == "delegate_report"
+      def context_origin?(origin) = ClientId.origin(origin[:client_id]) == "context"
+      def task_origin?(origin) = ClientId.origin(origin[:client_id]) == "task"
       # A turn with no prompt: "(continuing)"; a context wake's or a task
       # finish wake's label alone.
       def continuing_text(origin) = context_origin?(origin) || task_origin?(origin) ? nil : "(continuing)"

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -215,11 +215,14 @@ module Samagotchi
         return fallback unless client_id
 
         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?
-
-        task = id.delete_prefix(ClientId::TASK_PREFIX)
-        return "task #{Tools::TaskRecord.short_id(task)} finished" if id.start_with?(ClientId::TASK_PREFIX) && !task.empty?
+        case ClientId.origin(id)
+        when "context"
+          name = id.delete_prefix(ClientId::CONTEXT_PREFIX)
+          return "context #{name} changed" unless name.empty?
+        when "task"
+          task = id.delete_prefix(ClientId::TASK_PREFIX)
+          return "task #{Tools::TaskRecord.short_id(task)} finished" unless task.empty?
+        end
 
         prefix = id[/\A[^:]*:/]
         CLIENT_LABELS[id] || (prefix && CLIENT_LABELS[prefix]) || AUTOMATIC_LABEL

data/lib/samagotchi/testing/bundle.rb

@@ -339,7 +339,7 @@ module Samagotchi
       def model_answers = @recorder.model_answers
 
       # Queue ask_user answers ({selected:, freeform:, selected_indices:},
-      # or a callable given the Question).
+      # or a callable given the HookQuestion).
       def answer(*answers)
         @recorder.answers.concat(answers)
         self

data/lib/samagotchi/testing/host.rb

@@ -27,10 +27,7 @@ module Samagotchi
           messages: -> { recorder[:messages] },
           messages_partial: -> { recorder[:messages_partial] },
           notify: ->(text, level, label, fallback_for: nil) { recorder.notify(text, level, label, fallback_for) },
-          ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:, effects: nil|
-            recorder.ask_user(question: question, options: options, header: header, allow_freeform: allow_freeform, hook: hook,
-                              effects: effects)
-          },
+          ask_user: ->(question) { recorder.ask_user(question) },
           cancelled: -> { recorder[:cancelled] },
           card: ->(**card) { recorder.card(**card) },
           ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil|
@@ -89,10 +86,7 @@ module Samagotchi
       def build(recorder)
         Hooks::Runtime.new(
           notify: ->(text:, level:, hook:, fallback_for: nil) { recorder.notify(text, level, hook, fallback_for) },
-          ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:, effects: nil|
-            recorder.ask_user(question: question, options: options, header: header, allow_freeform: allow_freeform, hook: hook,
-                              effects: effects)
-          },
+          ask_user: ->(question) { recorder.ask_user(question) },
           stop_turn: ->(reason:, hook:) { recorder.stop(:turn, reason, hook) },
           steer: ->(text:, hook:) { recorder.steer(text, hook) },
           stop_generation: ->(reason:, hook:) { recorder.stop(:generation, reason, hook) }

data/lib/samagotchi/testing/recorder.rb

@@ -3,6 +3,7 @@
 require_relative "../plugin/card"
 require_relative "../plugin/context"
 require_relative "../guardrails/parent_policy"
+require_relative "../hook_question"
 
 module Samagotchi
   module Testing
@@ -13,11 +14,6 @@ module Samagotchi
     Steer = Data.define(:text, :hook)
     # A stop_turn or stop_generation (+kind+ :turn or :generation).
     Stop = Data.define(:kind, :reason, :hook)
-    # An ask_user question; effects: its options' tags as the bundle gave
-    # them (label => effect), nil for none.
-    Question = Data.define(:question, :options, :header, :allow_freeform, :hook, :effects) do
-      def initialize(effects: nil, **) = super
-    end
     # An ask_model request: the request Context built (SideQuestion), its
     # limits, cancel controller and the model: it named (nil: the session's;
     # the kit doesn't check it against any hosts), and +source+, the asking
@@ -107,11 +103,12 @@ module Samagotchi
       # Effects chi would refuse (a label the options don't have, an
       # unknown effect: Guardrails::ParentPolicy.option_tags) ask no one, as
       # in chi: nil, nothing recorded, no answer taken.
-      def ask_user(question:, options:, header:, allow_freeform:, hook:, effects: nil)
-        return nil if Guardrails::ParentPolicy.option_tags(options, effects) == false
+      # @param question [HookQuestion] recorded as asked (#questions; its
+      #   effects as the bundle gave them: label => effect, nil for none)
+      def ask_user(question)
+        return nil if Guardrails::ParentPolicy.option_tags(question.options, question.effects) == false
 
-        record(@questions, Question.new(question: question, options: options, header: header,
-                                        allow_freeform: allow_freeform, hook: hook, effects: effects))
+        record(@questions, question)
         answer = @mutex.synchronize { @answers.shift }
         answer.respond_to?(:call) ? answer.call(@questions.last) : answer
       end

data/lib/samagotchi/testing/sandbox.rb

@@ -124,6 +124,32 @@ module Samagotchi
         File.join(memory_dir(scope, cwd: cwd || Dir.pwd), "#{name}.md")
       end
 
+      # The model notes chi loads into the prompt for +model_id+ (the bare
+      # id, no host prefix: `deepseek/deepseek-v4.1-flash`), from this
+      # sandbox's memories (the system scope's, then the project scope's for
+      # the checkout at +cwd+), matched as chi matches them: each `models:`
+      # glob against the id and its model key.
+      # @param small [Boolean, nil] whether the model counts as a small one
+      #   for a `small` entry; nil: chi's own rule (guardrails.small_models)
+      # @return [Array<#name, #scope, #chars, #body>] the notes in prompt
+      #   order (`.map(&:name)` for the names); none: []
+      def model_notes_for(model_id, small: nil, cwd: nil)
+        require_relative "../model_notes"
+        require_relative "../model_overlay"
+        small_check = small.nil? ? nil : -> { small }
+        in_dir(cwd) do
+          ModelNotes.for(name: model_id, key: ModelOverlay.key_for(model_id), small: small_check, warn: false)
+        end
+      end
+
+      # The sizes chi warns over (it still loads the notes): one note's
+      # body (+:note+) and all of a model's notes (+:total+), in chars.
+      # @return [Hash{Symbol => Integer}]
+      def model_note_limits
+        require_relative "../model_notes"
+        { note: ModelNotes::NOTE_LIMIT, total: ModelNotes::TOTAL_LIMIT }
+      end
+
       # @return [String] a temp folder for the session's cwd
       def work_dir = File.join(@root, "work")
 

data/lib/samagotchi/tools/delegate.rb

@@ -234,11 +234,11 @@ module Samagotchi
         DelegateWait.mark_seen(parent.id, child, state_dir: state_dir)
         delivered = SessionManager.deliver_turn(id, prompt: task, client_id: "#{ClientId::DELEGATE_PREFIX}#{parent.id[0, 8]}",
                                                     state_dir: state_dir)
-        case delivered[:status]
+        case delivered.status
         when :accepted
-          DelegateWait.mark_turn(parent.id, id, follow_up_turn(id, delivered[:ack], state_dir: state_dir), state_dir: state_dir)
+          DelegateWait.mark_turn(parent.id, id, follow_up_turn(id, delivered.enqueued_id, state_dir: state_dir), state_dir: state_dir)
           id
-        when :refused then "Error: session #{id[0, 8]} refused the message (#{delivered.dig(:ack, "error")})"
+        when :refused then "Error: session #{id[0, 8]} refused the message (#{delivered.error})"
         when :timeout then "Error: the worker of session #{id[0, 8]} did not answer in time, so the message was not sent"
         else "Error: the message to session #{id[0, 8]} could not be written"
         end
@@ -251,24 +251,24 @@ module Samagotchi
 
       # The child's turn a delivered follow-up joins, for the wait
       # (DelegateCursor#turn): the running turn's (its checkpoint mark), the
-      # follow-up merging into it; else the ack's enqueued_id, the follow-up
-      # running as a turn of its own. Only from a worker that names
-      # turn_ids; nil otherwise, or when the running turn has no id (a
-      # delegate's first turn): the wait takes the next reply.
+      # follow-up merging into it; else the delivery's +enqueued_id+, the
+      # follow-up running as a turn of its own. Only
+      # from a worker that names turn_ids; nil otherwise, or when the
+      # running turn has no id (a delegate's first turn): the wait takes the
+      # next reply.
       # A follow-up steered into a turn that ended before it merged runs as
       # its own turn, yet the wait is on the ended one (LOW, as before).
       # One the child's idle look missed being merged into a turn starting
       # then never runs as its own: ReplyWait falls back to that turn's
       # reply (merged_elsewhere?).
       # @return [String, nil]
-      def self.follow_up_turn(id, ack, state_dir:)
+      def self.follow_up_turn(id, enqueued_id, state_dir:)
         return nil unless ReplyWait.turn_ids?(Session.session_dir(id, state_dir: state_dir))
 
         child = Session.load(id, state_dir: state_dir)
         return child.interrupted_turn&.enqueued_id if child.status == Session::STATUS_RUNNING
 
-        enqueued_id = ack.is_a?(Hash) ? (ack["enqueued_id"] || ack[:enqueued_id]) : nil
-        enqueued_id.to_s.empty? ? nil : enqueued_id.to_s
+        enqueued_id
       rescue ArgumentError
         nil
       end

data/lib/samagotchi/tools/delegate_cursor.rb

@@ -4,6 +4,7 @@ require "json"
 require "fileutils"
 require_relative "../atomic_file"
 require_relative "../session"
+require_relative "../reply_wait"
 
 module Samagotchi
   module Tools
@@ -14,32 +15,54 @@ module Samagotchi
     # of the child's turn the last follow-up went to (Delegate.follow_up),
     # whose own reply a wait takes (ReplyWait's turn:); nil once that turn
     # was reported, or when unknown (a new child, an older worker).
-    #   +report_claim+: a report reserved until the parent's turn is settled.
+    #   +report_claim+: a report reserved until the parent's turn is settled
+    # (ReportClaim).
     DelegateCursor = Data.define(:reply_file, :last_turn, :question_id, :messages, :turn, :report_claim) do
       def initialize(reply_file: nil, last_turn: nil, question_id: nil, messages: nil, turn: nil, report_claim: nil) = super
 
       def self.empty = new
 
-      # @param baseline [Hash, nil] ReplyWait.baseline_of's
+      # The cursor with no report reserved: what it is once the reserving
+      # turn is settled, and how two cursors compare apart from a claim.
+      def without_claim = with(report_claim: nil)
+
+      # @param baseline [ReplyWait::Baseline, nil] ReplyWait.baseline_of's
       def with_baseline(baseline)
-        b = baseline || {}
-        with(messages: b[:messages], question_id: b[:question_id], last_turn: b[:last_turn])
+        with(messages: baseline&.messages, question_id: baseline&.question_id, last_turn: baseline&.last_turn)
       end
 
-      # @return [Hash, nil] ReplyWait's baseline:, nil when none was taken
+      # @return [ReplyWait::Baseline, nil] ReplyWait's baseline:, nil when
+      #   none was taken
       def baseline
         return nil if messages.nil?
 
-        { messages: messages, question_id: question_id, last_turn: last_turn }
+        ReplyWait::Baseline.new(messages: messages, question_id: question_id, last_turn: last_turn)
       end
 
-      def to_json_hash = to_h.transform_keys(&:to_s).compact
+      def to_json_hash = to_h.merge(report_claim: report_claim&.to_json_hash).transform_keys(&:to_s).compact
 
       def self.from_json_hash(data)
         return empty unless data.is_a?(Hash)
 
         new(reply_file: data["reply_file"], last_turn: data["last_turn"], question_id: data["question_id"],
-            messages: data["messages"], turn: data["turn"], report_claim: data["report_claim"])
+            messages: data["messages"], turn: data["turn"], report_claim: ReportClaim.from_json_hash(data["report_claim"]))
+      end
+    end
+
+    # A delegate report reserved in the parent's cursor (ChildReports) until
+    # the parent's turn that took it is kept or rolled back: +id+ the
+    # claim's id (the taking turn's Report#claim_id), +file+ the reply file
+    # reported (nil for a question), +cursor+ the DelegateCursor the report
+    # moves the parent to once kept (its own claim empty). In delegates.json
+    # it is {"id", "file", "cursor"}, the file's key kept even when nil.
+    ReportClaim = Data.define(:id, :file, :cursor) do
+      def to_json_hash = { "id" => id, "file" => file, "cursor" => cursor.to_json_hash }
+
+      # @return [ReportClaim, nil] nil for no claim (or not a Hash)
+      def self.from_json_hash(data)
+        return nil unless data.is_a?(Hash)
+
+        new(id: data["id"], file: data["file"], cursor: DelegateCursor.from_json_hash(data["cursor"]))
       end
     end
 
@@ -77,6 +100,7 @@ module Samagotchi
       end
 
       # Reserve a report only if the cursor read to build it is still current.
+      # @param claim [ReportClaim]
       # @return [DelegateCursor, nil] the reserved cursor, or nil if another path moved it
       def claim_report(parent_id, child_id, expected:, claim:, state_dir:)
         locked(parent_id, state_dir: state_dir) do