samagotchi 0.114.0 → 0.116.0

data/lib/samagotchi/guardrail_wiring.rb

@@ -6,10 +6,13 @@ require_relative "config"
 require_relative "log"
 require_relative "guardrails"
 require_relative "guardrails/parent_approvals"
+require_relative "guardrails/parent_policy"
+require_relative "model_match"
 require_relative "memory_bundle/manifest"
 require_relative "version"
 require_relative "hooks"
 require_relative "edit_preview"
+require_relative "system_one"
 require_relative "tool_activity"
 require_relative "turn_origin"
 
@@ -38,8 +41,11 @@ module Samagotchi
     # @param ask       [#call] (fields) → the answer; the Engine's question flow
     # @param notify    [#call] (message) → shows a guardrails line in every UI
     #   (a bundle's rules kept because it needs a newer chi)
+    # @param system_one [#call] → SystemOne::Client or nil: the judgment client
+    #   (nil while `guardrails.system_one.mode` is off or no host is set)
+    # @param cancel_controller [#call] → the running turn's CancellationController, nil
     def initialize(scratch:, hooks:, tools:, session:, model_key:, cancelled:, ask:, model_name: -> {},
-                   notify: ->(_message) {})
+                   notify: ->(_message) {}, system_one: -> {}, cancel_controller: -> {})
       @scratch = scratch
       @hooks_lookup = hooks
       @tools_lookup = tools
@@ -49,6 +55,8 @@ module Samagotchi
       @cancelled_lookup = cancelled
       @ask = ask
       @notify = notify
+      @system_one = system_one
+      @cancel_controller = cancel_controller
       # Bundle name → the rules last loaded from it whole, kept while the
       # installed version needs a newer chi; [name, version] said so once.
       @loaded_bundle_rules = {}
@@ -82,6 +90,7 @@ module Samagotchi
     def state_dir=(state_dir)
       @approvals = Guardrails::Approvals.new(dir: Guardrails::Approvals.dir_for(state_dir))
       @approvals = Guardrails::Approvals::InMemory.new(@approvals) if @scratch
+      @system_one_log = nil
       @protected = nil
     end
 
@@ -259,11 +268,166 @@ module Samagotchi
       # A call on chi's own config, hooks or guardrails is the user's to
       # allow, never a parent agent's (Guardrails::ParentPolicy).
       payload[:user_only] = Guardrails::ParentApprovals.protected_facts?(payload[:approval])
-      Guardrails::Approval.settle(verdict, @ask.call(payload), payload[:approval][:scopes])
+      # System 1: the ask is judged before the user sees it, and in `on` mode
+      # one that passes every gate is allowed once without reaching them
+      # (docs/guardrails.md, "System 1").
+      judgment = system_one_judge(payload)
+      if judgment && judgment[:auto]
+        verdict.judgment = { id: judgment[:id], p: judgment[:p] }
+        verdict.settle!(:allow, decided_by: "system one")
+        verdict.scope = "once"
+        return verdict
+      end
+
+      answer = @ask.call(payload)
+      system_one_label(judgment, answer, payload)
+      Guardrails::Approval.settle(verdict, answer, payload[:approval][:scopes])
     end
 
     private
 
+    # The judgments log (SystemOne::Log), beside the approvals store; nil
+    # while there is no store dir.
+    def system_one_log
+      return nil if @approvals.nil?
+
+      @system_one_log ||= SystemOne::Log.new(dir: File.dirname(@approvals.path))
+    end
+
+    # System 1's judgment of an ask, written to the log before the user is
+    # asked, with the decision it led to: "auto" (it answered for the user),
+    # "asked" (on mode, the user decides) or "audit" (audit mode). A
+    # participant's review turn is never judged, and no client (mode off, no
+    # host) means no line at all. A judgment that fails is logged with p nil,
+    # so the failures are in the log too.
+    # @return [Hash, nil] {id:, p:, auto:}, nil when nothing was written
+    def system_one_judge(payload)
+      return nil if Steer.participant_author?(turn_author)
+
+      client = @system_one.call
+      log = system_one_log
+      return nil if client.nil? || log.nil?
+
+      approval = payload[:approval]
+      # The judgments log is read once for this ask: the state's examples and
+      # the record gate both use these entries. The judgment of the ask being
+      # judged is written after it, so the examples are always earlier asks.
+      entries = log.entries
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      answers = begin
+        client.ask(state: SystemOne::ApprovalQuestion.state(approval, session_title: @session_lookup.call&.title,
+                                                            entries: entries),
+                   questions: { SystemOne::ApprovalQuestion::ID => SystemOne::ApprovalQuestion.question },
+                   cancel_controller: @cancel_controller.call)
+      rescue StandardError => e
+        # The client already turns every failure it knows into a nil; this is
+        # the unexpected one. Either way the ask goes to the user.
+        Samagotchi::Log.warn(:guardrails, "system_one_ask_failed", error: "#{e.class}: #{e.message}")
+        nil
+      end
+      latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+      p = answers && answers[SystemOne::ApprovalQuestion::ID]&.noul
+      auto = system_one_auto_allow?(client, approval, p, entries)
+      decision = system_one_decision(client, auto)
+
+      id = log.judgment(session_id: @session_lookup.call&.id,
+                        rule: approval[:rule], source: approval[:source], tool: approval[:tool],
+                        **SystemOne::ApprovalQuestion.call_fields(approval),
+                        repo_name: approval[:repo_name],
+                        p: p, threshold: Config.get("guardrails.system_one.threshold"), model: client.model,
+                        latency_ms: latency_ms, decision: decision, origin: "live")
+      # A judgment the log cannot hold is no judgment: the user is asked.
+      { id: id, p: p, auto: auto && !id.nil? }
+    rescue StandardError => e
+      # The approval never fails because of System 1.
+      Samagotchi::Log.warn(:guardrails, "system_one_judgment_failed", error: "#{e.class}: #{e.message}")
+      nil
+    end
+
+    # What the judgment line says it did: "auto" (System 1 answered for the
+    # user), "asked" (on mode, the user decides), "audit" (nothing decided).
+    def system_one_decision(client, auto)
+      return "auto" if auto
+
+      client.mode == "on" ? "asked" : "audit"
+    end
+
+    # Every gate an auto-allow must pass, in order: the mode, the rule the
+    # user opted in, the never-list and chi's own files, the probability, and
+    # the rule's record. Any one that fails leaves the ask to the user. The
+    # entries are the judgment log read once for this ask.
+    # @param entries [Array<Hash>] SystemOne::Log#entries
+    def system_one_auto_allow?(client, approval, p, entries)
+      return false unless client.mode == "on"
+
+      rule = approval[:rule].to_s
+      return false if rule.empty?
+      return false unless system_one_rules.include?(rule)
+      return false if SystemOne::SelfProtect.refuse?(approval)
+
+      threshold = Config.get("guardrails.system_one.threshold").to_f
+      return false if p.nil? || p.to_f < threshold
+
+      min_record = Config.get("guardrails.system_one.min_record").to_i
+      SystemOne::Record.new(entries, rule: rule).qualifies?(threshold: threshold, min_record: min_record)
+    rescue StandardError => e
+      Samagotchi::Log.warn(:guardrails, "system_one_gate_failed", error: "#{e.class}: #{e.message}")
+      false
+    end
+
+    # guardrails.system_one.rules: a "|"-separated string or a YAML list,
+    # read with the same grammar as guardrails.small_models.
+    def system_one_rules
+      ModelMatch.parse(Config.get("guardrails.system_one.rules"))
+    rescue StandardError
+      []
+    end
+
+    # The user's answer to that ask, as a label on the judgment: the scope
+    # they took, a denial, or none for an ask that was cancelled. A parent
+    # agent's answer is not the user's: its allow labels nothing, and its
+    # deny is a label only where the parent could have allowed — a parent
+    # that was not allowed to permit says nothing about what the user would
+    # have done (docs/guardrails.md, "System 1").
+    def system_one_label(judgment, answer, payload)
+      id = judgment && judgment[:id]
+      return nil if id.nil?
+
+      scopes = Array(payload[:approval][:scopes])
+      if !answer.is_a?(Samagotchi::QuestionAnswer)
+        label = "none"
+      elsif answer.parent_agent?
+        return nil if parent_allowed?(answer, scopes) || !parent_may_permit?(payload)
+
+        label = "deny"
+      else
+        index = answer.selected_indices.first
+        label = if index && index < scopes.size
+                  scopes[index] == "once" ? "allow_once" : "allow_wide"
+                else
+                  "deny"
+                end
+      end
+      system_one_log.label(id, label)
+    rescue StandardError => e
+      Samagotchi::Log.warn(:guardrails, "system_one_label_failed", error: "#{e.class}: #{e.message}")
+      nil
+    end
+
+    # Whether a parent's answer picked one of the offered scopes.
+    def parent_allowed?(answer, scopes)
+      index = answer.selected_indices.first
+      !index.nil? && index < scopes.size
+    end
+
+    # Whether this session's parent level lets a parent allow a call at all,
+    # and the ask is not one only the user may answer.
+    def parent_may_permit?(payload)
+      return false if payload[:user_only]
+
+      Guardrails::ParentPolicy.for_session(@session_lookup.call).allow?("permit")
+    end
+
     # The work tree top of the session's working_directory (the folder
     # itself outside a repo, or when it's gone); never Dir.pwd, which is
     # the waker's cwd for a worker whose folder is gone.

data/lib/samagotchi/guardrails/approval.rb

@@ -51,6 +51,9 @@ module Samagotchi
             paths: targets && !targets.paths.empty? ? targets.paths : nil,
             # No command or path (an MCP tool): its arguments, as the question.
             args: args_for_card(targets),
+            # A memory_write ask, in words: the entry, its scope, and for a
+            # removal the description its index line carries.
+            memory: memory_for_card(targets),
             cwd: targets&.cwd,
             repo_root: targets&.repo_root,
             # The repository's name (a worktree's main checkout's folder).
@@ -78,6 +81,23 @@ module Samagotchi
         text.empty? ? nil : text
       end
 
+      # A memory_write ask names an entry, not a file: which one, and in which
+      # scope. For a removal the ask also carries that entry's description from
+      # its scoped index line, which is what System 1 otherwise cannot see
+      # (docs/guardrails.md, "System 1"). nil for every other tool.
+      def memory_for_card(targets)
+        entry = targets&.memory
+        return nil if entry.nil?
+
+        facts = { name: entry[:name], scope: entry[:scope] }
+        if targets.memory_remove?
+          require_relative "../memory_bundle/index_updater"
+          description = MemoryBundle::IndexUpdater.description_for(entry[:scope], entry[:name])
+          facts[:description] = description unless description.to_s.strip.empty?
+        end
+        facts
+      end
+
       # Settle +verdict+ from open_question's result.
       # @param answer [QuestionAnswer, Hash, String] the answer, or {error:} (anything else is a cancel)
       # @param scopes [Array<String>] the offered scopes, in option order

data/lib/samagotchi/guardrails/targets.rb

@@ -74,6 +74,12 @@ module Samagotchi
       attr_reader :memory_overlay
       alias memory_overlay? memory_overlay
 
+      # @return [Hash, nil] a memory_write call's entry and its scope,
+      #   {name:, scope:}: which memory the ask is about, in words rather than
+      #   as the file it names (#paths); nil for another tool or a call the
+      #   tool would refuse
+      attr_reader :memory
+
       # @param call [Hash] the parsed tool call
       # @param context [Context]
       # @param model_key [String, nil] for a memory_write model overlay, and
@@ -114,9 +120,10 @@ module Samagotchi
         end
         memory_remove = tool == "memory_write" && call[:remove].to_s.strip.downcase == "true"
         memory_overlay = tool == "memory_write" && !memory_remove && call[:current_model_only].to_s.strip.downcase == "true"
+        memory = tool == "memory_write" ? memory_facts(call) : nil
         new(tool: tool, command: command, paths: paths.compact, cwd: cwd, repo_root: context.repo_root(cwd),
             repo: context.repo(cwd), args: args, acts_as: acts_as, label: label, memory_remove: memory_remove,
-            memory_overlay: memory_overlay,
+            memory_overlay: memory_overlay, memory: memory,
             model_name: model_name, model_key: model_key, session_root: context.repo_root(base) || base,
             chi_dirs: -> { chi_dirs(context, base) })
       end
@@ -224,14 +231,28 @@ module Samagotchi
         nil
       end
 
+      # The memory a memory_write call is about, in the words the ask needs:
+      # the entry and its scope, not its file; nil for a call the tool would
+      # refuse (no entry, no scope, a scope chi has no folder for).
+      def self.memory_facts(call)
+        entry = call[:path].to_s.strip
+        scope = Tools::MemoryRead.normalize_scope(call[:scope])
+        return nil if entry.empty? || scope.nil?
+
+        { name: entry, scope: scope }
+      rescue StandardError
+        nil
+      end
+
       # @param chi_dirs [#call, nil] → the dirs touches_chi? looks for
       def initialize(tool:, command:, paths:, cwd:, repo_root:, repo: nil, args: nil, acts_as: nil, label: nil,
                      model_name: nil, model_key: nil, session_root: nil, chi_dirs: nil, memory_remove: false,
-                     memory_overlay: false)
+                     memory_overlay: false, memory: nil)
         @acts_as = acts_as
         @label = label
         @memory_remove = memory_remove
         @memory_overlay = memory_overlay
+        @memory = memory
         @repo = repo
         @chi_dirs = chi_dirs
         @session_root = session_root || repo_root || cwd

data/lib/samagotchi/guardrails/verdict.rb

@@ -19,8 +19,10 @@ module Samagotchi
       # parent model would be writing a model's prompt); and the bundle's
       # asks before answering chi's questions around chi answer (a parent
       # allowing one would answer a grandchild's question as the user).
-      # Only the user may allow them (ParentApprovals.protected?,
-      # ParentPolicy's user_only).
+      # A parent agent may never allow them (ParentApprovals.protected?,
+      # ParentPolicy's user_only); System 1 may, only if the user lists the
+      # rule by name in guardrails.system_one.rules, and never for the
+      # chi-answer/chi-broadcast ones (SystemOne::SelfProtect::NEVER_AUTO).
       PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd chi-broadcast prompt-memory-write
                            model-overlay-write chi-answer-piped chi-answer-http].freeze
       SCOPES = %w[once session repo rule].freeze
@@ -33,6 +35,8 @@ module Samagotchi
       attr_accessor :context, :targets
       # The scope the user allowed an ask for ("once", "session", …).
       attr_accessor :scope
+      # System 1's judgment that decided an ask, when it did: {id:, p:}.
+      attr_accessor :judgment
 
       def initialize(call:)
         @call = call
@@ -121,8 +125,11 @@ module Samagotchi
       end
 
       # For the activity entry; an allowed ask notes how ("approved (repo)",
-      # "approved earlier (session)").
+      # "approved earlier (session)"), one System 1 answered notes that and
+      # carries the judgment (docs/guardrails.md, "System 1").
       def to_activity
+        return system_one_activity if @decided_by == "system one"
+
         note = if allow? && @scope
                  "approved#{" earlier" if @decided_by == "approval"} (#{@scope})"
                end
@@ -131,6 +138,19 @@ module Samagotchi
 
       private
 
+      # The auto-allow's activity: who decided, for how long, and the
+      # judgment behind it (the p and the judgment's id), so a UI can show
+      # why the call was never asked about.
+      def system_one_activity
+        facts = @judgment || {}
+        p = facts[:p]
+        activity = { rule: @rule, verdict: @decision.to_s, decided_by: @decided_by, scope: @scope,
+                     note: p ? "auto-allowed by System 1 (p=#{format("%.2f", p.to_f)})" : "auto-allowed by System 1" }
+        activity[:judgment_id] = facts[:id] if facts[:id]
+        activity[:p] = p if p
+        activity.compact
+      end
+
       def decider
         return [("rule #{@rule}" if @rule), @source].compact.join(", ") if @rule || @source
 

data/lib/samagotchi/guardrails_command.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "config"
+require_relative "bridge/card_store"
+require_relative "guardrails/approvals"
+require_relative "guardrails/parent_policy"
+require_relative "host_registry"
+require_relative "session"
+require_relative "system_one"
+
+module Samagotchi
+  # `chi guardrails`: the guardrails' own maintenance commands, on this
+  # machine only (docs/guardrails.md, "System 1"). `replay` is the record
+  # seed: System 1 judges every approval this machine's sessions already
+  # answered, and the judgment and the user's answer go to the log as they
+  # would live. A rule's record then starts with the asks the user really
+  # decided on, instead of waiting for a few days of live ones.
+  class GuardrailsCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi guardrails <subcommand> [options]
+        replay [--dry-run] [--threshold T] [--model M]
+          Judge every approval this machine's sessions have already answered
+          (their cards, $XDG_STATE_HOME/samagotchi/sessions/<id>/cards.json)
+          through System 1 and write the judgment and the user's answer to
+          guardrails/judgments.jsonl, so a rule's record starts with the asks
+          the user really decided on. Asks with no approval card, unanswered
+          ones, and question ids a previous replay already logged are skipped.
+          A parent agent's answer is not the user's: only its deny is logged,
+          and only when the parent could have allowed (the session's
+          guardrails.parent_answers allows "permit" and the ask is not
+          user-only). --threshold overrides guardrails.system_one.threshold
+          for the table; --model overrides the configured model for this run.
+          --dry-run judges and prints the table without writing a line. Needs
+          guardrails.system_one.mode audit or on and a guardrails.system_one.host
+          (exit 2 without one).
+    TEXT
+
+    SUBCOMMANDS = %w[replay].freeze
+    FLAGS = {
+      "replay" => CLI::Flags.new(help: HELP_WORDS, args: false) do |f|
+        f.switch "--dry-run"
+        f.value "--threshold"
+        f.value "--model"
+      end
+    }.freeze
+    # The labels that mean the user let the call through.
+    ALLOW_LABELS = %w[allow_once allow_wide].freeze
+    # replay's table, in column order: the rule, how many asks it had, how
+    # many the user allowed, how many they denied, how many System 1 would
+    # have auto-allowed at the threshold, the false allows among them (the
+    # model said allow, the user did not), and the asks with no judgment.
+    COLUMNS = %w[rule asks allowed denied auto false_allows no_judgment].freeze
+    # Why an ask in a cards file was not replayed, in the words the summary
+    # uses.
+    SKIP_WORDS = {
+      already_replayed: "already replayed",
+      answered_by_parent: "answered by a parent agent",
+      parent_cannot_allow: "answered by a parent that could not allow",
+      unanswered: "unanswered",
+      no_approval: "no approval card",
+      no_question_id: "no question id"
+    }.freeze
+
+    # One ask a replay judges: the card's question id, the session it came
+    # from, its approval as the card saved it, the label its answer gives,
+    # and when the user was asked.
+    Ask = Data.define(:question_id, :session_id, :approval, :label, :asked_at)
+
+    # @param argv [Array<String>] the arguments after "guardrails"
+    # @param client [SystemOne::Client, nil] the judgment client; nil: the
+    #   one config.yml describes (the seam the specs pass a fake through)
+    # @param sessions_dir [String, nil] where the sessions are; nil: this
+    #   machine's ($XDG_STATE_HOME/samagotchi/sessions)
+    # @param log [SystemOne::Log, nil] the judgments log; nil: the one beside
+    #   the approvals store
+    def initialize(argv, stdout: $stdout, stderr: $stderr, client: nil, sessions_dir: nil, log: nil)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @client = client
+      @sessions_dir = sessions_dir
+      @log = log
+    end
+
+    # @return [Integer] exit status: 0 done, 2 a usage error or no System 1
+    #   client to judge with
+    def run
+      @sub = @argv[0]
+      if @sub.nil? || HELP_WORDS.include?(@sub)
+        @stdout.puts(USAGE)
+        return CLI::Exit::OK
+      end
+      return usage_error("unknown subcommand #{@sub}") unless SUBCOMMANDS.include?(@sub)
+
+      parsed = parse_flags(FLAGS.fetch(@sub), @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+
+      replay(parsed.options)
+    end
+
+    private
+
+    def command_name = @sub ? "chi guardrails #{@sub}" : "chi guardrails"
+
+    def replay(options)
+      threshold = threshold(options[:threshold])
+      return usage_error(threshold) if threshold.is_a?(String)
+
+      client = @client || SystemOne::Client.from_config(host_registry: HostRegistry.new, model: options[:model])
+      if client.nil?
+        error_line("chi guardrails replay: no System 1 client — set guardrails.system_one.mode to audit or on " \
+                   "and guardrails.system_one.host in config.yml")
+        return CLI::Exit::USAGE
+      end
+
+      sessions_dir = @sessions_dir || Session.default_state_dir
+      log = @log || SystemOne::Log.new(dir: Guardrails::Approvals.dir_for(sessions_dir))
+      replayed = File.exist?(log.path) ? log.entries.filter_map { |entry| entry["question_id"] if entry["origin"] == "replay" }.to_set : Set.new
+      @dry_run = options[:dry_run] ? true : false
+
+      asks = []
+      skipped = Hash.new(0)
+      malformed = 0
+      if Dir.exist?(sessions_dir)
+        Dir.children(sessions_dir).sort.each do |name|
+          path = File.join(sessions_dir, name, Bridge::CardStore::FILE)
+          next unless File.file?(path)
+
+          entries = sidecar(path)
+          if entries.nil?
+            malformed += 1
+            next
+          end
+
+          entries.each do |entry|
+            ask = ask_of(entry, name, replayed, sessions_dir)
+            next if ask.nil?
+
+            ask.is_a?(Symbol) ? skipped[ask] += 1 : asks << ask
+          end
+        end
+      end
+
+      stats = asks.map { |ask| judge(ask, client, log, threshold, sessions_dir) }
+      print_table(stats, threshold, client, skipped, malformed)
+      CLI::Exit::OK
+    end
+
+    # The asks of one session's cards file, or nil when it isn't one: a
+    # sidecar that doesn't parse costs one warning line, never the run.
+    def sidecar(path)
+      return nil unless File.file?(path)
+
+      data = JSON.parse(File.read(path), symbolize_names: true)
+      return nil unless data.is_a?(Hash) && data[:entries].is_a?(Array)
+
+      data[:entries]
+    rescue StandardError => e
+      error_line("chi guardrails replay: #{path}: unreadable cards (#{e.class}: #{e.message}); skipped")
+      nil
+    end
+
+    # One card entry as an ask to judge: an Ask, a skip reason (:already_replayed,
+    # :answered_by_parent, :parent_cannot_allow, :unanswered, :no_approval,
+    # :no_question_id), or nil for an entry that is not a question at all.
+    def ask_of(entry, session_id, replayed, sessions_dir)
+      return nil unless entry.is_a?(Hash) && entry[:type] == "question"
+
+      pending = entry[:pending_question]
+      return :no_approval unless pending.is_a?(Hash) && pending[:approval].is_a?(Hash)
+
+      question_id = pending[:id].to_s
+      return :no_question_id if question_id.empty?
+      return :already_replayed if replayed.include?(question_id)
+
+      answer = entry[:answer]
+      label = if entry[:cancelled]
+                "none"
+              elsif answer.nil?
+                return :unanswered
+              elsif answer[:by] == "parent_agent"
+                # A parent's allow is not the user's decision. Its deny is a
+                # label only where the parent could have allowed: a parent
+                # that was not allowed to permit says nothing about the user
+                # (docs/guardrails.md, "System 1").
+                return :answered_by_parent unless label_for(answer, pending[:approval][:scopes]) == "deny"
+                return :parent_cannot_allow unless parent_may_permit?(pending, session_id, sessions_dir)
+
+                "deny"
+              else
+                label_for(answer, pending[:approval][:scopes])
+              end
+
+      Ask.new(question_id: question_id, session_id: session_id, approval: pending[:approval],
+              label: label, asked_at: pending[:created_at])
+    end
+
+    # Whether this session's parent could have allowed the ask: not a
+    # user-only ask, and a parent level that permits one. No session file:
+    # not permitted.
+    def parent_may_permit?(pending, session_id, sessions_dir)
+      return false if pending[:user_only] == true
+
+      session = session_of(session_id, sessions_dir)
+      return false if session.nil?
+
+      Guardrails::ParentPolicy.for_session(session).allow?("permit")
+    end
+
+    # The session a card belongs to, or nil when there is no session file;
+    # read once per session for the run.
+    def session_of(session_id, sessions_dir)
+      return nil unless Session.valid_id?(session_id)
+      return nil unless File.exist?(Session.session_file(session_id, state_dir: sessions_dir))
+
+      (@sessions ||= {})[session_id] ||= begin
+        Session.load(session_id, state_dir: sessions_dir)
+      rescue StandardError
+        nil
+      end
+    end
+
+    # What the user did, as the log's label: the scope they took, a denial
+    # when the answer is not one of the offered scopes, none for an ask that
+    # was cancelled (docs/guardrails.md, "System 1").
+    def label_for(answer, scopes)
+      index = answer[:selected_indices]&.first
+      return "deny" if index.nil?
+
+      scopes = Array(scopes)
+      if index < scopes.size
+        scopes[index] == "once" ? "allow_once" : "allow_wide"
+      else
+        "deny"
+      end
+    end
+
+    # Judge one ask, write its two lines unless this is a dry run, and return
+    # what the table counts. A judgment that never came is written with p
+    # null, exactly as the live audit writes it.
+    def judge(ask, client, log, threshold, sessions_dir)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      answers = begin
+        client.ask(state: SystemOne::ApprovalQuestion.state(ask.approval, session_title: session_title(ask, sessions_dir)),
+                   questions: { SystemOne::ApprovalQuestion::ID => SystemOne::ApprovalQuestion.question })
+      rescue StandardError => e
+        Samagotchi::Log.warn(:guardrails, "system_one_replay_ask_failed", error: "#{e.class}: #{e.message}")
+        nil
+      end
+      latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+      p = answers && answers[SystemOne::ApprovalQuestion::ID]&.noul
+
+      unless @dry_run
+        id = log.judgment(session_id: ask.session_id, rule: ask.approval[:rule], source: ask.approval[:source],
+                          tool: ask.approval[:tool], **SystemOne::ApprovalQuestion.call_fields(ask.approval),
+                          repo_name: ask.approval[:repo_name], p: p, threshold: threshold, model: client.model,
+                          latency_ms: latency_ms, decision: "replay", origin: "replay",
+                          question_id: ask.question_id, asked_at: ask.asked_at)
+        log.label(id, ask.label)
+      end
+
+      { rule: ask.approval[:rule].to_s, label: ask.label, p: p, session: ask.session_id }
+    end
+
+    # The session's title, as the ask's state carries it; nil when there is
+    # no session file (the cards alone are enough to replay).
+    def session_title(ask, sessions_dir)
+      session_of(ask.session_id, sessions_dir)&.display_title
+    end
+
+    # The threshold for this run: --threshold, or guardrails.system_one.threshold.
+    # @return [Float, String] the number, or the usage error's message
+    def threshold(value)
+      return Config.get("guardrails.system_one.threshold").to_f if value.nil?
+
+      number = Float(value.to_s.strip)
+      return "--threshold takes a number between 0 and 1, got #{value}" if number.negative? || number > 1.0
+
+      number
+    rescue ArgumentError, TypeError
+      "--threshold takes a number between 0 and 1, got #{value}"
+    end
+
+    def print_table(stats, threshold, client, skipped, malformed)
+      rows = stats.group_by { |row| row[:rule] }.map { |rule, asks| rule_row(rule, asks, threshold) }
+      rows.sort_by! { |rule, count, _| [-count, rule] }
+      totals = ["total", *COLUMNS[1..].each_with_index.map { |_column, offset| rows.sum { |row| row[offset + 1] } }]
+      all = rows + [totals]
+      widths = COLUMNS.each_with_index.map { |column, index| [column.size, all.map { |row| row[index].to_s.size }.max].max }
+
+      @stdout.puts(row_line(COLUMNS, widths))
+      @stdout.puts(widths.map { |width| "-" * width }.join("  "))
+      rows.each { |row| @stdout.puts(row_line(row, widths)) }
+      @stdout.puts(row_line(totals, widths))
+
+      sessions = stats.map { |row| row[:session] }.uniq.size
+      @stdout.puts("#{stats.size} asks replayed from #{sessions} session#{"s" unless sessions == 1} " \
+                   "· threshold #{threshold} · model #{client.model || "the host's default"}")
+      notes = skipped.map { |reason, count| "#{count} #{SKIP_WORDS[reason] || reason}" }
+      notes << "#{malformed} unreadable cards file#{"s" unless malformed == 1}" if malformed.positive?
+      @stdout.puts("skipped: #{notes.sort.join(", ")}") unless notes.empty?
+      @stdout.puts("dry run: nothing was written") if @dry_run
+    end
+
+    # One table row, columns left-aligned to their width.
+    def row_line(values, widths)
+      values.each_with_index.map { |value, index| value.to_s.ljust(widths[index]) }.join("  ").rstrip
+    end
+
+    # One rule's row: asks, allowed, denied, auto-allowed at the threshold,
+    # false allows, asks with no judgment.
+    def rule_row(rule, rows, threshold)
+      allowed = rows.count { |row| ALLOW_LABELS.include?(row[:label]) }
+      denied = rows.count { |row| row[:label] == "deny" }
+      high = rows.select { |row| row[:p] && row[:p] >= threshold }
+      [rule, rows.size, allowed, denied,
+       high.count { |row| ALLOW_LABELS.include?(row[:label]) },
+       high.count { |row| row[:label] == "deny" },
+       rows.count { |row| row[:p].nil? }]
+    end
+  end
+end