samagotchi 0.81.0 → 0.83.0

data/lib/samagotchi/bundles/cost-cap/plugin.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+# The cost-cap bundle (docs/plugins.md, The cost-cap bundle): a per-session
+# cap on what the session spends (ctx.cost: reported + estimated, side
+# requests included). Before each generation it compares the spend with
+# the cap: at warn_at of it the user (only) gets one notice, at the cap the
+# turn pauses on a question, Continue (the cap goes up by a step) or Stop
+# (the turn stops, with a card). With no one to ask it stops. The model
+# never sees any of it: no tool, no steer, no prompt text.
+#
+# Settings (config.yml, bundles: cost-cap:), read at each use from
+# ctx.settings, never at load:
+#   default: 5.00   USD cap for a session with none set; absent/0/off: none
+#   child: 2.00     for delegate children (ctx.delegate?); absent: default
+#   warn_at: 0.8    the share of the cap that warns; 0/off: no warning
+#
+# State: <data_dir>/sessions/<session id>.json, {"cap": 3.0, "step": 3.0},
+# written by /cap and by Continue; "cap": null (or false) is off for the
+# session, over the config. Without a file the cap comes from the settings.
+# The cap is resolved once per session id (ctx.delegate? parses the session
+# file) and kept until /cap or Continue writes a new one.
+require "json"
+require "fileutils"
+
+class Plugin
+  USAGE = "usage: /cap [N | $N | off] (USD; /cap alone shows the spend)"
+  OPTIONS = %w[Continue Stop].freeze
+  WARN_AT = 0.8
+
+  def initialize(_settings)
+    @mutex = Mutex.new
+    @resolved = nil        # {session:, cap:, step:}
+    @warned = nil          # [session id, cap] the share warning was given for
+    @unknown_warned = nil  # the session id the "can't be enforced" notice was given for
+  end
+
+  def register(chi)
+    chi.on(:before_generation) { |_event, ctx| check(ctx) }
+    # Only the "can't be enforced" notice: a turn of one generation (or a
+    # session's last) has no next before_generation to give it.
+    chi.on(:after_generation) { |_event, ctx| check_known(ctx) }
+    chi.command("/cap", "see or set this session's cost cap: /cap, /cap 5, /cap off", anytime: true) do |args, ctx|
+      command(args, ctx)
+    end
+  end
+
+  # The cap in USD (a positive Float) or nil (none, 0, off, false).
+  def self.amount(value)
+    number = case value
+             when Numeric then value.to_f
+             when String then value.strip.delete_prefix("$").then { |s| s.match?(/\A\d+(\.\d+)?\z/) ? s.to_f : nil }
+             end
+    number&.positive? ? number : nil
+  end
+
+  # Cents, or up to four decimals under $0.10, so a small cap (/cap 0.003)
+  # doesn't read "$0.00 spent of $0.00".
+  def self.money(value)
+    return format("$%.2f", value) if value.zero? || value.abs >= 0.1
+
+    format("$%.4f", value).sub(/(\.\d\d\d*?)0+\z/, '\1')
+  end
+
+  private
+
+  def check(ctx)
+    resolved = resolve(ctx)
+    cap = resolved[:cap]
+    return unless cap
+
+    cost = ctx.cost
+    return unenforceable(ctx, resolved[:session], cap) unless cost.known?
+
+    total = cost.total
+    return at_cap(ctx, resolved, cost) if total >= cap
+
+    share = warn_share(ctx)
+    return unless share && total >= share * cap
+    return unless first_time?(:@warned, [resolved[:session], cap])
+
+    ctx.notify("#{money(total)} of #{money(cap)} spent (#{(total / cap * 100).floor}%)", level: :warn)
+  end
+
+  def check_known(ctx)
+    resolved = resolve(ctx)
+    return unless resolved[:cap]
+
+    unenforceable(ctx, resolved[:session], resolved[:cap]) unless ctx.cost.known?
+  end
+
+  def unenforceable(ctx, session, cap)
+    return unless first_time?(:@unknown_warned, session)
+
+    ctx.notify("the #{money(cap)} cap can't be enforced: #{ctx.model || "the model"} reports no cost and has no price",
+               level: :warn)
+  end
+
+  def at_cap(ctx, resolved, cost)
+    cap = resolved[:cap]
+    raised = raised_cap(cap, resolved[:step] || cap, cost.total)
+    answer = ctx.ask_user(question: "Cost cap reached: #{money(cost.total)} spent of #{money(cap)}. " \
+                                    "Continue raises it to #{money(raised)}.",
+                          header: "Cost cap", options: OPTIONS)
+    if continue?(answer)
+      save(ctx, resolved[:session], "cap" => raised, "step" => resolved[:step] || cap)
+      ctx.notify("cap raised to #{money(raised)}")
+    else
+      stop(ctx, cap, cost)
+    end
+  end
+
+  # Another step on the cap, as many steps as it takes to pass the spend
+  # (a turn that overshot by more than a step asks once, not each step).
+  def raised_cap(cap, step, total)
+    raised = cap + step
+    raised += step while raised <= total
+    raised.round(6)
+  end
+
+  def continue?(answer)
+    return false unless answer
+
+    Array(answer[:selected]).first == "Continue" || Array(answer[:selected_indices]).first&.zero?
+  end
+
+  def stop(ctx, cap, cost)
+    return unless ctx.stop_turn("cost cap reached (#{money(cost.total)} of #{money(cap)})")
+
+    ctx.card(title: "cost-cap stopped the turn",
+             body: "Spent #{breakdown(cost)} of a #{money(cap)} cap.\n\n`/cap N` raises it, `/cap off` removes it.",
+             level: :warn)
+  end
+
+  def command(args, ctx)
+    arg = args.to_s.strip.downcase
+    return show(ctx) if arg.empty?
+
+    session = ctx.session_id
+    return "cost-cap: no session yet" unless session
+
+    if %w[off 0].include?(arg)
+      save(ctx, session, "cap" => nil)
+      return "cost-cap: no cap for this session"
+    end
+    value = arg.match?(/\A\$?\d+(\.\d+)?\z/) ? self.class.amount(arg) : nil
+    return USAGE unless value
+
+    save(ctx, session, "cap" => value, "step" => value)
+    "cost-cap: cap set to #{money(value)} (#{money(ctx.cost.total)} spent)"
+  rescue StandardError => e
+    "cost-cap: #{e.message}"
+  end
+
+  def show(ctx)
+    cost = ctx.cost
+    cap = resolve(ctx)[:cap]
+    return "cost-cap: no cap (#{money(cost.total)} spent)" unless cap
+
+    line = "cost-cap: #{money(cost.total)} spent of #{money(cap)} (#{parts(cost)})"
+    cost.known? ? line : "#{line} (can't be enforced: no cost reported or priced)"
+  end
+
+  def parts(cost) = "reported #{money(cost.reported)}, estimated #{money(cost.estimated)}, side #{money(cost.side)}"
+
+  def breakdown(cost) = "#{money(cost.total)} (#{parts(cost)})"
+
+  # The session's cap and step now: the state file's, else child: for a
+  # delegate, else default:. Cached per session id.
+  def resolve(ctx)
+    session = ctx.session_id
+    cached = @mutex.synchronize { @resolved }
+    return cached if cached && cached[:session] == session
+
+    resolved = { session: session, **(state(ctx, session) || configured(ctx)) }
+    @mutex.synchronize { @resolved = resolved }
+  end
+
+  def state(ctx, session)
+    return nil unless session
+
+    saved = JSON.parse(File.read(state_path(ctx, session)))
+    return nil unless saved.is_a?(Hash) && saved.key?("cap")
+
+    cap = self.class.amount(saved["cap"])
+    { cap: cap, step: self.class.amount(saved["step"]) || cap }
+  rescue Errno::ENOENT, JSON::ParserError
+    nil
+  end
+
+  def configured(ctx)
+    settings = ctx.settings
+    return { cap: nil, step: nil } unless settings.key?("default") || settings.key?("child")
+
+    key = settings.key?("child") && ctx.delegate? ? "child" : "default"
+    cap = self.class.amount(settings[key])
+    { cap: cap, step: cap }
+  end
+
+  def warn_share(ctx)
+    settings = ctx.settings
+    return WARN_AT unless settings.key?("warn_at")
+
+    share = settings["warn_at"]
+    share.is_a?(Numeric) && share.positive? ? share : nil
+  end
+
+  def save(ctx, session, data)
+    path = state_path(ctx, session)
+    FileUtils.mkdir_p(File.dirname(path))
+    Samagotchi::AtomicFile.write(path, "#{JSON.generate(data)}\n")
+    cap = self.class.amount(data["cap"])
+    @mutex.synchronize { @resolved = { session: session, cap: cap, step: self.class.amount(data["step"]) || cap } }
+  end
+
+  def state_path(ctx, session) = File.join(ctx.data_dir, "sessions", "#{session.gsub(/[^A-Za-z0-9_.-]/, "_")}.json")
+
+  def money(value) = self.class.money(value)
+
+  # Whether +key+ is new for the once-only notice kept in +ivar+ (and keep it).
+  def first_time?(ivar, key)
+    @mutex.synchronize do
+      next false if instance_variable_get(ivar) == key
+
+      instance_variable_set(ivar, key)
+      true
+    end
+  end
+end

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.81.0
+version: 0.83.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/child_reports.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "securerandom"
 require_relative "client_id"
 require_relative "session"
 require_relative "session_inbox"
@@ -129,7 +130,7 @@ module Samagotchi
     # (DelegateWait.finish, its report variant), the cursor it moves the child to,
     # and the cursor it was read from (a commit after the model moved it
     # itself, with delegate_result, leaves it alone).
-    Report = Data.define(:child_id, :text, :before, :after, :rings) do
+    Report = Data.define(:child_id, :text, :before, :after, :rings, :claim_id) do
       def line(mark: nil) = Steer::Line.new(text: text, source: ChildReports::SOURCE, mark: mark)
       def origin = { client_id: "#{ClientId::CHILD_PREFIX}#{child_id[0, 8]}" }
     end
@@ -142,6 +143,7 @@ module Samagotchi
       @state_dir = state_dir
       @session_dir = Session.session_dir(session_id, state_dir: state_dir)
       @predecessor_dir = Session.valid_id?(predecessor) ? Session.session_dir(predecessor, state_dir: state_dir) : nil
+      Tools::DelegateCursors.clear_report_claims(@session_id, state_dir: @state_dir)
       # child id → the Report this turn took for it (rings merged).
       @taken = {}
     end
@@ -177,12 +179,16 @@ module Samagotchi
     end
 
     # The turn that took the reports was kept: move each child's cursor on
-    # (unless something else moved it since: the model's own
-    # delegate_result), then delete the rings.
+    # and delete the rings.
     def commit
       @taken.each_value do |report|
         Tools::DelegateCursors.update(@session_id, report.child_id, state_dir: @state_dir) do |cursor|
-          cursor == report.before ? report.after : cursor
+          next cursor unless cursor.report_claim&.fetch("id", nil) == report.claim_id
+
+          before = report.before.with(report_claim: nil)
+          after = report.after.with(report_claim: nil)
+          current = cursor.with(report_claim: nil)
+          current == before ? after : current
         end
         delete_rings(report.rings)
       rescue StandardError => e
@@ -193,6 +199,11 @@ module Samagotchi
 
     # The turn was rolled back: its rings stay for the next one.
     def release
+      @taken.each_value do |report|
+        Tools::DelegateCursors.update(@session_id, report.child_id, state_dir: @state_dir) do |cursor|
+          cursor.report_claim&.fetch("id", nil) == report.claim_id ? cursor.with(report_claim: nil) : cursor
+        end
+      end
       @taken = {}
     end
 
@@ -237,13 +248,19 @@ module Samagotchi
                                       timeout: 0, turn: before.turn)
       return nil unless reportable?(wait)
 
-      # A reported end is the follow-up turn's too (DelegateCursor#turn):
-      # a later wait on it would repeat its reply.
+      claim_id = before.report_claim&.fetch("id", nil) || SecureRandom.hex(16)
       after = before.with(reply_file: wait.status == :done ? wait.file : before.reply_file,
-                          turn: wait.status == :waiting_for_answer ? before.turn : nil)
+                          turn: wait.status == :waiting_for_answer ? before.turn : nil, report_claim: nil)
                     .with_baseline(ReplyWait.baseline_of(wait.session))
+      claim = { "id" => claim_id, "file" => wait.file, "cursor" => after.to_json_hash }
+      return nil unless Tools::DelegateCursors.claim_report(@session_id, child_id, expected: before, claim: claim,
+                                                            state_dir: @state_dir)
+
+      # A reported end is the follow-up turn's too (DelegateCursor#turn):
+      # a later wait on it would repeat its reply.
+      after = after.with(report_claim: claim)
       text = Tools::DelegateWait.finish(wait, child_id, timeout: 0, report: true)
-      Report.new(child_id: child_id, text: text, before: before, after: after, rings: rings)
+      Report.new(child_id: child_id, text: text, before: before, after: after, rings: rings, claim_id: claim_id)
     rescue ArgumentError
       nil # the child is gone
     end

data/lib/samagotchi/cli/parent_wait.rb

@@ -62,19 +62,25 @@ module Samagotchi
       #   a --wait with no message is about (ReplyWait.own_turn)
       # @param queued [Boolean] +turn+ is a queued message's (ReplyWait's
       #   queued:)
+      # @param ended_before [Boolean] a last_turn that ended before the
+      #   baseline is the answer (ReplyWait's ended_before:) — the
+      #   --wait-with-no-message's settled session
+      # @param report_turn_id [String, nil] the turn id to include in the
+      #   report, even when ReplyWait uses the next-reply path
       # @return [Integer] the exit status
       def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: self.class::WORKER_GONE_AFTER, turn: nil,
-                         queued: false)
+                         queued: false, ended_before: false, report_turn_id: turn)
         result = ReplyWait.call(id, state_dir: @state_dir, cursor: cursor, timeout: timeout, baseline: baseline,
                                     owner_grace: owner_grace, poll_interval: self.class::POLL_INTERVAL, turn: turn,
-                                    queued: queued)
+                                    queued: queued, ended_before: ended_before)
+        result.turn_id = report_turn_id if report_turn_id && !report_turn_id.to_s.empty?
         result.text = result.text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
         @reported = true
         ParentReport.report(result, session_id: id, stdout: @stdout, stderr: @stderr, command: command_name,
                                     json: @json, timeout: timeout, extra: report_extra)
       rescue Interrupt
         if @json
-          @stdout.puts(ParentReport.json_line(ReplyWait::Result.new(status: :canceled), session_id: id,
+          @stdout.puts(ParentReport.json_line(ReplyWait::Result.new(status: :canceled, turn_id: report_turn_id), session_id: id,
                                                                                         extra: report_extra))
           @stdout.flush
           @reported = true

data/lib/samagotchi/engine.rb

@@ -569,7 +569,7 @@ module Samagotchi
         block = @metrics.add_side(usage)
         @session_observer.notify(type: :side_usage, kind: usage.kind, side: block)
       end
-      sid = @session&.id
+      sid = @metrics.session_id
       return if sid.nil? || turn_running?
       return unless File.exist?(Session.session_file(sid, state_dir: session_state_dir))
 
@@ -2581,7 +2581,8 @@ module Samagotchi
         # build and after a rebuild that drops them (SystemPrompt#prompt_files
         # returns [] itself: the || keeps a nil builder safe).
         prompt_files: -> { @prompt_builder&.prompt_files || [] },
-        frontend: -> { interface }
+        frontend: -> { interface },
+        cost: -> { @metrics.cost }
       )
     end
 

data/lib/samagotchi/guardrails/rm_targets.rb

@@ -33,8 +33,10 @@ module Samagotchi
       # @param session_root [String] the session's repo root (or cwd)
       def outside_tmp?(command, cwd:, tmp_roots:, session_root:, home: Dir.home, env: ENV)
         tokens = ShellLex.lex(command.to_s)
-        # rm inside $(…) or backticks: the lexer keeps no body.
-        return true if tokens.any? { |_, value| value.include?(ShellLex::SUBST) } && command.to_s.match?(/\brm\b/)
+        # rm inside $(…) or backticks: the lexer keeps no body. A message
+        # heredoc's text is data, so leave it out of this fallback.
+        code = ShellLex.code_text(command.to_s)
+        return true if tokens.any? { |_, value| value.include?(ShellLex::SUBST) } && code.match?(/\brm\b/)
 
         session = ProtectedPaths.real(session_root.to_s)
         roots = tmp_roots.reject { |tmp| ShellPaths.within?(session, tmp) }

data/lib/samagotchi/guardrails/shell_paths.rb

@@ -16,8 +16,9 @@ module Samagotchi
     # A word it can't resolve (another $VAR, $(…), a glob, a relative path
     # after cd $X) or one that reads as a script (sh -c '…', ruby -e '…':
     # spaces, quotes, operators in it) falls back to a text match (+text+);
-    # so does the whole command when it holds a $(…) or backticks (the
-    # lexer keeps no body).
+    # so does the whole command when it holds a $(…) or backticks (the lexer
+    # keeps no body), except for message heredoc bodies ShellLex.code_text
+    # recognizes as data.
     module ShellPaths
       # A word that is a script rather than a path.
       SCRIPT = /[\s;&|<>()'"`]/
@@ -42,7 +43,8 @@ module Samagotchi
         roots = dirs.compact.map { |dir| ProtectedPaths.real(dir.to_s.chomp("/")) }.reject(&:empty?).uniq
         walk = Walk.new(cwd, home, env)
         tokens = ShellLex.lex(command.to_s)
-        return true if tokens.any? { |_, value| value.include?(ShellLex::SUBST) } && command.to_s.match?(text)
+        code = ShellLex.code_text(command.to_s)
+        return true if tokens.any? { |_, value| value.include?(ShellLex::SUBST) } && code.match?(text)
 
         ShellLex.simple_commands(tokens).any? do |words|
           walk.step(words).any? { |word, path| path ? names?(path, roots, tmp_roots) : word.match?(text) }

data/lib/samagotchi/idle_client.rb

@@ -187,13 +187,8 @@ module Samagotchi
       raise SummarizeError, "server returned no parseable assistant content (#{e.message})"
     end
 
-    # The request's token counts and reported cost (a broadcast's triage
-    # has no session to count them in). The cache counts show whether the
-    # host reused a cached prefix. A side request evicts a session's cached
-    # prompt only on a llama.cpp with no host-memory cache (--cache-ram 0)
-    # or an old single-slot build, or when pinned to the session's slot,
-    # which chi never does; paid hosts and current llama.cpp aren't
-    # affected (docs/internals/prompt-caching.md).
+    # Log reported request usage when cache counts are present; session
+    # side-usage counting is handled separately by #report_usage.
     def log_usage(response, kind)
       usage = response.usage
       fields = usage&.cache_fields || {}

data/lib/samagotchi/llm/http.rb

@@ -390,7 +390,7 @@ module Samagotchi
                 end
         Log.public_send(failure_level, :http, event, **log_base(current), status: e.is_a?(ProviderError) ? e.status : nil,
                                                      ms: elapsed_ms(current), attempts: current[:attempts], error: e.class.name,
-                                                     msg: (e.respond_to?(:summary) ? e.summary : e.message).to_s[0, 300])
+                                                     msg: log_message(e.respond_to?(:summary) ? e.summary : e.message))
         raise
       end
 
@@ -410,13 +410,18 @@ module Samagotchi
       def retry_after(error, attempts, delay, on_retry, cancel_controller, current)
         Log.warn(:http, "retry", **log_base(current), attempt: attempts, max_retries: @retry_policy.max, delay_s: delay,
                                  status: error.is_a?(ProviderError) ? error.status : nil, error: error.class.name,
-                                 msg: error.message.to_s[0, 300])
+                                 msg: log_message(error.message))
         on_retry&.call(attempt: attempts, max_retries: @retry_policy.max, next_delay: delay,
                        error_class: error.class.name, error_message: error.message,
                        status: error.is_a?(ProviderError) ? error.status : nil)
         wait(delay, cancel_controller)
       end
 
+      def log_message(value)
+        value.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+          .gsub(/[[:cntrl:]\u2028\u2029]+/, " ").split.join(" ")[0, 300]
+      end
+
       def check_status!(response)
         status = response.code.to_i
         return if status.between?(200, 299)

data/lib/samagotchi/parent_report.rb

@@ -76,6 +76,7 @@ module Samagotchi
     # @return [Hash] the --format json object
     def json(result, session_id:, timeout: nil, extra: {})
       report = { status: status(result), session_id: session_id }
+      report[:turn_id] = result.turn_id unless result.turn_id.to_s.empty?
       case report[:status]
       when "answered" then report[:text] = result.text.to_s
       when "question"
@@ -122,7 +123,7 @@ module Samagotchi
         text = if result.status == :waiting_for_answer
                  question_text(result.question, session_id: session_id)
                else
-                 "#{detail(result, session_id: session_id, timeout: timeout)}\n"
+                 "#{detail(result, session_id: session_id, timeout: timeout, turn_id: result.turn_id)}\n"
                end
         stderr.print("#{command}: #{text}")
       end
@@ -200,7 +201,7 @@ module Samagotchi
     end
 
     # What a wait that ended without an answer says, one line.
-    def detail(result, session_id:, timeout: nil)
+    def detail(result, session_id:, timeout: nil, turn_id: nil)
       attach = "chi --attach #{session_id}"
       case result.status
       when :waiting_for_answer
@@ -217,7 +218,10 @@ module Samagotchi
       when :error then "the worker failed: #{result.text}; #{attach} shows what happened"
       when :worker_gone then "the worker is gone; #{attach} shows what happened"
       when :stopped then "the session was stopped (chi sessions stop)"
-      else timeout ? "still running after #{format("%g", timeout)} s: #{attach}" : "still running: #{attach}"
+      else
+        wait_again = "chi send --wait --turn #{turn_id} #{session_id}" unless turn_id.to_s.empty?
+        hint = wait_again || attach
+        timeout ? "still running after #{format("%g", timeout)} s: #{hint}" : "still running: #{hint}"
       end
     end
 

data/lib/samagotchi/plugin/context.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require_relative "../log"
 require_relative "../paths"
+require_relative "../session_metrics/cost"
 require_relative "../guardrails/context"
 require_relative "../idle_client"
 require_relative "service"
@@ -51,10 +52,11 @@ module Samagotchi
     # ctx.http call without cancel: uses, nil for none: an init task's own,
     # else the running turn's for work done for it (the turn's thread, or a
     # plugin handler: +handler+) until the turn has ended.
+    # +cost+ returns the session's spend now (SessionMetrics::Cost).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit,
-                      :cancel_controller, keyword_init: true)
+                      :cancel_controller, :cost, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -140,6 +142,11 @@ module Samagotchi
       #   current_model_only names it
       def model_key = @host.model_key&.call
 
+      # @return [SessionMetrics::Cost] the session's spend so far, read now:
+      #   #total, #reported, #estimated, #side (Float USD) and #known?
+      #   (docs/plugins.md); zero and known with no session
+      def cost = @host.cost&.call || SessionMetrics::Cost.zero
+
       # @return [String, nil] the name of the session's toolkit ("full" for
       #   one from before toolkits; nil with no session)
       def toolkit = @host.toolkit&.call

data/lib/samagotchi/reply_wait.rb

@@ -52,8 +52,10 @@ module Samagotchi
     # @!attribute session [Session, nil] the session as the look that
     #   decided the outcome loaded it (a caller's next baseline); nil for
     #   :canceled and :timeout
+    # @!attribute turn_id [String, nil] the id of the turn this result is
+    #   about, when known
     Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, :error_kind, :retryable, :cancel_reason,
-                        :stopped_by, :kept_steps, :session, keyword_init: true)
+                        :stopped_by, :kept_steps, :session, :turn_id, keyword_init: true)
 
     module_function
 
@@ -94,10 +96,18 @@ module Samagotchi
     # @param queued [Boolean] the turn: input was sent as a queue (or with
     #   images), which a running turn never merges: no fallback, even when
     #   its file was taken before the first look
+    # @param ended_before [Boolean] a last_turn that ended before the
+    #   baseline (chi send --wait with no message, on a session that went
+    #   idle in the gap between waits) is the turn's end too: with the
+    #   session idle and its last_turn still the baseline's, its end is
+    #   the answer — its reply, or its no-reply outcome. Its reply file
+    #   sorts at the cursor, not past it, and its end precedes the
+    #   baseline, so without it the wait would time out "running" again.
+    #   Not for a turn: wait (chi answer) whose own end it waits for.
     # @return [Result]
     # @raise [ArgumentError] no such session
     def call(id, state_dir:, cursor:, timeout: nil, poll_interval: POLL_INTERVAL, cancelled: -> { false },
-             baseline: nil, owner_grace: nil, interject: nil, turn: nil, queued: false)
+             baseline: nil, owner_grace: nil, interject: nil, turn: nil, queued: false, ended_before: false)
       deadline = timeout && (monotonic + timeout.to_f)
       seen_running = false
       gone_since = nil
@@ -159,6 +169,38 @@ module Samagotchi
 
         return Result.new(status: :canceled) if cancelled.call
 
+        # The turn that ended before this wait (ended_before: chi send
+        # --wait with no message, on a session that went idle in the gap
+        # between waits): its last_turn still stands, the session is idle,
+        # so its end is the answer, not a wait that times out "running"
+        # again. Its reply file sorts at the cursor (the newest), not past
+        # it: it is the turn's when it is at least as new as the turn's
+        # end (the worker writes it after recording the ended_at), else the
+        # turn left no reply and an earlier turn's file is not its.
+        if ended_before && turn.nil? && session.status == Session::STATUS_IDLE &&
+           (ended = session.last_turn&.ended_at) && !ended.to_s.empty? &&
+           baseline && ended == baseline[:last_turn]
+          file = newest_reply(id, state_dir: state_dir)
+          path = File.join(reply_dir(id, state_dir: state_dir), file) if file
+          if file && reply_is_turns?(path, ended)
+            reply = Result.new(status: :done, text: File.read(path), file: file)
+            reply.session = settled(session, id, state_dir: state_dir)
+            return reply
+          end
+
+          return no_reply(session, baseline, fresh: true)
+        end
+
+        if ended_before && turn && session.last_turn&.enqueued_id == turn &&
+           !(session.status == Session::STATUS_RUNNING && session.interrupted_turn&.enqueued_id == turn) &&
+           (ended = session.last_turn&.ended_at) && !ended.to_s.empty? &&
+           baseline && ended == baseline[:last_turn]
+          # The turn-specific reply lookup above already found its file, if
+          # one exists. Without it, don't use the newest file as a fallback:
+          # it could belong to another turn.
+          return no_reply(session, baseline, fresh: true)
+        end
+
         if turn
           # Only the turn's own end: the session runs another turn when the
           # wait starts, and that one's end is not the answer. A last_turn
@@ -257,6 +299,18 @@ module Samagotchi
       session.last_turn&.enqueued_id
     end
 
+    # Whether +turn+ is a turn the caller can wait for: running now, queued
+    # as its own turn, or the last one to have ended.
+    def known_turn?(session, session_dir:, turn:)
+      id = turn.to_s
+      return false if id.empty?
+
+      running = session.status == Session::STATUS_RUNNING && session.interrupted_turn&.enqueued_id == id
+      queued = SessionInbox.waiting_input(session_dir, id) == :turn_end
+      ended = session.last_turn&.enqueued_id == id
+      running || queued || ended
+    end
+
     # Whether the session's worker sidecar names TURN_IDS_FEATURE.
     def turn_ids?(session_dir)
       WorkerSidecar.read(session_dir)&.features&.include?(TURN_IDS_FEATURE) || false
@@ -390,6 +444,16 @@ module Samagotchi
       cursor.nil? || file > cursor
     end
 
+    # Whether the reply file at +path+ is the turn that ended at +ended_at+'s,
+    # not an earlier turn's: the worker records ended_at before writing the
+    # reply, so its mtime is at least the turn's end and earlier replies'
+    # mtimes precede it. Unlike the filename, mtime is independent of TZ.
+    def reply_is_turns?(path, ended_at)
+      File.mtime(path) >= Time.parse(ended_at.to_s)
+    rescue ArgumentError, SystemCallError
+      false
+    end
+
     def monotonic
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end