samagotchi 0.124.0 → 0.126.0

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.124.0"
+  VERSION = "0.126.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -69,6 +69,7 @@ require_relative "message_display"
 require_relative "session_show"
 require_relative "session_create"
 require_relative "session_control"
+require_relative "verify_fresh_routes"
 require_relative "push_routes"
 require_relative "update_check"
 require_relative "proxy_gate"
@@ -99,6 +100,7 @@ module Samagotchi
       include SessionShow
       include SessionCreate
       include SessionControl
+      include VerifyFreshRoutes
       include PushRoutes
       include ProxyGate
 
@@ -265,6 +267,7 @@ module Samagotchi
         ["POST", %r{\A/api/sessions/([^/]+)/turn\z}, :handle_turn, :participant, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/wait/prepare\z}, :handle_wait_prepare, :participant, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/wait\z}, :handle_wait, :participant, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/verdicts/([^/]+)/fresh\z}, :handle_verify_fresh, :participant, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/notes\z}, :handle_notes, :owner, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/wake\z}, :handle_wake, :owner, :session],
         ["GET", %r{\A/api/sessions/([^/]+)/worker\z}, :handle_worker, :owner, :session],
@@ -1878,9 +1881,10 @@ module Samagotchi
       def home_label(dir) = Paths.tilde(dir)
 
       # <body> data for the page: where sessions are stored, where an
-      # all-view new chat starts (the start folder), and, when ?dir names a
-      # folder in a repo, that project's name and root. A bad dir adds
-      # nothing here: the list call answers 400 and the page says so.
+      # all-view new chat starts (the start folder), the home folder, and,
+      # when ?dir names a folder in a repo, that project's name and root. A
+      # bad dir adds nothing here: the list call answers 400 and the page
+      # says so.
       # Without ?dir (and without ?scope=all) the page is the start folder's
       # project view when that folder is in a repo: data-scope-dir names it
       # for the page (the URL stays bare, so a token's 303, a link code's
@@ -1890,6 +1894,9 @@ module Samagotchi
         # version: the chi that served the page; the events snapshot names
         # the one serving now (an upgraded chi web after a reconnect).
         attrs = { "sessions-dir" => sessions_dir_label, "server-dir" => home_label(start_dir), "version" => Samagotchi::VERSION }
+        # The owner's home: a claim link's quote reads it "~", as the
+        # participant page shows it (claim_link.js).
+        attrs["home"] = Dir.home
         attrs["view"] = view_name(req.params["view"])
         # Only when on: the page reads its presence (the turn view ignores it).
         attrs["working-set"] = "1" if working_set?(req.params["working_set"])

data/lib/samagotchi/web/participant_access.rb

@@ -14,6 +14,7 @@ require_relative "../participant_messages"
 require_relative "../participants"
 require_relative "../session"
 require_relative "../turn_checkpoint"
+require_relative "../verify_fresh"
 require_relative "../log"
 
 module Samagotchi
@@ -271,8 +272,10 @@ module Samagotchi
         reason = participant_turn_refusal(grant, prompt, body)
         return participant_turn_refused(grant, prompt, *reason) if reason
 
+        verify = VerifyAnchor.from(body["verify"])
         result = SessionManager.deliver_turn(id, prompt: prompt, client_id: ClientId.review(grant.id),
                                                  delivery: Delivery::QUEUE, author: grant.author,
+                                                 verify: verify,
                                                  pending_limit: grant.queue_limit + 1,
                                                  state_dir: @state_dir, manager: @manager,
                                                  bridge: -> { live_bridge_client(id) })
@@ -291,15 +294,23 @@ module Samagotchi
 
       # [429, cap_reached, …] once the grant spent its cap (D7: their turns
       # and the side requests they caused, from the session's saved
-      # analytics; a running turn's spend counts from its end, and the
-      # worker checks again before a queued one starts), nil before.
+      # analytics, and their Verify fresh children's; a running turn's
+      # spend counts from its end, and the worker checks again before a
+      # queued one starts), nil before.
       def participant_cap_refusal(grant)
-        dir = Session.session_dir(grant.session_id, state_dir: default_state_dir)
-        return nil if SessionMetrics.saved_spend(dir, grant.author) < grant.spend_cap
+        return nil if participant_saved_spend(grant) < grant.spend_cap
 
         [429, "cap_reached", ParticipantMessages::CAP_REACHED]
       end
 
+      # What +grant+'s participant spent, saved: in the session and in
+      # their Verify fresh children (VerifyFresh.children_spend).
+      def participant_saved_spend(grant)
+        dir = Session.session_dir(grant.session_id, state_dir: default_state_dir)
+        SessionMetrics.saved_spend(dir, grant.author) +
+          VerifyFresh.children_spend(grant.session_id, grant.author, state_dir: default_state_dir)
+      end
+
       def participant_turn_refused(grant, prompt, status, code, detail)
         audit_turn(grant, prompt, status: "refused", reason: code)
         error_response(status, code, detail)

data/lib/samagotchi/web/participant_review.rb

@@ -7,6 +7,7 @@ require_relative "../session_metrics"
 require_relative "../review_start"
 require_relative "../guardrails/review_paths"
 require_relative "../participant_mode"
+require_relative "../verify_fresh"
 
 module Samagotchi
   module Web
@@ -73,6 +74,10 @@ module Samagotchi
           current_turn: current,
           waiting_for_owner: waiting,
           queued: review_queue(queued || [], viewer),
+          verdicts: ParticipantView.verdicts(VerifyFresh.verdicts_of(session, Session.session_dir(id, state_dir: default_state_dir)), viewer),
+          # The verdicts a fresh check runs for now (their check_turn_id;
+          # never the child's id: a participant can't open it).
+          fresh_running: VerifyFresh.running(id, state_dir: default_state_dir).map { |row| row[:of] }.uniq,
           last_event_id: turn_snapshot && turn_snapshot["event_id"]
         })
       end
@@ -190,7 +195,8 @@ module Samagotchi
         dir = Session.session_dir(grant.session_id, state_dir: default_state_dir)
         saved = SessionMetrics.saved_spend(dir, grant.author)
         live = live_spend(state, grant.author)
-        [saved, live].max.round(4)
+        fresh = VerifyFresh.children_spend(grant.session_id, grant.author, state_dir: default_state_dir)
+        ([saved, live].max + fresh).round(4)
       end
 
       # +author+'s cost in the live worker's metrics (spend_by_author), 0.0

data/lib/samagotchi/web/participant_view.rb

@@ -4,15 +4,17 @@ require_relative "../output_formatter"
 require_relative "../steer"
 require_relative "../turn_origin"
 require_relative "../participant_mode"
+require_relative "../verify_anchor"
 
 module Samagotchi
   module Web
     # What a participant sees of their session (D5 a): prompts and replies
     # with their authors, one-line tool rows (the tool's name, and a
     # project-relative path for a file tool), turn boundaries, and the
-    # waiting states. Never: tool output or arguments, thinking, context
-    # notes, plugin steers, automatic input, cards, commands, questions'
-    # internals, memories, the working set, cost or timing, host paths.
+    # waiting states. Verdict cards expose only their anchor, verdict,
+    # reason and author. Never: tool output or arguments, thinking, context
+    # notes, plugin steers, automatic input, other cards, commands,
+    # questions' internals, memories, the working set, cost or timing, host paths.
     #
     # Every read a participant reaches goes through here: the stream's
     # events (#event, ParticipantStreamFilter), the review route's
@@ -47,6 +49,9 @@ module Samagotchi
         "turn_completed" => :turn_ended,
         "turn_canceled" => :turn_ended,
         "turn_failed" => :turn_ended,
+        # A Verify fresh child's verdict landing on its card: the card's
+        # fields only (#verdict_record).
+        "verdict_recorded" => :verdict_recorded,
         "generation_chunk" => :generation_chunk,
         "generation_retrying" => :generation_retrying,
         "tool_call_started" => :tool_call_started,
@@ -125,8 +130,44 @@ module Samagotchi
         out
       end
 
-      def turn_ended(event, _viewer)
-        { "type" => field(event, :type).to_s, **id_fields(event) }
+      def turn_ended(event, viewer)
+        out = { "type" => field(event, :type).to_s, **id_fields(event) }
+        verdict = verdict_record(field(event, :verdict), viewer)
+        out["verdict"] = verdict if verdict
+        out
+      end
+
+      def verdicts(records, viewer)
+        Array(records).filter_map { |record| verdict_record(record, viewer) }
+      end
+
+      def verdict_record(raw, viewer)
+        return unless raw.is_a?(Hash)
+
+        anchor = VerifyAnchor.from(field(raw, :anchor))
+        verdict = field(raw, :verdict).to_s
+        reason = field(raw, :reason)
+        check_turn_id = field(raw, :check_turn_id)
+        by = field(raw, :by)
+        return unless anchor && %w[confirmed refuted unclear].include?(verdict) && reason.is_a?(String)
+        return unless check_turn_id.is_a?(String) && !check_turn_id.empty?
+        return unless by.nil? || by.is_a?(String)
+
+        out = {
+          "anchor" => { "turn_id" => anchor.turn_id, "quote" => anchor.quote },
+          "verdict" => verdict, "reason" => reason, "by" => by,
+          "check_turn_id" => check_turn_id
+        }
+        # A Verify fresh verdict: which verdict it checked again (never the
+        # child's id: a participant can't open that session).
+        of = field(raw, :of)
+        out.merge!("fresh" => true, "of" => of) if field(raw, :fresh) == true && of.is_a?(String) && !of.empty?
+        Redact.deep(out, viewer)
+      end
+
+      def verdict_recorded(event, viewer)
+        verdict = verdict_record(field(event, :verdict), viewer) or return nil
+        { "type" => "verdict_recorded", "verdict" => verdict }
       end
 
       # The reply's visible text only: never thinking, a tool call's bytes

data/lib/samagotchi/web/participants_admin.rb

@@ -26,15 +26,17 @@ module Samagotchi
       # +identity_header+: the header this chi web's auth proxy names the
       # signed-in user in (null without one), for the Invite's email field;
       # +mode+: what a participant invited now gets, "pair" or "review"
-      # (ReviewStart.share_terms), for the panel's words.
-      def handle_participants_list(_req, id = nil)
+      # (ReviewStart.share_terms), for the panel's words; +link_base+: where
+      # a participant's link opens (participant_base), for a claim link
+      # (claim_link.js) the participant's browser opens with its cookie.
+      def handle_participants_list(req, id = nil)
         now = @grants.now
         grants = @grants.list(session_id: id).map { |grant| grant.public_h(now) }
         return json_response(200, { participants: grants }) unless id
 
         terms = ReviewStart.share_terms(Session.load(id, state_dir: default_state_dir), state_dir: default_state_dir)
         json_response(200, { participants: with_spend(id, grants), warning: terms.warning, mode: terms.mode.to_s,
-                             identity_header: @public_url&.identity_header })
+                             identity_header: @public_url&.identity_header, link_base: participant_base(req) })
       rescue Grants::Unwritable => e
         grants_unwritable(e)
       end
@@ -149,10 +151,19 @@ module Samagotchi
           return @public_url.link(@link_codes.issue(kind: :grant, token: token, ttl: ttl), "s=#{id}")
         end
 
+        "#{participant_base(req)}?token=#{token}#s=#{id}"
+      end
+
+      # Where a participant's link opens, no token: web.public_url's origin,
+      # else this chi web's LAN address, else the Host asked
+      # ("http://192.168.1.5:4567/").
+      def participant_base(req)
+        return "#{@public_url.origin}/" if @public_url
+
         host = req.get_header("HTTP_HOST").to_s
         port = host[/:(\d+)\z/, 1] || req.port.to_s
         name = @lan ? @lan[:ip] : host.sub(/:\d*\z/, "")
-        "http://#{name}:#{port}/?token=#{token}#s=#{id}"
+        "http://#{name}:#{port}/"
       end
     end
   end

data/lib/samagotchi/web/public/annotate_bar.css

@@ -1,6 +1,6 @@
-/* The selection bubble (annotate_bar.js): Annotate + the presets (web.annotate_presets), small pills with a gap (they
-   wrap on a narrow page). Both pages link it: the owner's (app.js) and the participant page (participant.js). Colours
-   are tokens.css's. */
+/* The selection bubble (annotate_bar.js): Annotate + the presets (web.annotate_presets), Copy link last where the page
+   has one, small pills with a gap (they wrap on a narrow page). Both pages link it: the owner's (app.js) and the
+   participant page (participant.js). Colours are tokens.css's. */
 #annotateBar{position:fixed;z-index:20;display:flex;flex-wrap:wrap;gap:4px;max-width:calc(100vw - 16px)}
 #annotateBar[hidden]{display:none}
 #annotateBar button{font-size:12px;padding:4px 10px;border-radius:999px;box-shadow:0 2px 8px var(--shadow-strong)}
@@ -15,4 +15,8 @@
 #annotateBar.docked{right:8px;justify-content:center}
 @media (pointer:coarse){#annotateBar button{font-size:14px;padding:8px 14px}}
 #annotateBar .annotate-more-list[hidden]{display:none}
-#annotateBar .annotate-preset{background:var(--bg-raised);color:var(--text-2);border:1px solid var(--border-strong);padding:3px 10px;max-width:32ch;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+#annotateBar .annotate-preset,#annotateBar .annotate-link{background:var(--bg-raised);color:var(--text-2);border:1px solid var(--border-strong);padding:3px 10px;max-width:32ch;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+/* A claim link's target (claim_link.js): its bubble (or its turn's opening) ringed, the quote itself highlighted. One
+   name for both pages; --claim-mark/--claim-ring follow the palette (warn-bright and warn are set per palette). */
+.claim-hit{outline:2px solid var(--claim-ring);outline-offset:3px;border-radius:12px}
+::highlight(chi-claim){background-color:var(--claim-mark);color:inherit}