samagotchi 0.36.0 → 0.37.0

data/lib/samagotchi/broadcast/triage_log.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+require_relative "../paths"
+
+module Samagotchi
+  module Broadcast
+    # What each broadcast decided, one JSON line per broadcast in
+    # <state>/samagotchi/broadcast/log.jsonl: its id, time, note text, the
+    # note's tags and every recipient's verdict (no scope cards: they quote
+    # the user's prompts). `chi broadcast deliver` adds a "corrected" line
+    # for the sessions it delivered to anyway: labels for the threshold and
+    # a future classifier. Not a list sessions read: broadcasts stay
+    # fire-and-forget. Over MAX_BYTES the file becomes log.jsonl.1 (one old
+    # file kept).
+    class TriageLog
+      MAX_BYTES = 2 * 1024 * 1024
+
+      # One recipient's line in a broadcast.
+      # @!attribute result [String] "delivered", "skipped" or "failed"
+      # @!attribute p [Float, nil] the triage model's P(yes), nil when no
+      #   model judged it
+      # @!attribute by [String] Triage::Verdict#by
+      # @!attribute tags [Array<String>] the session's tags (Tag#label)
+      Entry = Data.define(:session, :result, :p, :reason, :by, :tags)
+
+      # A `chi broadcast deliver`: when, and each session's result.
+      # @!attribute sessions [Array<Delivery>]
+      Correction = Data.define(:at, :sessions)
+
+      # One session a correction delivered to (or tried).
+      Delivery = Data.define(:session, :result)
+
+      # A broadcast as read back, with the corrections made to it since.
+      # @!attribute at [Time]
+      # @!attribute recipients [Array<Entry>]
+      # @!attribute corrections [Array<Correction>]
+      Record = Data.define(:id, :at, :text, :note_tags, :triage_model, :recipients, :corrections) do
+        # @return [Entry, nil]
+        def entry(session) = recipients.find { |e| e.session == session }
+
+        # Whether +session+ got it, from the broadcast or a correction.
+        def delivered?(session)
+          entry(session)&.result == "delivered" ||
+            corrections.any? { |c| c.sessions.any? { |d| d.session == session && d.result == "delivered" } }
+        end
+
+        def to_json_hash
+          { id: id, at: at.iso8601, text: text, note_tags: note_tags, triage_model: triage_model,
+            recipients: recipients.map(&:to_h),
+            corrections: corrections.map { |c| { at: c.at.iso8601, sessions: c.sessions.map(&:to_h) } } }
+        end
+      end
+
+      # No broadcast with that id, or several start with it.
+      class NotFound < StandardError; end
+
+      # @return [String] <state>/samagotchi/broadcast/log.jsonl
+      def self.default_path(env: ENV) = File.join(Paths.state_dir(env: env), "broadcast", "log.jsonl")
+
+      attr_reader :path
+
+      def initialize(path = self.class.default_path)
+        @path = path
+      end
+
+      # @param at [Time]
+      # @param recipients [Array<Entry>]
+      def append_broadcast(id:, at:, text:, note_tags:, triage_model:, recipients:)
+        append(type: "broadcast", id: id, at: at.iso8601, text: text, note_tags: note_tags, triage_model: triage_model,
+               recipients: recipients.map(&:to_h))
+      end
+
+      # @param sessions [Array<Delivery>]
+      def append_correction(id:, at:, sessions:)
+        append(type: "corrected", id: id, at: at.iso8601, sessions: sessions.map(&:to_h))
+      end
+
+      # Every broadcast in the log (the rotated file's first), oldest
+      # first, with its corrections. A line that doesn't parse is skipped.
+      # @return [Array<Record>]
+      def records
+        found = {}
+        [rotated_path, @path].each do |file|
+          next unless File.file?(file)
+
+          File.foreach(file) do |line|
+            data = parse(line)
+            next unless data
+
+            if data["type"] == "broadcast"
+              found[data["id"]] = record(data)
+            elsif data["type"] == "corrected" && (previous = found[data["id"]])
+              found[data["id"]] = previous.with(corrections: previous.corrections + [correction(data)])
+            end
+          end
+        end
+        found.values
+      end
+
+      # The broadcast +given+ names: its id, with or without "b-", or the
+      # start of one.
+      # @return [Record]
+      # @raise [NotFound]
+      def find(given)
+        want = given.to_s.strip.delete_prefix("b-")
+        raise NotFound, "no broadcast id given" if want.empty?
+
+        matches = records.select { |r| r.id.delete_prefix("b-").start_with?(want) }
+        return matches.first if matches.one?
+        raise NotFound, "no broadcast #{given} in the log (chi broadcast log)" if matches.empty?
+
+        raise NotFound, "#{given} names #{matches.size} broadcasts (#{matches.map(&:id).join(", ")}); give more of the id"
+      end
+
+      private
+
+      def rotated_path = "#{@path}.1"
+
+      def append(data)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.rename(@path, rotated_path) if File.file?(@path) && File.size(@path) > MAX_BYTES
+        File.open(@path, File::WRONLY | File::APPEND | File::CREAT, 0o600) do |file|
+          file.flock(File::LOCK_EX)
+          file.write("#{JSON.generate(data)}\n")
+        end
+      end
+
+      def parse(line)
+        data = JSON.parse(line)
+        data.is_a?(Hash) && data["id"].is_a?(String) ? data : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def record(data)
+        Record.new(id: data["id"], at: time(data["at"]), text: data["text"].to_s, note_tags: Array(data["note_tags"]),
+                   triage_model: data["triage_model"],
+                   recipients: Array(data["recipients"]).filter_map { |e| entry(e) }, corrections: [])
+      end
+
+      def entry(data)
+        return nil unless data.is_a?(Hash)
+
+        Entry.new(session: data["session"].to_s, result: data["result"].to_s, p: data["p"], reason: data["reason"].to_s,
+                  by: data["by"].to_s, tags: Array(data["tags"]))
+      end
+
+      def correction(data)
+        sessions = Array(data["sessions"]).filter_map do |d|
+          Delivery.new(session: d["session"].to_s, result: d["result"].to_s) if d.is_a?(Hash)
+        end
+        Correction.new(at: time(data["at"]), sessions: sessions)
+      end
+
+      def time(value)
+        Time.iso8601(value.to_s)
+      rescue ArgumentError
+        Time.at(0)
+      end
+    end
+  end
+end

data/lib/samagotchi/broadcast/triage_model.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../idle_target"
+require_relative "../model_profile"
+
+module Samagotchi
+  # Loaded on first use, as the CLI commands do: host_registry pulls in the
+  # LLM layer.
+  autoload :HostRegistry, File.expand_path("../host_registry", __dir__)
+
+  module Broadcast
+    # Which model a broadcast's triage asks: broadcast.triage_model /
+    # triage_host_ref / triage_base_url; with none of them set, the recap's
+    # (recap.*); with none of those, default.model. Settings that can't be
+    # resolved are a problem, not a fallback to the next ones: triage then
+    # delivers unchecked and says why.
+    module TriageModel
+      # @!attribute target [IdleTarget, nil] nil when +problem+ says why
+      # @!attribute setting [String] where it came from: "broadcast.triage_model",
+      #   "recap.model" or "default.model" (the prefix of the keys read)
+      Choice = Data.define(:target, :setting, :problem)
+
+      SETTINGS = [%w[broadcast.triage_model broadcast.triage_host_ref broadcast.triage_base_url],
+                  %w[recap.model recap.host_ref recap.base_url]].freeze
+
+      module_function
+
+      # @param get [#call] a Config key → its value
+      # @return [Choice]
+      def resolve(host_registry: nil, get: ->(key) { Config.get(key) })
+        registry = host_registry || HostRegistry.new
+        SETTINGS.each do |model, host_ref, base_url|
+          target = IdleTarget.resolve(model: get.call(model), host_ref: get.call(host_ref), base_url: get.call(base_url),
+                                      host_registry: registry)
+          return Choice.new(target: target, setting: model, problem: nil) if target
+        rescue IdleTarget::Unresolved => e
+          return Choice.new(target: nil, setting: model, problem: problem(e, model, host_ref))
+        end
+        model = ModelProfile.required_model_name(get.call("default.model"))
+        Choice.new(target: IdleTarget.of_model(registry, model), setting: "default.model", problem: nil)
+      rescue StandardError => e
+        Choice.new(target: nil, setting: "default.model", problem: e.message.to_s.lines.first.to_s.strip[0, 200])
+      end
+
+      def problem(error, model_key, host_ref_key)
+        case error.reason
+        when :host_ref_unknown then "#{host_ref_key} '#{error.host_ref}' is not in hosts:"
+        when :model_host_mismatch then "#{model_key} '#{error.model}' names host '#{error.named}', not #{host_ref_key} '#{error.host_ref}'"
+        else "#{model_key} is missing (a host or base_url alone names no model)"
+        end
+      end
+      private_class_method :problem
+    end
+  end
+end

data/lib/samagotchi/broadcast_command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "securerandom"
 require_relative "config"
 require_relative "session"
 require_relative "session_inbox"
@@ -7,6 +8,9 @@ require_relative "note_delivery"
 require_relative "broadcast/recipients"
 require_relative "broadcast/scope_card"
 require_relative "broadcast/tags"
+require_relative "broadcast/triage"
+require_relative "broadcast/triage_model"
+require_relative "broadcast/triage_log"
 require_relative "cli/command"
 require_relative "cli/flags"
 
@@ -14,8 +18,11 @@ module Samagotchi
   # `chi broadcast`: share a note with every session it may concern,
   # without picking them. Each recipient (Broadcast::Recipients) that shares
   # a tag with the note (Broadcast::Tags) gets it as a context note from
-  # "broadcast"; --all gives it to every recipient. The rest are listed as
-  # skipped, with why. For the user only: refused inside a chi session.
+  # "broadcast", and a triage model judges the rest (Broadcast::Triage);
+  # --all gives it to every recipient. The rest are listed as skipped, with
+  # why. Each broadcast's verdicts go to Broadcast::TriageLog (`chi
+  # broadcast log`), and `chi broadcast deliver` gives one to sessions it
+  # skipped. For the user only: refused inside a chi session.
   class BroadcastCommand
     include CLI::Command
 
@@ -31,6 +38,8 @@ module Samagotchi
 
     USAGE = <<~TEXT
       Usage: chi broadcast [-m TEXT] [--all] [--dry-run]
+             chi broadcast log [--last N] [--format json]
+             chi broadcast deliver BROADCAST_ID (ID|PREFIX)...
         Shares TEXT (or stdin) with the sessions it may concern, as a context
         note from "broadcast": background the model sees on its next turn,
         not a prompt. It starts no turn.
@@ -39,10 +48,20 @@ module Samagotchi
         the last broadcast.active_hours (8). One gets the note when it shares
         a tag with it: a ticket id (PAY-123) in its branch or your prompts
         there, a pull request (PR #42, its URL) attached to it, a link in
-        your prompts there or its attached context. The rest are skipped.
+        your prompts there or its attached context. A triage model
+        (broadcast.triage_model, else the recap's, else default.model) reads
+        the note and each other session's scope card and says whether it
+        concerns it; one it can't judge in broadcast.triage_deadline (20 s)
+        gets it unchecked. A first line naming one project keeps the note to
+        that project's sessions.
         -m TEXT    the note; without it, stdin is read
-        --all      every recipient, tag or not
+        --all      every recipient, no tags or triage
         --dry-run  show each recipient's scope card, tags and verdict; deliver nothing
+        It prints the broadcast's id (b-7f3a1c9e), then a line per recipient.
+        log: the last N broadcasts (5) and each recipient's verdict, from
+        the triage log; --format json for a script.
+        deliver: the broadcast to sessions it skipped, after all (kept in
+        the log as a correction).
         For you, not for an agent: refused inside a chi session.
         One session or a few by id: chi note. See docs/broadcast.md.
     TEXT
@@ -53,17 +72,33 @@ module Samagotchi
       f.value "-m", "--message", key: :text
     end
 
-    # One recipient's verdict. +match+: the tag that delivers it (nil with
-    # --all or none); +skip+: why it is skipped, else nil.
-    Verdict = Data.define(:recipient, :match, :skip) do
-      def deliver? = skip.nil?
+    LOG_FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS, args: false) do |f|
+      f.value "--last"
+      f.value "--format"
+    end
+
+    DELIVER_FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS)
+
+    # The broadcasts `chi broadcast log` shows by default.
+    LOG_LAST = 5
+
+    # One recipient and its Broadcast::Triage::Verdict.
+    Decision = Data.define(:recipient, :verdict) do
+      def deliver? = verdict.relevant
     end
 
     # @param argv [Array<String>] the arguments after "broadcast"
     # @param active_hours [Numeric, nil] broadcast.active_hours (config)
     # @param ticket_pattern [String, nil] broadcast.ticket_pattern (config)
+    # @param triage [#call, nil] (CancellationController) → a triage
+    #   backend (#judge(note, card) → Verdict); nil: Triage::LLM on
+    #   Broadcast::TriageModel's model
+    # @param log [Broadcast::TriageLog, nil] nil: the default path's
     def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, env: ENV, now: Time.now,
-                   active_hours: Config.get("broadcast.active_hours"), ticket_pattern: Config.get("broadcast.ticket_pattern"))
+                   active_hours: Config.get("broadcast.active_hours"), ticket_pattern: Config.get("broadcast.ticket_pattern"),
+                   triage: nil, triage_parallel: Config.get("broadcast.triage_parallel"),
+                   triage_deadline: Config.get("broadcast.triage_deadline"), threshold: Config.get("broadcast.threshold"),
+                   log: nil)
       @argv = argv.dup
       @stdin = stdin
       @stdout = stdout
@@ -73,18 +108,24 @@ module Samagotchi
       @now = now
       @active_hours = active_hours || 8
       @ticket = Broadcast::Tags.ticket_regexp(ticket_pattern, warn: ->(line) { @stderr.puts("chi broadcast: #{line}") })
+      @triage = triage
+      @triage_parallel = (triage_parallel || Broadcast::Triage::DEFAULT_PARALLEL).to_i
+      @triage_deadline = (triage_deadline || Broadcast::Triage::DEFAULT_DEADLINE).to_f
+      @threshold = (threshold || Broadcast::Triage::DEFAULT_THRESHOLD).to_f
+      @log = log || Broadcast::TriageLog.new
     end
 
     # @return [Integer] exit status: 0 done (skipped sessions included),
     #   1 refused, nothing to send to or a delivery failed, 2 usage
     def run
+      case @argv.first
+      when "log" then return run_log(@argv.drop(1))
+      when "deliver" then return run_deliver(@argv.drop(1))
+      end
+
       options = parse
       return options if options.is_a?(Integer)
-
-      unless @env[PARENT_ENV].to_s.empty?
-        error_line("chi broadcast: chi broadcast is for your user, not an agent")
-        return 1
-      end
+      return refused if agent?
 
       text = utf8(options[:text] || read_stdin)
       return usage_error("no note text: pass -m TEXT or pipe it in") unless text
@@ -113,6 +154,15 @@ module Samagotchi
       parsed.is_a?(Integer) ? parsed : parsed.options
     end
 
+    # Inside a chi session (any SAMAGOTCHI_PARENT_SESSION, "chi" included):
+    # an agent runs it.
+    def agent? = !@env[PARENT_ENV].to_s.empty?
+
+    def refused
+      error_line("chi broadcast: chi broadcast is for your user, not an agent")
+      1
+    end
+
     # @return [Integer] exit status
     def broadcast(text, all:, dry_run:)
       recipients = Broadcast::Recipients.list(state_dir: @state_dir, active_hours: @active_hours, now: @now)
@@ -124,73 +174,245 @@ module Samagotchi
 
       note_tags = Broadcast::Tags.of_text(text, from: "note", ticket: @ticket)
       cards = recipients.to_h { |r| [r.id, Broadcast::ScopeCards.build(r, state_dir: @state_dir, ticket: @ticket)] }
-      verdicts = recipients.map { |r| verdict(r, cards.fetch(r.id), note_tags, all: all) }
-      verdicts = verdicts.select(&:deliver?) + verdicts.reject(&:deliver?)
-
-      @stdout.puts("broadcast#{" (dry run: nothing is delivered)" if dry_run}  #{headline(text)}")
+      id = "b-#{SecureRandom.hex(4)}" unless dry_run
+      @stdout.puts("broadcast #{id || "(dry run: nothing is delivered)"}  #{headline(text)}")
       @stdout.puts("note tags: #{note_tags.empty? ? "none" : note_tags.map(&:label).join(" · ")}") if dry_run
-      return dry_run(verdicts, cards) if dry_run
+      @stdout.flush
+      decisions = decide(text, recipients, cards, note_tags, all: all)
+      decisions = decisions.select(&:deliver?) + decisions.reject(&:deliver?)
+      @stdout.puts("triage model: #{@triage_choice.target&.label || "none"} (#{@triage_choice.setting})") if dry_run && @triage_choice
+      return dry_run(decisions, cards) if dry_run
+
+      deliver_all(Broadcast::TriageLog::Record.new(id: id, at: @now, text: text, note_tags: note_tags.map(&:label),
+                                                   triage_model: @triage_choice&.target&.label, recipients: [],
+                                                   corrections: []), decisions, cards)
+    end
+
+    # Every recipient's verdict: a chi REPL takes no notes, --all takes the
+    # rest, else Broadcast::Triage (tags, the scope line, the model).
+    # @return [Array<Decision>] in +recipients+' order
+    def decide(text, recipients, cards, note_tags, all:)
+      fixed = recipients.to_h do |r|
+        verdict = if r.repl?
+                    Broadcast::Triage::Verdict.new(relevant: false, p: nil, reason: "open in a chi REPL", by: "repl")
+                  elsif all
+                    Broadcast::Triage::Verdict.new(relevant: true, p: nil, reason: "--all", by: "all")
+                  end
+        [r.id, verdict]
+      end
+      judged = recipients.reject { |r| fixed[r.id] }.map { |r| cards.fetch(r.id) }
+      triaged = Broadcast::Triage.verdicts(text, judged, note_tags: note_tags, new_backend: method(:triage_backend),
+                                                         parallel: @triage_parallel, deadline: @triage_deadline)
+      recipients.map { |r| Decision.new(recipient: r, verdict: fixed[r.id] || triaged.fetch(r.id)) }
+    end
+
+    # One triage backend for a thread (Triage.judge_all): the injected
+    # one, or Triage::LLM on the triage model, resolved once; with no
+    # model to ask, one that delivers unchecked and says why.
+    def triage_backend(cancel)
+      return @triage.call(cancel) if @triage
 
-      deliver_all(verdicts, text)
+      choice = triage_choice
+      return UncheckedBackend.new("no triage model: #{choice.problem}") unless choice.target
+
+      Broadcast::Triage::LLM.new(target: choice.target, timeout: @triage_deadline, threshold: @threshold,
+                                 cancel_controller: cancel)
     end
 
-    def verdict(recipient, card, note_tags, all:)
-      return Verdict.new(recipient: recipient, match: nil, skip: "open in a chi REPL") if recipient.repl?
+    def triage_choice
+      (@triage_lock ||= Mutex.new).synchronize do
+        @triage_choice ||= Broadcast::TriageModel.resolve.tap do |choice|
+          error_line("chi broadcast: no triage model: #{choice.problem}; delivering unchecked") unless choice.target
+        end
+      end
+    end
 
-      match = Broadcast::Tags.match(note_tags, card.tags)
-      skip = "no tag match (not checked: no triage yet)" unless all || match
-      Verdict.new(recipient: recipient, match: match, skip: skip)
+    # A triage backend with no model: every card it gets is delivered
+    # unchecked, +why+ in the reason.
+    UncheckedBackend = Data.define(:why) do
+      def judge(_note, _card) = Broadcast::Triage.unchecked(why)
     end
 
-    def dry_run(verdicts, cards)
-      verdicts.each do |v|
-        @stdout.puts(line(v.recipient, v.deliver? ? "would get it" : "skipped", reason(v), width: 12))
-        @stdout.puts(cards.fetch(v.recipient.id).to_s.gsub(/^/, "          "))
+    def dry_run(decisions, cards)
+      decisions.each do |d|
+        @stdout.puts(line(d.recipient, d.deliver? ? "would get it" : "skipped", d.verdict.reason, width: 12))
+        @stdout.puts(cards.fetch(d.recipient.id).to_s.gsub(/^/, "          "))
       end
-      delivered = verdicts.count(&:deliver?)
-      @stdout.puts("would deliver #{delivered} · skipped #{verdicts.size - delivered}")
+      delivered = decisions.count(&:deliver?)
+      @stdout.puts("would deliver #{delivered} · skipped #{decisions.size - delivered}#{unchecked_summary(decisions)}")
       0
     end
 
-    def deliver_all(verdicts, text)
+    # Delivers +broadcast+ (a TriageLog::Record with no recipients yet) per
+    # +decisions+, prints a line per recipient and the summary, and logs it.
+    def deliver_all(broadcast, decisions, cards)
       ok = true
-      lines = verdicts.map do |v|
-        next [v.recipient, false, "skipped", v.skip] unless v.deliver?
+      lines = decisions.map do |d|
+        next [d, "skipped", d.verdict.reason] unless d.deliver?
 
-        result = NoteDelivery.deliver(v.recipient.id, text: body(text, v.match), source: SOURCE, state_dir: @state_dir)
-        next [v.recipient, false, "skipped", "open in a chi REPL"] unless result.delivered?
+        result = NoteDelivery.deliver(d.recipient.id, text: body(broadcast.text, d.verdict), source: SOURCE,
+                                                      state_dir: @state_dir)
+        next [d, "skipped", "open in a chi REPL"] unless result.delivered?
 
-        [v.recipient, true, "delivered", "#{reason(v)}#{"; waits for its next start" if result.status == :waits}"]
+        [d, "delivered", "#{d.verdict.reason}#{"; waits for its next start" if result.status == :waits}"]
       rescue SessionInbox::NoteRejected, SystemCallError => e
         ok = false
-        [v.recipient, false, "failed", e.message]
+        [d, "failed", e.message]
       end
-      lines.sort_by.with_index { |(_, delivered), i| [delivered ? 0 : 1, i] }.each do |recipient, _, word, why|
-        @stdout.puts(line(recipient, word, why))
+      lines.sort_by.with_index { |(_, word), i| [word == "delivered" ? 0 : 1, i] }.each do |d, word, why|
+        @stdout.puts(line(d.recipient, word, why))
       end
-      delivered = lines.count { |_, d| d }
-      @stdout.puts("delivered #{delivered} · skipped #{lines.size - delivered}")
+      delivered = lines.count { |_, word| word == "delivered" }
+      @stdout.puts("delivered #{delivered} · skipped #{lines.size - delivered}#{unchecked_summary(decisions)}")
+      write_log(broadcast, lines, cards)
       ok ? 0 : 1
     end
 
+    # The broadcast's verdicts into the triage log; a log that can't be
+    # written is a warning, not a failed broadcast.
+    def write_log(broadcast, lines, cards)
+      entries = lines.map do |d, word, why|
+        verdict = d.verdict
+        Broadcast::TriageLog::Entry.new(session: d.recipient.id, result: word, p: verdict.p, reason: why, by: verdict.by,
+                                        tags: cards.fetch(d.recipient.id).tags.map(&:label))
+      end
+      @log.append_broadcast(id: broadcast.id, at: broadcast.at, text: broadcast.text, note_tags: broadcast.note_tags,
+                            triage_model: broadcast.triage_model, recipients: entries)
+    rescue SystemCallError => e
+      error_line("chi broadcast: the triage log #{@log.path} couldn't be written: #{e.message}")
+    end
+
+    # `chi broadcast log`. @return [Integer] exit status
+    def run_log(argv)
+      parsed = parse_flags(LOG_FLAGS, argv)
+      return parsed if parsed.is_a?(Integer)
+      return refused if agent?
+
+      options = parsed.options
+      last = options[:last] ? Integer(options[:last], exception: false) : LOG_LAST
+      return usage_error("--last takes a positive number") unless last&.positive?
+      return usage_error("--format takes json") unless [nil, "json"].include?(options[:format])
+
+      records = @log.records.last(last)
+      if options[:format] == "json"
+        @stdout.puts(JSON.pretty_generate(records.map(&:to_json_hash)))
+        return 0
+      end
+      @stdout.puts("no broadcasts in the log yet (#{@log.path})") if records.empty?
+      records.each { |record| print_record(record) }
+      0
+    end
+
+    def print_record(record)
+      @stdout.puts("#{record.id}  #{record.at.localtime.strftime("%Y-%m-%d %H:%M")}  #{headline(record.text)}")
+      record.recipients.each { |e| @stdout.puts("  #{e.session[0, 8]}  #{e.result.ljust(9)}  #{e.reason}") }
+      delivered = record.recipients.count { |e| e.result == "delivered" }
+      @stdout.puts("  delivered #{delivered} · skipped #{record.recipients.size - delivered}")
+      record.corrections.each do |c|
+        sessions = c.sessions.map { |d| "#{d.session[0, 8]}#{" (#{d.result})" unless d.result == "delivered"}" }
+        @stdout.puts("  #{c.at.localtime.strftime("%Y-%m-%d %H:%M")} delivered anyway: #{sessions.join(", ")}")
+      end
+    end
+
+    # `chi broadcast deliver BROADCAST_ID SESSION...`: the logged note to
+    # sessions it skipped. @return [Integer] exit status
+    def run_deliver(argv)
+      parsed = parse_flags(DELIVER_FLAGS, argv)
+      return parsed if parsed.is_a?(Integer)
+      return refused if agent?
+
+      given, *sessions = parsed.args
+      return usage_error("give a broadcast id and the sessions to deliver it to") if given.nil? || sessions.empty?
+
+      record = begin
+        @log.find(given)
+      rescue Broadcast::TriageLog::NotFound => e
+        error_line("chi broadcast: #{e.message}")
+        return 1
+      end
+      ids = sessions.map { |given| resolve_session(given) }
+      results = ids.compact.uniq.map { |id| deliver_anyway(record, id) }
+      unless results.empty?
+        begin
+          @log.append_correction(id: record.id, at: @now, sessions: results)
+        rescue SystemCallError => e
+          error_line("chi broadcast: the triage log #{@log.path} couldn't be written: #{e.message}")
+        end
+      end
+      # Done when every session named has the note now.
+      ids.all? && results.all? { |d| ["delivered", "had it"].include?(d.result) } ? 0 : 1
+    end
+
+    # The full id +given+ names (an id or the start of one), or nil after
+    # saying why there is none.
+    def resolve_session(given)
+      id = Session.resolve_id(given, state_dir: @state_dir)
+      Session.load(id, state_dir: @state_dir) # raises ArgumentError when there is no such session
+      id
+    rescue ArgumentError => e
+      error_line("chi broadcast: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      nil
+    rescue SystemCallError => e
+      error_line("chi broadcast: session #{given} can't be read: #{e.message}")
+      nil
+    end
+
+    # @param id [String] a full session id (#resolve_session)
+    # @return [Broadcast::TriageLog::Delivery]
+    def deliver_anyway(record, id)
+      if record.delivered?(id)
+        @stdout.puts(line_for(id, "skipped", "it got #{record.id} already"))
+        return Broadcast::TriageLog::Delivery.new(session: id, result: "had it")
+      end
+
+      result = NoteDelivery.deliver(id, text: passed_on_body(record), source: SOURCE, state_dir: @state_dir)
+      unless result.delivered?
+        @stdout.puts(line_for(id, "skipped", "open in a chi REPL"))
+        return Broadcast::TriageLog::Delivery.new(session: id, result: "refused")
+      end
+
+      @stdout.puts(line_for(id, "delivered", "by hand#{"; waits for its next start" if result.status == :waits}"))
+      Broadcast::TriageLog::Delivery.new(session: id, result: "delivered")
+    rescue SessionInbox::NoteRejected, SystemCallError => e
+      @stdout.puts(line_for(id, "failed", e.message))
+      Broadcast::TriageLog::Delivery.new(session: id, result: "failed")
+    end
+
+    # A logged broadcast passed on by hand: as #body words it, dated when
+    # it was shared.
+    def passed_on_body(record)
+      shared = "Shared by your user on #{record.at.localtime.strftime("%Y-%m-%d %H:%M")}"
+      "#{record.text}\n(#{shared} with the sessions it may concern; your user passed it on to this session.)"
+    end
+
+    def line_for(id, word, why) = "#{id[0, 8]}  #{word.ljust(9)}  #{why}"
+
+    # " · 2 unchecked: triage deadline" when some were delivered without a
+    # verdict (the desktop helper shows only this line), else "".
+    def unchecked_summary(decisions)
+      unchecked = decisions.map(&:verdict).select(&:unchecked?)
+      return "" if unchecked.empty?
+
+      whys = unchecked.map { |v| v.reason.delete_prefix("unchecked: ").sub(/\s*[("].*\z/m, "") }.uniq
+      " · #{unchecked.size} unchecked: #{whys.join(", ")}"
+    end
+
     # What a recipient gets: the user's text first (the terminal's "note
     # from broadcast: …" line shows its start), then a line saying when it
     # was shared (a session with no worker may read it days later; the
-    # note's header has the time only) and why it reached this session. No
-    # instruction: the system prompt says what a broadcast note asks.
-    def body(text, match)
+    # note's header has the time only) and, for a tag match, why it reached
+    # this session. No instruction: the system prompt says what a broadcast
+    # note asks.
+    def body(text, verdict)
       shared = "Shared by your user on #{@now.localtime.strftime("%Y-%m-%d %H:%M")}"
-      return "#{text}\n(#{shared} with every active session.)" unless match
+      return "#{text}\n(#{shared} with every active session.)" if verdict.by == "all"
+      return "#{text}\n(#{shared} with the sessions it may concern.)" unless verdict.match
 
-      because = match.because
+      because = verdict.match.because
       because = "#{because[0, BECAUSE_CHARS - 1]}…" if because.length > BECAUSE_CHARS
       "#{text}\n(#{shared} with the sessions it may concern; it reached you because #{because}.)"
     end
 
-    def reason(verdict)
-      verdict.skip || verdict.match&.reason || "--all"
-    end
-
     def line(recipient, word, why, width: 9) = "#{recipient.short_id}  #{word.ljust(width)}  #{why}"
 
     # The note's first line, quoted and cut, for the output's head.
@@ -206,23 +428,5 @@ module Samagotchi
       value = hours.to_f
       "#{value == value.round ? value.round : value} #{value == 1 ? "hour" : "hours"}"
     end
-
-    # Only a pipe or a file is read, as chi note does: a terminal or a
-    # socket a launcher passes down may never close.
-    def read_stdin
-      return nil if @stdin.respond_to?(:tty?) && @stdin.tty?
-
-      if @stdin.respond_to?(:stat)
-        stat = @stdin.stat
-        return nil unless stat.pipe? || stat.file?
-      end
-
-      @stdin.read
-    end
-
-    # The note as UTF-8 whatever the locale says (see NoteCommand#utf8).
-    def utf8(text)
-      text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
-    end
   end
 end