samagotchi 0.115.0 → 0.117.0

data/lib/samagotchi/session_manager.rb

@@ -1141,11 +1141,12 @@ module Samagotchi
     #   there is no live SSE or in-process cancel/answer).
     # @param on_input [#call, nil] called after the Bridge queues a turn
     def self.start_bridge(engine:, state_dir:, session_id:, on_input: nil, on_command: nil, on_exit_request: nil,
-                          exit_discards: nil)
+                          exit_discards: nil, exit_stopped: nil, on_holds: nil, on_holds_stop: nil)
       require_relative "bridge"
       Samagotchi::Bridge.new(
         engine: engine, state_dir: state_dir, session_id: session_id, input_format: SessionInbox::INPUT_FORMAT,
-        on_input: on_input, on_command: on_command, on_exit_request: on_exit_request, exit_discards: exit_discards
+        on_input: on_input, on_command: on_command, on_exit_request: on_exit_request, exit_discards: exit_discards,
+        exit_stopped: exit_stopped, on_holds: on_holds, on_holds_stop: on_holds_stop
       ).start
     rescue StandardError => e
       Log.error(:bridge, "start_failed", echo: "Bridge: failed to start for session #{session_id}: #{e.class}: #{e.message}", sid: session_id, error: e.class.name)

data/lib/samagotchi/session_metrics.rb

@@ -1106,6 +1106,12 @@ module Samagotchi
         active[:via] = via.to_s if via
         # A grep that found nothing (ok): the reloaded web row says "no match".
         active[:no_match] = true if event.dig(:activity, :no_match)
+        # Allowed once by System 1 instead of the user: the reloaded web row
+        # says so and can flag the judgment it came from.
+        guardrail = event.dig(:activity, :guardrail)
+        if guardrail.is_a?(Hash) && guardrail[:decided_by] == "system one"
+          active[:guardrail] = { rule: guardrail[:rule], p: guardrail[:p], judgment_id: guardrail[:judgment_id] }.compact
+        end
         finish_tool_record(active, status.empty? ? "ok" : status, waited_ms: event[:waited_ms].to_i)
       end
     end
@@ -1113,7 +1119,7 @@ module Samagotchi
     # Caller holds the mutex.
     def finish_tool_record(active, status, waited_ms: 0)
       record = active.slice(
-        :id, :turn_id, :iteration, :call_index, :tool, :called_as, :via, :no_match, :started_at
+        :id, :turn_id, :iteration, :call_index, :tool, :called_as, :via, :no_match, :guardrail, :started_at
       ).merge(
         status: status,
         completed_at: now.iso8601(3),

data/lib/samagotchi/system_one/answer.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "question"
+
+module Samagotchi
+  module SystemOne
+    # One judgment the System One API answered: for an :noul question,
+    # `noul` is the probability of "yes"; a :choice answer carries `choice`
+    # (the criterion chosen) and `confidence`; a :score answer carries
+    # `score` (the level's index) and `confidence`. `probabilities` is what
+    # the model put on each option, when it says.
+    Answer = Data.define(:id, :type, :noul, :choice, :score, :confidence, :probabilities) do
+      def initialize(id:, type:, noul: nil, choice: nil, score: nil, confidence: nil, probabilities: nil) = super
+
+      # The response's answers entry as the wire sends it, or nil when it is
+      # not usable: no type, a type the contract doesn't have, a noul
+      # outside 0..1, a score that isn't a whole number, … A nil means "no
+      # judgment for this question", never a guess.
+      def self.from_wire(id, raw)
+        return nil unless raw.is_a?(Hash)
+
+        type = raw["type"].to_s.strip.downcase.to_sym
+        return nil unless QUESTION_TYPES.include?(type)
+
+        confidence = probability(raw["confidence"])
+        odds = probabilities(raw["probabilities"])
+        # A field the server sent but can't read is as unusable as a missing answer.
+        return nil if bad_field(raw, "confidence", confidence) || bad_field(raw, "probabilities", odds)
+
+        answer = { id: id, type: type, confidence: confidence, probabilities: odds }
+
+        case type
+        when :noul
+          noul = probability(raw["noul"])
+          noul.nil? ? nil : new(**answer, noul: noul)
+        when :choice
+          choice = raw["choice"].to_s.strip
+          choice.empty? ? nil : new(**answer, choice: choice)
+        else
+          score = raw["score"]
+          score = score.to_i if score.is_a?(Float) && score.to_i == score
+          score.is_a?(Integer) && score >= 0 ? new(**answer, score: score) : nil
+        end
+      end
+
+      # A value the wire sent that we could not parse.
+      private_class_method def self.bad_field(raw, name, parsed)
+        raw.key?(name) && !raw[name].nil? && parsed.nil?
+      end
+
+      # A probability as written: a number in 0..1, else nil.
+      private_class_method def self.probability(value)
+        return nil unless value.is_a?(Numeric)
+
+        value = value.to_f
+        return nil if value.nan? || value.infinite? || value.negative? || value > 1.0
+
+        value
+      end
+
+      # The probabilities as sent: a map of option => number, or a list of
+      # numbers (the options in order). Anything else is malformed.
+      private_class_method def self.probabilities(value)
+        if value.is_a?(Hash)
+          pairs = value.map { |name, weight| [name.to_s, probability(weight)] }
+          return nil if pairs.any? { |_name, weight| weight.nil? }
+
+          pairs.to_h
+        elsif value.is_a?(Array)
+          weights = value.map { |weight| probability(weight) }
+          return nil if weights.any?(&:nil?)
+
+          weights
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/system_one/approval_question.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "question"
+require_relative "similar"
+
+module Samagotchi
+  module SystemOne
+    # The one question an approval asks System 1: "would this user allow it
+    # without hesitation?" (docs/guardrails.md, "System 1"). The instruction
+    # is a constant in code, reviewed like a prompt; the state is the ask's
+    # own facts — the rule that asked, why, the call, and where it runs — plus
+    # the memory an ask names and the earlier asks it resembles.
+    module ApprovalQuestion
+      ID = "allow"
+      # What the judgment is asked, in the model's terms. Frozen: a change
+      # here is a change in behaviour, not a wording tweak.
+      INSTRUCTIONS = "A coding agent wants to run this tool call, and a guardrail rule asked its user to approve it. " \
+                     "The state names the rule, why it asked, the call and where it runs. Would the user approve it " \
+                     "without hesitation? Users usually approve routine reads, edits of the agent's own notes and " \
+                     "memory, and pushes of verified work; they usually refuse discarding uncommitted work, " \
+                     "interactive rebases, deleting outside the project, and anything irreversible they did not ask " \
+                     "for. The state may also list a few of the user's earlier decisions on calls like this one, " \
+                     "most alike first, each with what they answered."
+      # How much of a command, a diff or a path list the state carries.
+      TEXT_CHARS = 2000
+      # How much of the call the judgment log keeps; its digest is of the whole.
+      CALL_CHARS = 300
+
+      # @return [Question] the noul question for id "allow"
+      def self.question
+        # The type as a string: a symbol here reads as an event type to
+        # spec/web/participant_view_spec.
+        Question.new(id: ID, type: "noul", instructions: INSTRUCTIONS)
+      end
+
+      # @param approval [Hash] payload[:approval]: the ask the user is shown
+      # @param session_title [String, nil] the session's title, when it has one
+      # @param entries [Array<Hash>] SystemOne::Log#entries: the judgments the
+      #   user has answered so far, read once per ask and shared with the
+      #   record gate (GuardrailWiring#system_one_judge)
+      # @return [Hash] the state, with the fields the ask didn't give left out
+      def self.state(approval, session_title: nil, entries: nil)
+        {
+          "rule" => approval[:rule],
+          "source" => approval[:source],
+          "reason" => approval[:reason],
+          "tool" => approval[:tool],
+          "command" => cut(approval[:command]),
+          "paths" => Array(approval[:paths]).map { |path| cut(path) },
+          "change" => change_text(approval[:preview]),
+          "cwd" => approval[:cwd],
+          "repo_name" => approval[:repo_name],
+          "branch" => approval[:branch],
+          "session" => session_title,
+          # Which memory entry the ask is about, when it is a memory ask.
+          "memory" => memory_facts(approval[:memory]),
+          # The asks this one looks like, and what the user did about them.
+          "examples" => Similar.select(entries: entries, rule: approval[:rule], repo_name: approval[:repo_name],
+                                       call_text: call_text(approval))
+        }.reject do |_key, value|
+          value.nil? || (value.is_a?(String) && value.strip.empty?) ||
+            ((value.is_a?(Array) || value.is_a?(Hash)) && value.empty?)
+        end
+      end
+
+      # What the call is, whole: the command, the paths, or a plugin tool's
+      # arguments.
+      def self.call_text(approval)
+        command = approval[:command]
+        return command.to_s if command && !command.to_s.empty?
+
+        paths = Array(approval[:paths])
+        return paths.join("\n") unless paths.empty?
+
+        approval[:args].to_s
+      end
+
+      # The judgment log's two fields for the call: what it was, cut to
+      # CALL_CHARS, and the SHA256 of the whole of it.
+      def self.call_fields(approval)
+        call = call_text(approval)
+        { "call" => cut(call, CALL_CHARS), "call_digest" => Digest::SHA256.hexdigest(call) }
+      end
+
+      # The memory an ask is about, as the approval card built it: entry name,
+      # scope, and (for a removal) the description its index line carries.
+      private_class_method def self.memory_facts(memory)
+        return nil unless memory.is_a?(Hash) && !memory.empty?
+
+        memory.transform_keys(&:to_s).reject { |_key, value| value.to_s.strip.empty? }
+      end
+
+      private_class_method def self.change_text(preview)
+        return nil unless preview.is_a?(Hash)
+
+        text = preview[:text] || preview["text"]
+        return cut(text) if text && !text.to_s.strip.empty?
+
+        note = preview[:error] || preview["error"] || preview[:skipped] || preview["skipped"]
+        return note.to_s unless note.to_s.strip.empty?
+
+        "+#{(preview[:added] || preview["added"]).to_i} −#{(preview[:removed] || preview["removed"]).to_i}"
+      end
+
+      private_class_method def self.cut(text, chars = TEXT_CHARS)
+        text = text.to_s
+        text.length > chars ? "#{text[0, chars - 1]}…" : text
+      end
+    end
+  end
+end

data/lib/samagotchi/system_one/client.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../log"
+require_relative "answer"
+require_relative "errors"
+require_relative "http_backend"
+require_relative "question"
+
+module Samagotchi
+  module SystemOne
+    # The one way anything asks System 1 a question: #ask answers a set of
+    # questions about a state, or says nothing. A backend that is unreachable,
+    # slow, refusing or nonsensical is a nil — no judgment, one log line — and
+    # the caller asks the user as it would have anyway.
+    #
+    #   client = SystemOne::Client.from_config(host_registry: registry)
+    #   client&.ask(state: "git push origin main", questions: {"allow" => question})
+    class Client
+      MODES = %w[off audit on].freeze
+      DEFAULT_TIMEOUT_MS = 2000
+
+      attr_reader :mode, :host, :model, :backend
+
+      def initialize(backend:, mode: "off", host: nil, model: nil)
+        @backend = backend
+        @mode = mode.to_s.strip.downcase
+        @host = host
+        @model = model
+      end
+
+      # nil when judgment is off (the default) or no host is named, so the
+      # caller needs no other check. The settings are read every call: a
+      # config.yml change takes effect on the next ask.
+      # @param model [String, nil] a model for this call only (chi guardrails
+      #   replay --model), else the configured one
+      def self.from_config(host_registry:, env: ENV, model: nil)
+        mode = Config.get("guardrails.system_one.mode").to_s.strip.downcase
+        return nil unless MODES.include?(mode) && mode != "off"
+
+        host = Config.get("guardrails.system_one.host").to_s.strip
+        return nil if host.empty?
+
+        model = (model.nil? ? Config.get("guardrails.system_one.model") : model).to_s.strip
+        timeout_ms = Config.get("guardrails.system_one.timeout_ms").to_i
+        timeout_ms = DEFAULT_TIMEOUT_MS unless timeout_ms.positive?
+
+        new(backend: HttpBackend.new(host_registry: host_registry, host: host, model: model.empty? ? nil : model,
+                                     timeout_ms: timeout_ms, env: env),
+            mode: mode, host: host, model: model.empty? ? nil : model)
+      end
+
+      # @param state [String, Hash, Array] what the question is about, as the
+      #   contract takes it
+      # @param questions [Hash{String => Question|Hash}] the questions, by id
+      # @return [Hash{String => Answer}, nil] one Answer per question, or nil
+      #   when there is no judgment at all
+      def ask(state:, questions:, cancel_controller: nil)
+        questions = SystemOne.normalize_questions(questions)
+        return nil if questions.empty?
+
+        answers = begin
+          @backend.ask(state: state, questions: questions, cancel_controller: cancel_controller)
+        rescue StandardError => e
+          return no_judgment("#{e.class}: #{e.message}", error: e.class.name)
+        end
+
+        unless answers.is_a?(Hash)
+          return no_judgment("the backend returned #{answers.inspect}")
+        end
+
+        answers = questions.to_h { |question| [question.id, answers[question.id]] }
+        missing = questions.reject { |question| answers[question.id].is_a?(Answer) }
+        return no_judgment("no answer for #{missing.map(&:id).join(", ")}") unless missing.empty?
+
+        answers
+      end
+
+      private
+
+      # One warn, one nil: the ask goes to the user.
+      def no_judgment(reason, **fields)
+        # Qualified: inside SystemOne, the bare Log is now SystemOne::Log.
+        Samagotchi::Log.warn(:guardrails, "system_one_failed", echo: "[samagotchi:guardrails] system one: #{reason}", host: @host, **fields)
+        nil
+      end
+    end
+  end
+end

data/lib/samagotchi/system_one/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module SystemOne
+    # A judgment that did not happen: the backend could not reach the host,
+    # the host refused the request, or its answer was not usable. Client#ask
+    # turns any of these into nil (no judgment), so the caller asks the user.
+    class BackendError < StandardError; end
+
+    # The named host is not a System One host: it isn't in hosts:, its api
+    # is not openai, or it names no model.
+    class UnsupportedHost < BackendError; end
+  end
+end

data/lib/samagotchi/system_one/fake_backend.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Samagotchi
+  module SystemOne
+    # The backend the specs use: answers from a block, from a fixed hash, or
+    # an error every time. It never reaches the network.
+    #
+    #   FakeBackend.new { |state, questions| {questions.first.id => answer} }
+    #   FakeBackend.new("git-push" => Answer.from_wire("git-push", {"type" => "noul", "noul" => 0.97}))
+    #   FakeBackend.new(failing: true)
+    class FakeBackend
+      attr_reader :calls
+
+      # @param answers [Hash{String => Answer}, nil] the same answers for
+      #   every call
+      # @param failing [Boolean] true: every #ask raises
+      # @param error [String] what a failing backend says
+      # @param judgments [#call] (state, questions) => {id => Answer}
+      def initialize(answers = nil, failing: false, error: "fake System One backend is unavailable", &judgments)
+        @answers = answers
+        @judgments = judgments
+        @failing = failing
+        @error = error
+        @calls = 0
+      end
+
+      def ask(state:, questions:, cancel_controller: nil)
+        @calls += 1
+        raise BackendError, @error if @failing
+
+        judged = @judgments&.call(state, questions)
+        return judged unless judged.nil?
+
+        ids = Array(questions).map { |question| question.respond_to?(:id) ? question.id : question.to_s }
+        (@answers || {}).select { |id, _answer| ids.include?(id) }
+      end
+
+      def failing? = @failing
+
+      def inspect = "#<#{self.class.name} calls=#{@calls}#{" failing" if @failing}>"
+    end
+  end
+end

data/lib/samagotchi/system_one/http_backend.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require_relative "../config"
+require_relative "../llm/api_key"
+require_relative "../llm/http"
+require_relative "answer"
+require_relative "question"
+require_relative "errors"
+
+module Samagotchi
+  module SystemOne
+    # The TypeSafe System One judgment API on a host from config.yml's
+    # `hosts:`: POST <openai_base_url>/systemone (that base already ends in
+    # /v1), one request per #ask, no retries — a judgment that doesn't
+    # arrive in time is no judgment, and the ask goes to the user.
+    #
+    # Works for Splash (a local `api: openai` host serving /v1/systemone)
+    # and for the hosted Jev API the same way; a host whose api isn't
+    # openai is refused.
+    class HttpBackend
+      DEFAULT_TIMEOUT_MS = 2000
+
+      # @param host_registry [HostRegistry] where the host is looked up
+      # @param host [String] the hosts: entry name
+      # @param model [String, nil] the judgment model; nil: the host's first
+      #   model (hosts.<name>.models), and no judgment when it has none
+      # @param timeout_ms [Integer] the whole request's limit, in ms
+      # @param env [Hash] where the host's api_key_env: key is read
+      def initialize(host_registry:, host:, model: nil, timeout_ms: DEFAULT_TIMEOUT_MS, env: ENV)
+        @host_registry = host_registry
+        @host = host.to_s.strip.downcase
+        @model = model.nil? ? nil : model.to_s.strip
+        @timeout_ms = timeout_ms.to_i
+        @env = env
+      end
+
+      # @return [Hash{String => Answer}] one Answer per question, nil for a
+      #   question the response answered badly
+      # @raise [UnsupportedHost] the host is unknown, not an openai host, or
+      #   names no model
+      # @raise [BackendError] the request failed, the status isn't 200, or
+      #   the body isn't a usable response
+      def ask(state:, questions:, cancel_controller: nil)
+        entry = @host_registry.find_entry(@host)
+        raise UnsupportedHost, "host #{@host.inspect} is not in hosts:" unless entry
+        unless entry.api&.to_sym == :openai
+          raise UnsupportedHost, "host #{@host} has api: #{entry.api || "llama_cpp"}; System One speaks the OpenAI-compatible API"
+        end
+
+        model = @model || host_model(entry)
+        raise UnsupportedHost, "host #{@host} names no model for System One" if model.nil? || model.empty?
+
+        url = "#{entry.openai_base_url.to_s.chomp("/")}/systemone"
+        questions = SystemOne.normalize_questions(questions)
+        body = { model: model, state: state, questions: questions.to_h { |question| [question.id, question.to_wire] } }
+        request = json_post(url, body)
+        response = http(entry).fetch(URI(url), request, retries: false, check_status: false, cancel_controller: cancel_controller,
+                                     log_fields: { purpose: "system_one", model: model })
+
+        status = response.code.to_i
+        unless status == 200
+          raise BackendError, "#{@host}: #{status} #{error_detail(response.body)}"
+        end
+
+        answers = answers_of(response.body)
+        questions.to_h { |question| [question.id, Answer.from_wire(question.id, answers[question.id])] }
+      end
+
+      private
+
+      # The host's first model: whatever hosts.<name>.models holds, in the
+      # shape the registry has it in (HostModel by id, or as written).
+      def host_model(entry)
+        models = entry.models
+        return nil if models.nil? || models.empty?
+
+        first = models.is_a?(Hash) ? models.values.first : models.first
+        first.respond_to?(:id) ? first.id : first.to_s
+      end
+
+      # One attempt, closed on the timeout: a judgment is worth at most
+      # timeout_ms, not a retry chain.
+      def http(entry)
+        seconds = @timeout_ms.positive? ? @timeout_ms / 1000.0 : DEFAULT_TIMEOUT_MS / 1000.0
+        open_timeout = [seconds, Config.positive_seconds("server.open_timeout")].min
+        LLM::HTTP.new(label: entry.name, open_timeout: open_timeout, read_timeout: seconds,
+                      retry_policy: LLM::HTTP::RetryPolicy.none,
+                      api_key: LLM::ApiKey.for(entry.api_key_env, host: entry.name, env: @env, scheme: entry.auth_scheme))
+      end
+
+      # The POST the adapters build: JSON body, Content-Type, and the host's
+      # key on the header its auth: names (LLM::HTTP adds it).
+      def json_post(url, body)
+        Net::HTTP::Post.new(URI(url)).tap do |request|
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(body)
+        end
+      end
+
+      def answers_of(body)
+        data = JSON.parse(body.to_s)
+        raise BackendError, "the response is not JSON: #{body.to_s[0, 200]}" unless data.is_a?(Hash)
+
+        answers = data["answers"]
+        raise BackendError, "the response has no answers map" unless answers.is_a?(Hash)
+
+        answers
+      rescue JSON::ParserError => e
+        raise BackendError, "the response is not JSON: #{e.message[0, 200]}"
+      end
+
+      # A 422's detail array, or the body's start, for the log line.
+      def error_detail(body)
+        data = JSON.parse(body.to_s)
+        detail = data["detail"]
+        text = if detail.is_a?(Array)
+                 detail.map { |item| item.is_a?(Hash) ? item["msg"] || item.to_s : item.to_s }.join("; ")
+               else
+                 detail.to_s
+               end
+        text.empty? ? body.to_s[0, 200] : text[0, 200]
+      rescue StandardError
+        body.to_s[0, 200]
+      end
+    end
+  end
+end

data/lib/samagotchi/system_one/log.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+require "time"
+
+require_relative "../log"
+
+module Samagotchi
+  module SystemOne
+    # The judgments log: one JSON line per System 1 judgment, and a later
+    # line for the user's answer to the ask it judged (docs/guardrails.md,
+    # "System 1"). It sits beside the approvals store,
+    # `$XDG_STATE_HOME/samagotchi/guardrails/judgments.jsonl`, and is written
+    # append-only under an exclusive flock: several workers judge at once,
+    # and a line is never rewritten to add its label. Past 5 MB the file is
+    # rewritten, under the same lock, keeping the newest half of its lines.
+    #
+    # Nothing here can break an approval: every write that fails is one
+    # Log.warn and a nil, and the ask reaches the user as it would have.
+    class Log
+      FILE = "judgments.jsonl"
+      # Above this the file is rewritten keeping the newest half of the lines.
+      MAX_BYTES = 5 * 1024 * 1024
+      MODE = 0o600
+      # What a label's answer can be (P2a writes the first four;
+      # "should_have_asked" comes with `/guardrails wrong`).
+      ANSWERS = %w[allow_once allow_wide deny none should_have_asked].freeze
+
+      attr_reader :dir, :path
+
+      # @param dir [String] the guardrails store dir (Guardrails::Approvals.dir_for)
+      # @param warn [#call] (reason) — the record for a failed write
+      def initialize(dir:, warn: nil)
+        @dir = dir
+        @path = File.join(dir, FILE)
+        @warn = warn || ->(reason) { Samagotchi::Log.warn(:guardrails, "system_one_log_failed", echo: "[samagotchi:guardrails] #{reason}") }
+      end
+
+      # @param fields [Hash] the judgment's own fields (rule, tool, p, …)
+      # @return [String, nil] the judgment's id, nil when nothing was written
+      def judgment(fields)
+        id = SecureRandom.uuid
+        append({ "kind" => "judgment", "id" => id, "at" => Time.now.utc.iso8601 }.merge(fields)) ? id : nil
+      end
+
+      # @param id [String] a judgment's id
+      # @param answer [String] one of ANSWERS
+      # @return [Boolean] whether the line was written
+      def label(id, answer)
+        return false if id.to_s.strip.empty?
+
+        append({ "kind" => "label", "id" => id.to_s, "at" => Time.now.utc.iso8601, "answer" => answer.to_s })
+      end
+
+      # The judgments, oldest first, each joined with its LAST label
+      # (answer: nil when it has none). Lines that don't parse are skipped;
+      # labels of a judgment that isn't there are dropped.
+      # @return [Array<Hash>]
+      def entries
+        judgments = {}
+        labels = {}
+        with_lock(File::LOCK_SH) do |file|
+          file.each_line do |line|
+            data = parse(line)
+            next if data.nil?
+
+            case data["kind"]
+            when "judgment" then judgments[data["id"]] = data
+            when "label" then labels[data["id"]] = data["answer"] if data.key?("id")
+            end
+          end
+        end
+        judgments.map { |id, judgment| judgment.merge("answer" => labels[id]) }
+      rescue StandardError => e
+        warn_about(e)
+        []
+      end
+
+      private
+
+      def append(line)
+        with_lock(File::LOCK_EX) do |file|
+          # The handle is read-write (not O_APPEND) so #trim can rewrite the
+          # file: write at the end, under the lock nobody else holds.
+          file.seek(file.size)
+          file.puts(JSON.generate(line))
+          trim(file)
+        end
+        true
+      rescue StandardError => e
+        warn_about(e)
+        false
+      end
+
+      # @param mode [Integer] File::LOCK_EX for a write, LOCK_SH to read
+      def with_lock(mode)
+        FileUtils.mkdir_p(@dir)
+        File.open(@path, File::RDWR | File::CREAT, MODE) do |file|
+          file.flock(mode)
+          yield file
+        end
+      end
+
+      # Past MAX_BYTES, keep the newest half of the lines (whole, so a
+      # judgment and its labels stay together as far as the cut reaches).
+      def trim(file)
+        file.flush
+        return if file.size <= MAX_BYTES
+
+        file.rewind
+        lines = file.readlines
+        keep = lines.last([lines.size / 2, 1].max).join
+        file.rewind
+        file.write(keep)
+        file.flush
+        file.truncate(keep.bytesize)
+      end
+
+      def parse(line)
+        data = JSON.parse(line)
+        data.is_a?(Hash) ? data : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def warn_about(error)
+        @warn.call("system one log: #{path}: #{error.class}: #{error.message}")
+      end
+    end
+  end
+end