samagotchi 0.125.0 → 0.126.0

data/lib/samagotchi/session.rb

@@ -20,6 +20,10 @@ require_relative "project_scope"
 require_relative "guardrails/parent_levels"
 
 module Samagotchi
+  # Loaded on first use (a Verify fresh child): keeps the bundle test kit's
+  # load budget (spec/samagotchi/testing/sandbox_spec.rb).
+  autoload :VerifyFreshOrigin, File.expand_path("verify_fresh_origin", __dir__)
+
   # archive_store requires this file.
   autoload :ArchiveStore, File.expand_path("archive_store", __dir__)
 
@@ -134,6 +138,14 @@ module Samagotchi
       @last_turn = LastTurn.from_file(value)
     end
 
+    # Verdict cards recorded by completed Verify turns, in append order.
+    # A missing field stays missing until the first verdict is recorded.
+    def verdicts = @verdicts || []
+
+    def verdicts=(values)
+      @verdicts = values.nil? ? nil : Array(values)
+    end
+
     # The mark of a turn a worker checkpointed and never finished
     # (InterruptedTurn), as loaded; the next worker settles it and sets it
     # to nil. While a turn runs, #turn_checkpoint's marker is saved instead.
@@ -280,6 +292,20 @@ module Samagotchi
     # Whether this is a review session (chi review, the web's Start review).
     def review? = !@review.nil?
 
+    # A Verify fresh child's requester, rules and claim (VerifyFreshOrigin),
+    # nil for any other session. Set once, at spawn (VerifyFresh.start).
+    attr_reader :verify_fresh
+
+    # @param value [VerifyFreshOrigin, Hash, nil] the session file's form too
+    def verify_fresh=(value)
+      @verify_fresh = value.nil? ? nil : VerifyFreshOrigin.of(value)
+    end
+
+    # The session whose participants.json names this session's
+    # participants: a Verify fresh child's parent (its requester's grant is
+    # the parent's), else the session itself.
+    def participants_source_id = @verify_fresh && @parent_id ? @parent_id : @id
+
     # How many tool outputs its history holds: its tool messages
     # (tool_response, a chat loop's tool; a native step's one message holds
     # every call's output and counts once).
@@ -333,7 +359,7 @@ module Samagotchi
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
                    continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
                    toolkit: nil, toolkit_origin: "chosen", settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil,
-                   working_set_pins: [], review: nil)
+                   working_set_pins: [], review: nil, verdicts: nil, verify_fresh: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -370,6 +396,8 @@ module Samagotchi
       self.parent_answers = parent_answers
       self.working_set_pins = working_set_pins
       self.review = review
+      self.verdicts = verdicts
+      self.verify_fresh = verify_fresh
       self.interrupted_turn = interrupted_turn
       @turn_checkpoint = nil
       @archived = false
@@ -539,6 +567,7 @@ module Samagotchi
       "parent_id" => nil,
       "scratch" => false,
       "last_turn" => nil,
+      "verdicts" => nil,
       "delegate" => false,
       "llm_context" => nil,
       "continues" => nil,
@@ -553,12 +582,13 @@ module Samagotchi
       "parent_answers" => nil,
       "working_set_pins" => [],
       "review" => nil,
-      "first_turn_id" => nil
+      "first_turn_id" => nil,
+      "verify_fresh" => nil
     }.freeze
 
     # FIELDS a session file has only when set: a session without them saves
     # as it did before they existed.
-    OPTIONAL_FIELDS = %w[review first_turn_id].freeze
+    OPTIONAL_FIELDS = %w[review first_turn_id verdicts verify_fresh].freeze
 
     # A session from a parsed session file. +messages+ false leaves the
     # conversation out (the lists' lightweight summaries).
@@ -712,6 +742,13 @@ module Samagotchi
                 when "last_turn" then @last_turn&.to_file
                 when "working_set_pins" then @working_set_pins.map(&:to_file)
                 when "review" then @review&.to_file
+                when "verify_fresh" then @verify_fresh&.to_file
+                when "verdicts"
+                  @verdicts&.map do |record|
+                    scrub_utf8(record.to_h do |key, entry|
+                      [key.to_s, entry.is_a?(Hash) ? stringify_message_keys(entry) : entry]
+                    end)
+                  end
                 when "used_memory_names", "preloaded_memory_names", "muted_memory_names", "appended_prompt_files"
                   Array(instance_variable_get(:"@#{key}"))
                 else instance_variable_get(:"@#{key}")

data/lib/samagotchi/session_inbox.rb

@@ -12,6 +12,10 @@ require_relative "steer"
 require_relative "turn_origin"
 
 module Samagotchi
+  # Loaded on first use (a Verify turn's input): keeps the bundle test kit's
+  # load budget (spec/samagotchi/testing/sandbox_spec.rb).
+  autoload :VerifyAnchor, File.expand_path("verify_anchor", __dir__)
+
   # A session directory's file inbox and outbox (see SessionManager for the
   # layout): input/ holds one JSON file per queued turn, notes/ the context
   # notes a worker adds between turns, output/ one text file per reply,
@@ -53,7 +57,7 @@ module Samagotchi
     # @param now [Time] the time the file is named by (a spec's clock)
     # @return [String, false] the input file's path, or false
     def self.write_input(session_dir, prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [],
-                         delivery: nil, author: nil, now: Time.now)
+                         delivery: nil, author: nil, verify: nil, now: Time.now)
       images = Array(images)
       input_dir = File.join(session_dir, INPUT_DIR)
       FileUtils.mkdir_p(input_dir)
@@ -63,7 +67,7 @@ module Samagotchi
                  "no_interrupt" => (no_interrupt ? true : nil),
                  "delivery" => (Delivery.queue?(delivery) ? Delivery::QUEUE : nil),
                  "images" => (images.empty? ? nil : images.map { |image| image.transform_keys(&:to_s) }),
-                 "author" => author }.compact
+                 "author" => author, "verify" => VerifyAnchor.from(verify)&.to_file }.compact
       AtomicFile.write(path, JSON.generate(record))
       path
     rescue StandardError
@@ -228,9 +232,9 @@ module Samagotchi
     # (+no_interrupt+, --no-interrupt), its +images+ ({file:, name:} refs),
     # and its +delivery+ ("queue" or nil; a file without the key is one an
     # older chi wrote, so nil).
-    Input = Data.define(:prompt, :origin, :no_interrupt, :images, :delivery) do
-      def initialize(prompt:, origin: nil, no_interrupt: false, images: [], delivery: nil)
-        super(prompt:, origin: TurnOrigin.of(origin), no_interrupt:, images:, delivery:)
+    Input = Data.define(:prompt, :origin, :no_interrupt, :images, :delivery, :verify) do
+      def initialize(prompt:, origin: nil, no_interrupt: false, images: [], delivery: nil, verify: nil)
+        super(prompt:, origin: TurnOrigin.of(origin), no_interrupt:, images:, delivery:, verify: verify && VerifyAnchor.from(verify))
       end
     end
     # A file that doesn't parse, or isn't a JSON object: no prompt.
@@ -246,7 +250,7 @@ module Samagotchi
       origin = TurnOrigin.from(data.slice("client_id", "enqueued_id", "author"))
       images = Array(data["images"]).select { |image| image.is_a?(Hash) }.map { |image| image.transform_keys(&:to_sym) }
       Input.new(prompt: data["prompt"].to_s, origin: origin, no_interrupt: data["no_interrupt"] == true,
-                images: images, delivery: Delivery.queue?(data["delivery"]) ? Delivery::QUEUE : nil)
+                images: images, delivery: Delivery.queue?(data["delivery"]) ? Delivery::QUEUE : nil, verify: data["verify"])
     rescue JSON::ParserError
       UNREADABLE_INPUT
     end
@@ -278,9 +282,11 @@ module Samagotchi
       true
     end
 
-    # A parsed input file's #waits_for_turn_end?.
+    # A parsed input file's #waits_for_turn_end?. A Verify turn waits too:
+    # merged into a running turn as a steer, its anchor would be lost.
     def self.turn_end_data?(data)
-      Array(data["images"]).any? || Delivery.queue?(data["delivery"]) || Steer.participant_author?(data["author"])
+      Array(data["images"]).any? || Delivery.queue?(data["delivery"]) || Steer.participant_author?(data["author"]) ||
+        data["verify"].is_a?(Hash)
     end
 
     # How the unclaimed input file carrying +enqueued_id+ waits: :turn_end

data/lib/samagotchi/session_manager.rb

@@ -164,6 +164,8 @@ module Samagotchi
     #   turn sees it
     # @param review [SessionReview, nil] a review session's (ReviewStart; a
     #   continue keeps its previous link's)
+    # @param verify_fresh [VerifyFreshOrigin, nil] a Verify fresh child's
+    #   requester, rules and claim (VerifyFresh.start)
     # @param before_spawn [#call, nil] (session) runs once the session and
     #   its note are saved, before its worker spawns
     # @return [Session] with #seed_images_dropped: refs whose file was gone,
@@ -171,7 +173,7 @@ module Samagotchi
     def self.spawn_session(prompt:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
                            memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
                            preview: nil, title: nil, delegate: false, setup: SessionSetup.new, continues: nil, note: nil,
-                           note_source: "chi", before_spawn: nil, review: nil)
+                           note_source: "chi", before_spawn: nil, review: nil, verify_fresh: nil)
       sd = state_dir || Session.default_state_dir
       # The resolved ref is stored (a resumed session keeps its model when an
       # alias is retargeted), with the name as typed beside it. A wrong host
@@ -198,6 +200,8 @@ module Samagotchi
       )
       session.toolkit = Toolkit.configured(delegate: delegate) if session.toolkit.nil?
       session.toolkit_origin = setup.toolkit_origin || "default"
+      # Saved before the worker starts: its first turn is already the requester's.
+      session.verify_fresh = verify_fresh
       session.model_warning = model_warning
       # With no prompt there is no first turn to run (an attaching UI sends
       # the prompts), so the session starts idle.
@@ -1310,10 +1314,10 @@ module Samagotchi
     #   session's images/
     # @return [String, false] the input file's path, or false.
     def self.write_turn_input(session_id, prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, state_dir: nil,
-                              images: [], delivery: nil, author: nil)
+                              images: [], delivery: nil, author: nil, verify: nil)
       session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
       SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author)
+                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, verify: verify)
     end
 
     # How long a turn waits for the Bridge of a worker a resume just spawned.
@@ -1395,7 +1399,8 @@ module Samagotchi
     # @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, no_interrupt: false,
-                          author: nil, pending_limit: nil, state_dir: nil, manager: self, bridge: nil)
+                          author: nil, pending_limit: nil, verify: nil, state_dir: nil, manager: self, bridge: nil)
+      verify = VerifyAnchor.from(verify)
       session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
       bridge ||= lambda do
         link = WorkerLink.await(session_id, session_dir: session_dir, timeout: TURN_BRIDGE_WAIT)
@@ -1417,6 +1422,7 @@ module Samagotchi
           options[:no_interrupt] = true if no_interrupt
           options[:author] = author if author
           options[:pending_limit] = pending_limit if author && pending_limit
+          options[:verify] = verify if verify
           reply = client.post_turn(**options)
           ack = reply.json
           return DeliverResult.new(status: :accepted, via: :bridge, ack: ack) if reply.status == 202 && ack.is_a?(Hash)
@@ -1454,6 +1460,7 @@ module Samagotchi
       input[:delivery] = delivery unless Delivery.next_step?(delivery)
       input[:no_interrupt] = true if no_interrupt
       input[:author] = author if author
+      input[:verify] = verify if verify
       path = participant_queue_lock(session_dir, author && pending_limit) do
         # No worker: the participant's waiting files are all their turns,
         # counted and written under one lock (the Bridge counts under its).

data/lib/samagotchi/session_participants.rb

@@ -22,8 +22,10 @@ module Samagotchi
     end
 
     # Reads +session+'s sidecar again.
+    # A Verify fresh child reads its parent's (Session#participants_source_id):
+    # its requester's grant is there.
     def refresh!(session)
-      @session_id = session&.id
+      @session_id = source_id(session)
       @entries = read
       self
     end
@@ -44,7 +46,7 @@ module Samagotchi
     def entry_for(author, session: nil)
       return nil unless Steer.participant_author?(author)
 
-      refresh!(session) if session && session.id != @session_id
+      refresh!(session) if session && source_id(session) != @session_id
       id = Steer.participant_id(author)
       @entries.find { |e| e.id == id } || (@entries = read).find { |e| e.id == id }
     end
@@ -62,6 +64,12 @@ module Samagotchi
 
     private
 
+    def source_id(session)
+      return nil unless session
+
+      session.respond_to?(:participants_source_id) ? session.participants_source_id : session.id
+    end
+
     def read
       return [] if @session_id.to_s.empty?
 

data/lib/samagotchi/verdict.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A parsed verdict line from a Verify turn's final answer.
+  Verdict = Data.define(:verdict, :reason) do
+    LINE = /\AVerdict:\s*(confirmed|refuted|unclear)\b\s*(?:—|–|-)\s*(.+?)\s*\z/i
+    MARKDOWN = /(?:\*\*|__|`)/
+
+    def self.parse(text)
+      line = text.to_s.lines.reverse_each.find { |candidate| !candidate.strip.empty? }
+      return unless line
+
+      normalized = line.strip.gsub(MARKDOWN, "")
+      match = LINE.match(normalized)
+      return unless match
+
+      new(verdict: match[1].downcase, reason: match[2].strip)
+    end
+  end
+end

data/lib/samagotchi/verify_anchor.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A claim selected in an earlier turn, carried only by a Verify turn.
+  VerifyAnchor = Data.define(:turn_id, :quote) do
+    UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+    QUOTE_MAX = 200
+
+    def self.from(value)
+      return value if value.is_a?(self)
+      return nil unless value.is_a?(Hash)
+
+      fields = value.to_h { |key, entry| [key.to_s, entry] }
+      return nil unless fields.keys.sort == %w[quote turn_id]
+
+      turn_id = fields["turn_id"]
+      quote = fields["quote"]
+      return nil unless turn_id.is_a?(String) && UUID.match?(turn_id)
+      return nil unless quote.is_a?(String) && quote.length.between?(1, QUOTE_MAX) && !quote.strip.empty?
+
+      new(turn_id:, quote:)
+    end
+
+    def to_h = { turn_id:, quote: }
+
+    def to_file = { "turn_id" => turn_id, "quote" => quote }
+  end
+end

data/lib/samagotchi/verify_fresh.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+require_relative "atomic_file"
+require_relative "log"
+require_relative "session"
+require_relative "session_metrics"
+require_relative "steer"
+require_relative "verify_anchor"
+require_relative "verify_fresh_origin"
+
+module Samagotchi
+  autoload :SessionManager, File.expand_path("session_manager", __dir__)
+
+  # Verify fresh (docs/internals/participants.md, Verify fresh): an unclear
+  # verdict checked again by a delegate child that sees only the claim, in
+  # the parent session's own folder, with none of its history. The child's
+  # field (VerifyFreshOrigin) makes every turn of a participant's child
+  # theirs: their author, the boundary their grant has in the parent, their
+  # cap counted across the parent and all their fresh children (.spend).
+  #
+  # Two files in the parent's directory, neither in its conversation:
+  # - LEDGER, one line per child started (child id, the verdict it checks,
+  #   who asked): the running check (one fresh child per verdict at a time)
+  #   and the spend rollup read it;
+  # - INBOX, the child's verdicts (.forward, written by the child's worker
+  #   after its turn's save), taken into the parent's verdicts by the
+  #   parent's worker between turns (.take) and shown before that by chi
+  #   web (.verdicts_of). Verdicts are display state: nothing here enters a
+  #   prompt.
+  module VerifyFresh
+    LEDGER = "verify_fresh.jsonl"
+    LOCK = "verify_fresh.lock"
+    INBOX = "fresh_verdicts"
+    # The child's first message, after the claim.
+    ASK = "Verify this claim against the files here. You have none of the original session's context. " \
+          "End with a line `Verdict: confirmed|refuted|unclear — <one-line reason>`."
+    # How long a child whose worker hasn't come up yet counts as running
+    # (Tools::Delegate::STARTING_GRACE_SECONDS).
+    STARTING_GRACE_SECONDS = 15
+
+    # A start refused: the HTTP +status+, the error +code+ and its words.
+    class Refused < StandardError
+      attr_reader :status, :code
+
+      def initialize(status, code, detail)
+        @status = status
+        @code = code
+        super(detail)
+      end
+    end
+
+    NOT_FOUND = "no Verify verdict with that check turn in this session"
+    NOT_UNCLEAR = "only an unclear verdict can be verified fresh"
+    RUNNING = "a fresh check of this claim is already running"
+    BUSY = "a fresh check this requester started is still running: one at a time each"
+    FULL = "this session has as many delegates running as it may (session.max_children): wait for one to finish"
+
+    module_function
+
+    # The child's first prompt: the claim, quoted, and the ask. Nothing of
+    # the parent's conversation.
+    def prompt_for(quote)
+      claim = quote.to_s.lines.map { |line| "> #{line.chomp}" }.join("\n")
+      "Claim:\n#{claim}\n\n#{ASK}"
+    end
+
+    # Starts a fresh child for the parent's unclear verdict +of+ (its
+    # check_turn_id). +author+: the requester ("p:<id>"), nil for the
+    # owner; +mode+: a participant's grant's mode in the parent
+    # (ParticipantMode.live_for), saved on the child.
+    # @return [Session] the child
+    # @raise [Refused] no such verdict, not unclear, or a fresh check of it
+    #   still runs
+    def start(parent_id, of:, author:, mode: nil, state_dir: Session.default_state_dir, spawn: nil)
+      parent = Session.load(parent_id, state_dir: state_dir)
+      record = original(parent.verdicts, of) or raise Refused.new(404, "not_found", NOT_FOUND)
+      raise Refused.new(409, "not_unclear", NOT_UNCLEAR) unless field(record, :verdict).to_s == "unclear"
+
+      anchor = VerifyAnchor.from(field(record, :anchor)) or raise Refused.new(404, "not_found", NOT_FOUND)
+      author = Steer.sender_author(author)
+      origin = VerifyFreshOrigin.new(author: author, mode: author && mode.to_s, of: of, anchor: anchor)
+      dir = Session.session_dir(parent.id, state_dir: state_dir)
+      spawn ||= SessionManager.method(:spawn_session)
+      locked(dir) do
+        refuse_busy!(parent.id, of, author, state_dir)
+
+        child = spawn.call(prompt: prompt_for(anchor.quote), working_directory: parent.working_directory,
+                           model_name: parent.model_name, memories: [Session::DELEGATE_MEMORY],
+                           parent_id: parent.id, delegate: true, verify_fresh: origin, state_dir: state_dir)
+        append_ledger(dir, { "child_id" => child.id, "of" => of, "author" => author, "at" => Time.now.utc.iso8601(3) })
+        child
+      end
+    end
+
+    # Under the lock: one fresh check per verdict, one running fresh child
+    # per requester (a participant or the owner: each start passes the cap
+    # on saved spend, so parallel children would multiply it), and no more
+    # running children of any kind than session.max_children.
+    def refuse_busy!(parent_id, of, author, state_dir)
+      fresh = running(parent_id, state_dir: state_dir)
+      raise Refused.new(409, "fresh_running", RUNNING) if fresh.any? { |row| row[:of] == of }
+      raise Refused.new(409, "fresh_busy", BUSY) if fresh.any? { |row| row[:author] == author }
+
+      require_relative "tools/delegate"
+      return if Tools::Delegate.running_children(parent_id, state_dir: state_dir).size < Tools::Delegate.max_children
+
+      raise Refused.new(409, "children_full", FULL)
+    end
+    private_class_method :refuse_busy!
+
+    # The parent's verdict +of+ names, never a fresh one (a fresh verdict
+    # lands on its original's card; the original takes another check).
+    def original(verdicts, of)
+      Array(verdicts).find do |record|
+        record.is_a?(Hash) && field(record, :check_turn_id) == of && !field(record, :fresh)
+      end
+    end
+
+    # The fresh children of +parent_id+ running now, newest last: [{of:,
+    # child_id:, author:}].
+    def running(parent_id, state_dir: Session.default_state_dir)
+      ledger(Session.session_dir(parent_id, state_dir: state_dir)).select do |row|
+        child_running?(row[:child_id], state_dir)
+      end
+    end
+
+    # What +author+ spent in the fresh children of +parent_id+ (their saved
+    # analytics), but +except+'s (the child asking, whose own spend its
+    # worker counts live).
+    # @return [Float]
+    def children_spend(parent_id, author, state_dir: Session.default_state_dir, except: nil)
+      return 0.0 unless Steer.participant_author?(author)
+
+      ledger(Session.session_dir(parent_id, state_dir: state_dir)).sum(0.0) do |row|
+        next 0.0 unless row[:author] == author && row[:child_id] != except
+
+        SessionMetrics.saved_spend(Session.session_dir(row[:child_id], state_dir: state_dir), author)
+      end
+    end
+
+    # What +author+ spent outside +session+'s own metrics that counts
+    # against their cap there: in a parent, their fresh children's; in a
+    # fresh child, the parent's and its other fresh children's.
+    # @return [Float]
+    def related_spend(session, author, state_dir: Session.default_state_dir)
+      return 0.0 unless Steer.participant_author?(author) && session
+
+      if session.verify_fresh && session.parent_id
+        parent_dir = Session.session_dir(session.parent_id, state_dir: state_dir)
+        SessionMetrics.saved_spend(parent_dir, author) +
+          children_spend(session.parent_id, author, state_dir: state_dir, except: session.id)
+      else
+        children_spend(session.id, author, state_dir: state_dir)
+      end
+    rescue StandardError => e
+      Log.warn(:worker, "fresh_spend_failed", error: e.class.name, msg: e.message)
+      0.0
+    end
+
+    # The child's new verdicts (+records+, Engine's verdict records) into
+    # its parent's INBOX, marked fresh: true with the child's id and the
+    # verdict they check again (of). Best effort.
+    # @param child [Session] a Verify fresh child
+    # @return [Integer] how many were written
+    def forward(child, records, state_dir: Session.default_state_dir)
+      fresh = child&.verify_fresh
+      return 0 unless fresh&.of && child.parent_id && Session.exist?(child.parent_id, state_dir: state_dir)
+
+      dir = File.join(Session.session_dir(child.parent_id, state_dir: state_dir), INBOX)
+      FileUtils.mkdir_p(dir)
+      Array(records).count do |record|
+        check = field(record, :check_turn_id).to_s
+        next false unless Session.valid_id?(check)
+
+        out = record.to_h { |key, value| [key.to_s, value.is_a?(Hash) ? value.transform_keys(&:to_s) : value] }
+        out.merge!("fresh" => true, "of" => fresh.of, "child_id" => child.id)
+        AtomicFile.write(File.join(dir, "#{check}.json"), JSON.generate(out))
+        true
+      end
+    rescue StandardError => e
+      Log.warn(:worker, "fresh_forward_failed", parent: child&.parent_id.to_s[0, 8], error: e.class.name, msg: e.message)
+      0
+    end
+
+    # The verdicts waiting in +session_dir+'s INBOX: [[record, file]],
+    # oldest first.
+    def pending(session_dir)
+      Dir.glob(File.join(session_dir, INBOX, "*.json")).sort_by { |path| [File.mtime(path), path] }.filter_map do |path|
+        record = JSON.parse(File.read(path))
+        record.is_a?(Hash) && record["fresh"] == true ? [record, path] : nil
+      rescue JSON::ParserError, SystemCallError
+        nil
+      end
+    end
+
+    # The parent's side, between turns (its worker): the waiting verdicts
+    # appended to +session+'s verdicts (one already there is not added
+    # twice). The caller saves the session, then deletes the files.
+    # @return [Array(Array<Hash>, Array<String>)] the records added and the
+    #   files taken
+    def take(session, session_dir)
+      waiting = pending(session_dir)
+      return [[], []] if waiting.empty?
+
+      known = session.verdicts.map { |record| field(record, :check_turn_id) }
+      added = waiting.map(&:first).reject { |record| known.include?(record["check_turn_id"]) }
+      session.verdicts = session.verdicts + added unless added.empty?
+      [added, waiting.map(&:last)]
+    end
+
+    # +session+'s verdicts as a page shows them: its own, then the fresh
+    # ones still waiting in its INBOX (no worker took them yet).
+    def verdicts_of(session, session_dir)
+      own = Array(session.verdicts)
+      known = own.map { |record| field(record, :check_turn_id) }
+      own + pending(session_dir).map(&:first).reject { |record| known.include?(record["check_turn_id"]) }
+    rescue StandardError
+      Array(session.verdicts)
+    end
+
+    # The LEDGER's rows: [{child_id:, of:, author:}].
+    def ledger(session_dir)
+      path = File.join(session_dir, LEDGER)
+      return [] unless File.exist?(path)
+
+      File.readlines(path, chomp: true).filter_map do |line|
+        row = JSON.parse(line)
+        next unless row.is_a?(Hash) && Session.valid_id?(row["child_id"].to_s)
+
+        { child_id: row["child_id"], of: row["of"].to_s, author: row["author"] }
+      rescue JSON::ParserError
+        nil
+      end
+    rescue SystemCallError
+      []
+    end
+
+    def append_ledger(session_dir, row)
+      FileUtils.mkdir_p(session_dir)
+      File.open(File.join(session_dir, LEDGER), File::WRONLY | File::APPEND | File::CREAT, 0o600) do |io|
+        io.write("#{JSON.generate(row)}\n")
+      end
+    end
+    private_class_method :append_ledger
+
+    # One start at a time per parent: the running check and the spawn.
+    def locked(session_dir)
+      FileUtils.mkdir_p(session_dir)
+      File.open(File.join(session_dir, LOCK), File::RDWR | File::CREAT, 0o600) do |io|
+        io.flock(File::LOCK_EX)
+        yield
+      end
+    end
+    private_class_method :locked
+
+    # A child runs while its worker runs a turn, or while it is marked
+    # running and its worker is on its way (Tools::Delegate.running?).
+    def child_running?(child_id, state_dir)
+      child = Session.summary_from_file(Session.session_file(child_id, state_dir: state_dir)) or return false
+      return false unless child.status == Session::STATUS_RUNNING
+      return true if SessionManager.session_owner(child_id, state_dir: state_dir)&.worker?
+
+      Time.now - Time.iso8601(child.updated_at.to_s) < STARTING_GRACE_SECONDS
+    rescue ArgumentError
+      false
+    end
+    private_class_method :child_running?
+
+    def field(record, key) = record[key] || record[key.to_s]
+    private_class_method :field
+  end
+end

data/lib/samagotchi/verify_fresh_origin.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "steer"
+require_relative "turn_origin"
+require_relative "verify_anchor"
+require_relative "participant_mode"
+
+module Samagotchi
+  # A Verify fresh child's own field (Session#verify_fresh; VerifyFresh
+  # starts one): who asked for it (+author+, a participant's "p:<id>", nil
+  # for the owner), the rules a participant's turns run under in it
+  # (+mode+, "review" or "pair": their grant's mode in the parent when it
+  # started, ParticipantMode.live_for), the parent's verdict it checks again
+  # (+of+, that verdict's check_turn_id) and the claim (+anchor+, a
+  # VerifyAnchor). Every turn of a participant's child is theirs
+  # (#origin_for): their author, their boundary, their cap. A field that is
+  # there but doesn't read as one is INVALID, whose author is no
+  # participant's: its turns are refused, never run as the owner's.
+  VerifyFreshOrigin = Data.define(:author, :mode, :of, :anchor) do
+    # @param value [VerifyFreshOrigin, Hash, nil] the session file's form too
+    # @return [VerifyFreshOrigin, nil] nil for nil; INVALID for anything
+    #   else that doesn't read as one
+    def self.of(value)
+      return value if value.is_a?(self)
+      return nil if value.nil?
+      return self::INVALID unless value.is_a?(Hash)
+
+      field = ->(key) { value.key?(key) ? value[key] : value[key.to_s] }
+      author = field.call(:author)
+      mode = field.call(:mode)
+      anchor = VerifyAnchor.from(field.call(:anchor))
+      of = field.call(:of)
+      return self::INVALID unless anchor && of.is_a?(String) && !of.empty?
+      return new(author: nil, mode: nil, of: of, anchor: anchor) if author.nil?
+      return self::INVALID unless author.is_a?(String) && Steer.participant_author?(author) && self::MODES.include?(mode)
+
+      new(author: author, mode: mode, of: of, anchor: anchor)
+    end
+
+    # Whether a participant asked for it (the owner's child runs as any
+    # delegate child).
+    def participant? = Steer.participant_author?(author)
+
+    # The boundary a participant's turn runs under here: :pair only when
+    # saved so, else :review (fail closed).
+    def turn_mode = mode == ParticipantMode::PAIR.to_s ? ParticipantMode::PAIR : ParticipantMode::REVIEW
+
+    # +origin+ with this child's requester as its author: every turn of a
+    # participant's child is theirs, whoever typed it; the owner's child
+    # keeps the origin as it is.
+    # @param origin [TurnOrigin]
+    # @return [TurnOrigin]
+    def origin_for(origin)
+      origin = TurnOrigin.of(origin)
+      participant? ? origin.with(author: author) : origin
+    end
+
+    # The session file's form.
+    def to_file = { "author" => author, "mode" => mode, "of" => of, "anchor" => anchor&.to_file }.compact
+  end
+
+  # A verify_fresh field that doesn't read: a participant author nobody
+  # has, so the worker refuses its turns ("revoked"), under the review
+  # boundary.
+  # The modes a participant's child may be saved with (a constant of
+  # VerifyFreshOrigin: one inside the Data.define block would be Samagotchi's).
+  VerifyFreshOrigin::MODES = [ParticipantMode::REVIEW.to_s, ParticipantMode::PAIR.to_s].freeze
+
+  VerifyFreshOrigin::INVALID = VerifyFreshOrigin.new(author: "#{Steer::PARTICIPANT_PREFIX}invalid", mode: "review",
+                                                     of: nil, anchor: nil)
+end

data/lib/samagotchi/version.rb

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