samagotchi 0.91.0 → 0.93.0

data/lib/samagotchi/send_command.rb

@@ -23,6 +23,8 @@ require_relative "vision_support"
 require_relative "cli/command"
 require_relative "cli/flags"
 require_relative "cli/parent_wait"
+require_relative "send_command/parent_gate"
+require_relative "send_command/wait_target"
 
 module Samagotchi
   # `chi send`: put text into sessions as the user's message, the same as
@@ -93,9 +95,9 @@ module Samagotchi
         --set BUNDLE.KEY=VALUE
                     (--new) a bundle setting for this session, over
                     config.yml's bundles: (repeatable; a key its bundle's
-                    manifest lists in session_settings:; 3, 2.5, true,
-                    false and off are typed, the rest is text:
-                    --set cost-cap.cap=3)
+                    manifest lists in session_settings:; numbers (3,
+                    .5) and booleans (true, off, no) are typed, the
+                    rest is text: --set cost-cap.cap=3)
         --parent-answers LEVEL
                     (--new) what a parent agent may answer on its
                     questions: hard, standard or soft, only stricter than
@@ -252,19 +254,14 @@ module Samagotchi
         return refuse_local_command(local, options)
       end
 
-      # A parent agent's /continue yes is chi answer --option Continue by
-      # another route: held to guardrails.parent_answers (tightened by each
-      # target's own) here, and marked as chi answer's (#client_id_for) so
-      # the worker checks it again.
-      if prompt && parent_continue?(prompt) && (refusal = continue_refusal_for(options))
+      # A parent agent's /continue yes held to guardrails.parent_answers,
+      # and a /parent-answers that loosens: refused before anything is sent.
+      gate = ParentGate.new(options, state_dir: @state_dir)
+      if prompt && (refusal = gate.continue_refusal(prompt))
         @stderr.puts("chi send: #{refusal}")
         return CLI::Exit::FAILED
       end
-      # chi send never loosens a session's own parent_answers (only a user
-      # at a UI does: the worker refuses it too); refused before anything
-      # is sent. Tightening goes.
-      if prompt && SessionCommands.builtin_registry.lookup(prompt)&.id == :parent_answers &&
-         target_parent_answers(options).any? { |value| ParentAnswersCommand.loosens?(prompt, value) }
+      if prompt && gate.loosens?(prompt)
         error_line("chi send: refused: #{ParentAnswersCommand::REFUSED}")
         return CLI::Exit::FAILED
       end
@@ -365,11 +362,12 @@ module Samagotchi
         options[:thinking] = Thinking.session_level(word)
       end
       if options[:parent_answers]
-        word = options[:parent_answers].strip.downcase
-        levels = Guardrails::ParentPolicy::ORDER
-        return usage_error("--parent-answers takes #{levels.join(", ")}, not #{options[:parent_answers]}") unless levels.include?(word)
+        level = Guardrails::ParentPolicy.parse_level(options[:parent_answers])
+        unless Guardrails::ParentPolicy::ORDER.include?(level)
+          return usage_error("--parent-answers takes #{Guardrails::ParentPolicy::ORDER.join(", ")}, not #{options[:parent_answers]}")
+        end
 
-        options[:parent_answers] = word
+        options[:parent_answers] = level
       end
       toolkit = Toolkit.from_flags(name: options[:toolkit], add: options[:tools], remove: options[:no_tools])
       options[:toolkit_value] = toolkit if toolkit
@@ -453,8 +451,7 @@ module Samagotchi
       return report_command(session.id) if @sent_command
 
       wait_for_reply(session.id, cursor: nil, baseline: baseline_of(session, question_id: nil),
-                                 timeout: options[:timeout], turn: @sent_input_file ? @sent_enqueued_id : nil,
-                                 report_turn_id: @sent_enqueued_id)
+                                 timeout: options[:timeout], **WaitTarget.first_message(@delivered).to_h)
     end
 
     # The model the new session will run, for the images check: --model
@@ -526,29 +523,15 @@ module Samagotchi
       return 1 unless deliver(id, prompt)
       return report_command(id) if @sent_command
 
-      # The ack's id names the queued message's turn, also when the turn
-      # running at the check ended before it went in (an idle worker's ack
-      # says next_step, and the file still runs as that turn).
-      # A file fallback has no delivery field; use its id to see terminal
-      # outcomes for commands that finish without starting a turn.
-      turn = @sent_enqueued_id if @queue || @sent_input_file
-      report_turn_id = if @queue
-                         turn
-                       elsif session.status == Session::STATUS_RUNNING
-                         running_turn
-                       else
-                         @sent_enqueued_id
-                       end
-      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout], turn: turn,
-                          queued: @queue && !turn.nil?,
-                          report_turn_id: report_turn_id)
+      target = WaitTarget.message(@delivered, queue: @queue, running: session.status == Session::STATUS_RUNNING,
+                                              running_turn: running_turn)
+      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout], **target.to_h)
     end
 
     # --wait with no message: the session's next reply, sending nothing,
     # so an agent can go back to waiting after exit 3 or 130. A running
     # turn is fine here (nothing joins its queue); a question pending now
-    # was already reported. No message count: a note landing between turns
-    # grows the messages without a turn. An idle session with no worker
+    # was already reported. An idle session with no worker
     # waits for whatever wakes one (the web, chi send) rather than calling
     # it gone. The turn running now, or the one whose continue offer
     # stands, is the one waited for (ReplyWait.own_turn): its reply, not a
@@ -568,17 +551,10 @@ module Samagotchi
         return 1
       end
       live = session.status == Session::STATUS_RUNNING || SessionManager.session_owner(id, state_dir: @state_dir)
-      turn = requested_turn || ReplyWait.own_turn(session, session_dir: session_dir)
-      # The gate for the settled case: idle, a turn ended (last_turn), no
-      # question standing (a continue offer waits for its answer).
-      settled = session.status == Session::STATUS_IDLE && session.last_turn && session.pending_question.nil?
-      ended_before = requested_turn ? session.last_turn&.enqueued_id == requested_turn : settled
-      report_turn_id = turn
-      report_turn_id ||= session.last_turn&.enqueued_id if settled
+      target = WaitTarget.wait_only(session, session_dir: session_dir, requested: requested_turn)
       wait_for_reply(id, cursor: ReplyWait.newest_reply(id, state_dir: @state_dir),
-                         baseline: baseline_of(session).merge(messages: nil),
-                         timeout: options[:timeout], owner_grace: live ? self.class::WORKER_GONE_AFTER : nil,
-                         turn: turn, ended_before: ended_before, report_turn_id: report_turn_id)
+                         baseline: baseline_of(session),
+                         timeout: options[:timeout], owner_grace: live ? self.class::WORKER_GONE_AFTER : nil, **target.to_h)
     end
 
     # The session as it was before the message went in (ReplyWait's
@@ -610,66 +586,22 @@ module Samagotchi
         @info.puts("#{session.id}  failed: its worker did not start; the session is kept (chi --attach #{session.id})")
         return false
       end
-      unless result[:status] == :accepted
-        @info.puts("#{session.id}  failed: #{result.dig(:ack, "detail") || "could not queue it"}")
+      unless result.accepted?
+        @info.puts("#{session.id}  failed: #{result.detail || "could not queue it"}")
         return false
       end
 
-      ack = result[:ack].is_a?(Hash) ? result[:ack] : {}
-      @sent_input_file = !ack.key?("delivery")
-      @sent_enqueued_id = (ack["enqueued_id"] || ack[:enqueued_id])&.to_s
-      @sent_command = command_ack?(result[:ack])
+      @delivered = result
+      @sent_command = result.command?
       @info.puts("#{session.id}  started#{continued_words(session)}#{with_images}#{"; #{SENT_COMMAND}" if @sent_command}")
       true
     end
 
     SENT_COMMAND = "sent as a session command"
 
-    # Whether the worker took the message as a session command (a POST
-    # /turn whose line is one answers with its command_id).
-    def command_ack?(ack) = ack.is_a?(Hash) && !ack["command_id"].to_s.empty?
-
     # chi send's client id, or chi answer's for a parent agent's /continue
     # yes (the worker holds that to its guardrails.parent_answers).
-    def client_id_for(prompt) = parent_continue?(prompt) ? ClientId::CLI_ANSWER : CLIENT_ID
-
-    # The first refusal of a parent's /continue yes among the targets, each
-    # by config.yml tightened by its own parent_answers; nil when none
-    # refuses.
-    def continue_refusal_for(options)
-      target_parent_answers(options).each do |value|
-        strategy = Guardrails::ParentPolicy.effective(value)
-        refusal = Guardrails::ParentPolicy.continue_refusal(strategy: strategy)
-        return refusal if refusal
-      end
-      nil
-    end
-
-    # The targets' own parent_answers values: a --new session's
-    # --parent-answers, a --continues link's previous session's (the link
-    # keeps it), each id's. An id that doesn't resolve is skipped (#resolve
-    # reports it later); none left is config.yml's alone ([nil]).
-    def target_parent_answers(options)
-      return [options[:parent_answers]] if options[:new] && !options[:continues]
-
-      sessions = if options[:new]
-                   [target_session { SessionChain.resolve(options[:continues], state_dir: @state_dir) }]
-                 else
-                   options[:ids].map { |given| target_session { Session.resolve_id(given, state_dir: @state_dir) } }
-                 end
-      values = sessions.compact.map(&:parent_answers)
-      values.empty? ? [nil] : values
-    end
-
-    # The session the block's id names, or nil when there is none.
-    def target_session
-      Session.load(yield, state_dir: @state_dir)
-    rescue ArgumentError
-      nil
-    end
-
-    # A /continue yes (or bare /continue) from a parent agent's process.
-    def parent_continue?(prompt) = TurnFlow.continue_yes?(prompt) && Guardrails::ParentApprovals.parent_process?
+    def client_id_for(prompt) = ParentGate.parent_continue?(prompt) ? ClientId::CLI_ANSWER : CLIENT_ID
 
     # Whether +text+ may be a session command, which only its worker knows
     # (a bundle's too).
@@ -740,26 +672,25 @@ module Samagotchi
                  end
       result = SessionManager.deliver_turn(id, prompt: prompt, client_id: client_id_for(prompt), images: refs, state_dir: @state_dir,
                                                delivery: delivery)
-      unless result[:status] == :accepted
+      unless result.accepted?
         # A worker older than queueing would steer it: refused, not sent.
-        word = result.dig(:ack, "error") == Delivery::QUEUE_UNAVAILABLE["error"] ? "refused" : "failed"
-        @info.puts("#{short}  #{word}: #{result.dig(:ack, "detail") || "could not queue it"}")
+        word = result.error == Delivery::QUEUE_UNAVAILABLE["error"] ? "refused" : "failed"
+        @info.puts("#{short}  #{word}: #{result.detail || "could not queue it"}")
         return false
       end
 
-      @sent_command = command_ack?(result[:ack])
+      @sent_command = result.command?
       if @sent_command
         @info.puts("#{short}  #{SENT_COMMAND}")
         return true
       end
 
-      ack = result[:ack].is_a?(Hash) ? result[:ack] : {}
-      @sent_input_file = !ack.key?("delivery")
+      ack = result.ack
+      @delivered = result
       # What the worker applied, for --format json: its ack's delivery
       # (next_step for an idle session) and a cut's outcome.
       @sent_delivery = ack["delivery"] || delivery
       @sent_cut = ack["cut"]
-      @sent_enqueued_id = (ack["enqueued_id"] || ack[:enqueued_id])&.to_s
       @info.puts("#{short}  sent#{with_images}#{delivery_note(ack, delivery: delivery, running: running, owner: owner)}")
       true
     rescue SessionManager::OwnedByTUI

data/lib/samagotchi/session.rb

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

data/lib/samagotchi/session_inbox.rb

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

data/lib/samagotchi/session_manager.rb

@@ -5,6 +5,7 @@ require "json"
 require "time"
 require "securerandom"
 require "rbconfig"
+require_relative "child_env"
 require_relative "client_id"
 require_relative "analytics_file"
 require_relative "atomic_file"
@@ -79,7 +80,7 @@ module Samagotchi
 
       def initialize(session_id)
         @session_id = session_id
-        super("session #{session_id} is owned by an interactive TUI")
+        super("session #{session_id} is open in a chi REPL; close it there first")
       end
     end
 
@@ -210,7 +211,7 @@ module Samagotchi
     # is when the worker starts); opts[:env] adds to it (merged, not
     # replaced) what it can't read there: this `chi`'s CLI settings
     # (Config.cli_env) and the absolute log file. It unsets
-    # SAMAGOTCHI_GUARDRAILS_* and the session markers (SESSION_MARKER_ENV).
+    # what ChildEnv lists (SAMAGOTCHI_GUARDRAILS_*, the session markers).
     # XDG_CONFIG_HOME passes: whoever starts or
     # wakes the worker picks which config.yml it reads (docs/guardrails.md).
     # XDG_STATE_HOME and XDG_CONFIG_HOME, when set, pass made absolute
@@ -244,18 +245,15 @@ module Samagotchi
       # And the spawner's XDG dirs, absolute: a relative XDG_STATE_HOME or
       # XDG_CONFIG_HOME would otherwise be read from the session's directory.
       child_env.merge!(Paths.absolute_xdg)
-      # The spawner's environment must not reach the worker's guardrails (a
-      # parent agent starting or waking a session): Process.spawn unsets a
-      # key mapped to nil. config.yml no longer reads them; this keeps an
-      # older or future env-exposed one out as well.
-      ENV.each_key { |key| child_env[key] = nil if key.start_with?(GUARDRAILS_ENV_PREFIX) }
-      # The markers a session's execute exports (Tools::Builtins.parent_env)
-      # are that session's: a worker started from its commands (chi send)
-      # is another session. Its execute and tasks set its own; nothing else
-      # it runs (a user's !cmd, an MCP server, a context command) has one.
-      SESSION_MARKER_ENV.each { |key| child_env[key] = nil }
-      # A smoke's fake "newest installed" is for this process's notices only.
-      child_env[InstalledVersions::ENV_KEY] = nil
+      # Unset (Process.spawn unsets a key mapped to nil) what no child chi
+      # takes from its spawner (ChildEnv): the spawner's guardrails settings
+      # (a parent agent starting or waking a session; config.yml no longer
+      # reads them, this keeps an older or future env-exposed one out as
+      # well); the session markers, a session's own (a worker started from
+      # its commands, chi send, is another session: its execute and tasks
+      # set its own; nothing else it runs has one); and a smoke's fake
+      # "newest installed", for this process's notices only.
+      child_env.merge!(ChildEnv.unset)
       # A worker process: run_session_loop traps signals, and leaves this
       # process's tree.
       child_env[WORKER_PROCESS_ENV] = "1"
@@ -263,17 +261,11 @@ module Samagotchi
       # A gem-mode worker activates the newest installed chi itself: under
       # `bundle exec` (a Gemfile that has samagotchi) Bundler's RUBYOPT would
       # hold it to the bundle's version, and its badge would never clear.
-      child_env.merge!(InstalledGem.unbundled_env_changes) if InstalledGem.spec
+      child_env.merge!(ChildEnv.unbundled)
       opts[:env] = child_env unless child_env.empty?
       opts
     end
 
-    GUARDRAILS_ENV_PREFIX = "SAMAGOTCHI_GUARDRAILS_"
-    WORKER_ENV_PREFIX = "SAMAGOTCHI_WORKER_"
-    # Tools::Builtins.parent_env's (Tools::TaskRuntime::MARKER_ENV_KEYS).
-    SESSION_MARKER_ENV = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL SAMAGOTCHI_SESSION_THINKING
-                            SAMAGOTCHI_SESSION_REASONING_HISTORY].freeze
-
     # List all sessions, reading status from persisted session.json files.
     # +project_root+: only that project's sessions (nil: every session).
     # +include_archived+: archived sessions too (Session#archived says which).
@@ -1148,6 +1140,39 @@ module Samagotchi
     # How long a turn waits for the Bridge of a worker a resume just spawned.
     TURN_BRIDGE_WAIT = 5.0
 
+    # What #deliver_turn did with a message.
+    # +status+ :accepted; :refused (the Bridge refused it, or a queue would
+    # reach a worker that doesn't queue); :timeout (the Bridge took it and
+    # never answered); :failed (the input file couldn't be written).
+    # +via+ :bridge (the worker's Bridge answered) or :file (the input-file
+    # fallback); nil when nothing went in.
+    # +ack+ the Bridge's reply body, or the file's {"status", "enqueued_id",
+    # "session_id"}: string keys either way, {} for none.
+    # +code+ a refusal's HTTP status.
+    DeliverResult = Data.define(:status, :via, :ack, :code) do
+      def initialize(status:, via: nil, ack: {}, code: nil) = super(status:, via:, ack: ack || {}, code:)
+
+      def accepted? = status == :accepted
+
+      # Sent as an input file (no Bridge): its turn and outcome carry the
+      # file's enqueued_id, which a wait follows (chi send --wait).
+      def file? = via == :file
+
+      # @return [String, nil] the id the message's turn will carry
+      def enqueued_id
+        id = ack["enqueued_id"].to_s
+        id.empty? ? nil : id
+      end
+
+      # Whether the worker took the line as a session command (a POST /turn
+      # answered with its command_id).
+      def command? = !ack["command_id"].to_s.empty?
+
+      def error = ack["error"]
+
+      def detail = ack["detail"]
+    end
+
     # Hand a user message to the session the way a UI does, for the web
     # composer and `chi send` alike: wakes the worker when none runs, posts
     # through its Bridge so every live UI sees :turn_enqueued, and falls back
@@ -1161,14 +1186,12 @@ module Samagotchi
     #   stand-in (the web's specs); #session_owner is optional
     # @param bridge [#call, nil] returns the BridgeClient or nil; defaults to
     #   the session's sidecar, waiting TURN_BRIDGE_WAIT for a new worker's
-    # @return [Hash] {status: :accepted, ack: Hash} (the Bridge's reply, or
-    #   {status:, enqueued_id:, session_id:} for a file), {status: :refused,
-    #   code:, ack:} when the Bridge refused the request (any 4xx with an
+    # @return [DeliverResult] :accepted (via the Bridge or a file),
+    #   :refused when the Bridge refused the request (any 4xx with an
     #   error: bad images, a delivery it doesn't run) or a queue would reach
-    #   a worker that doesn't queue (no file then: it would steer),
-    #   {status: :timeout, ack:} when it took the request but never answered
-    #   (no file then), or {status: :failed} when the input file couldn't be
-    #   written
+    #   a worker that doesn't queue (no file then: it would steer), :timeout
+    #   when it took the request but never answered (no file then), or
+    #   :failed when the input file couldn't be written
     # @raise [OwnedByTUI] a chi REPL owns the session
     # @raise [ArgumentError] no such session
     def self.deliver_turn(session_id, prompt:, client_id: nil, images: [], delivery: nil, state_dir: nil, manager: self,
@@ -1188,7 +1211,7 @@ module Samagotchi
           options[:delivery] = delivery unless Delivery.next_step?(delivery)
           reply = client.post_turn(**options)
           ack = reply.json
-          return { status: :accepted, ack: ack } if reply.status == 202 && ack.is_a?(Hash)
+          return DeliverResult.new(status: :accepted, via: :bridge, ack: ack) if reply.status == 202 && ack.is_a?(Hash)
           # Read after its deadline and dropped: a file would run it after all.
           return turn_timeout if ack.is_a?(Hash) && ack["error"] == "deadline_passed"
           # Any other 4xx with an error is a refusal (bad images, a delivery
@@ -1197,7 +1220,7 @@ module Samagotchi
           # limit, a big piped chi send) and a 5xx keep the file fallback
           # below, which carries the delivery (a queue too).
           if (400..499).cover?(reply.status) && reply.status != 413 && ack.is_a?(Hash) && ack["error"]
-            return { status: :refused, code: reply.status, ack: ack }
+            return DeliverResult.new(status: :refused, via: :bridge, code: reply.status, ack: ack)
           end
         rescue Errno::ETIMEDOUT
           # The Bridge drops a turn it reads after the request's deadline
@@ -1213,7 +1236,7 @@ module Samagotchi
       input[:images] = images unless images.empty?
       input[:delivery] = delivery unless Delivery.next_step?(delivery)
       path = manager.write_turn_input(session_id, **input)
-      return { status: :failed } unless path
+      return DeliverResult.new(status: :failed) unless path
 
       owner = delivery_owner(manager, session_id, state_dir)
       # A TUI that took the session between the resume and the write never
@@ -1226,7 +1249,8 @@ module Samagotchi
       # wake a new one. (The exiting worker also looks for input it left;
       # one the first resume spawned that is still starting is left be.)
       manager.resume_session(session_id, state_dir: state_dir) if owner.nil?
-      { status: :accepted, ack: { status: "accepted", enqueued_id: enqueued_id, session_id: session_id } }
+      DeliverResult.new(status: :accepted, via: :file,
+                        ack: { "status" => "accepted", "enqueued_id" => enqueued_id, "session_id" => session_id })
     end
 
     # Whether the session's live worker runs delivery: queue (its sidecar
@@ -1238,12 +1262,13 @@ module Samagotchi
     end
 
     private_class_method def self.queue_unavailable
-      { status: :refused, code: 409, ack: Delivery::QUEUE_UNAVAILABLE }
+      DeliverResult.new(status: :refused, code: 409, ack: Delivery::QUEUE_UNAVAILABLE)
     end
 
     private_class_method def self.turn_timeout
-      { status: :timeout, ack: { "error" => "worker_timeout",
-                                 "detail" => "the session's worker did not answer, so the message was not sent" } }
+      DeliverResult.new(status: :timeout, via: :bridge,
+                        ack: { "error" => "worker_timeout",
+                               "detail" => "the session's worker did not answer, so the message was not sent" })
     end
 
     private_class_method def self.delivery_owner(manager, session_id, state_dir)

data/lib/samagotchi/session_metrics.rb

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

data/lib/samagotchi/sessions_command.rb

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