samagotchi 0.34.0 → 0.35.0

data/lib/samagotchi/broadcast/tags.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Samagotchi
+  module Broadcast
+    # A cheap, deterministic marker found in a note or about a session: a
+    # ticket id, a pull request, a link. A tag the note and a session share
+    # delivers the note there without asking a model (the fast path).
+    # @!attribute kind [String] "ticket", "pr" or "link"
+    # @!attribute value [String] "PAY-123"; "#42" or "acme/shop#42"; a
+    #   link's host and path ("notion.so/team/checkout-v2")
+    # @!attribute from [String] where it was found: "note", "branch",
+    #   "messages" (the user's prompts) or "context <name>" (an attached
+    #   context source)
+    Tag = Data.define(:kind, :value, :from) do
+      def label = "#{kind} #{value}"
+
+      # Same kind and value; a pr with no repo matches the same number in
+      # any repo.
+      def matches?(other)
+        return false unless kind == other.kind
+        return value == other.value unless kind == "pr"
+
+        number, repo = Tags.pr_parts(value)
+        other_number, other_repo = Tags.pr_parts(other.value)
+        number == other_number && (repo.nil? || other_repo.nil? || repo == other_repo)
+      end
+    end
+
+    # A tag of the note and the session tag it matched.
+    Match = Data.define(:note_tag, :session_tag) do
+      # For the broadcast's output: "ticket PAY-123 matches (branch)".
+      def reason = "#{note_tag.label} matches (#{session_tag.from})"
+
+      # For the note the session gets: "ticket PAY-123 matches your branch".
+      def because
+        tag = session_tag
+        case tag.from
+        when "branch" then "#{note_tag.label} matches your branch"
+        when "messages" then "#{note_tag.label} is in your user's messages too"
+        else "#{note_tag.label} matches your attached #{tag.from}"
+        end
+      end
+    end
+
+    # Tags from text, a branch and attached context, and the first match
+    # between a note's and a session's.
+    module Tags
+      DEFAULT_TICKET_PATTERN = '\b[A-Z][A-Z0-9]+-\d+\b'
+      # Words the default ticket pattern would take that are no ticket.
+      NOT_TICKETS = %w[UTF SHA ISO IEC RFC GPT AES RSA ECMA ES HTTP TLS SSL MD IPV X].freeze
+      URL_RE = %r{https?://[^\s<>()\[\]{}"'`|]+}
+      PR_URL_RE = %r{\A(?:www\.)?github\.com/([^/]+/[^/]+)/pull/(\d+)}i
+      PR_TEXT_RE = /\bPR\s?#(\d+)\b/i
+      PR_SOURCE_RE = /\Apr-(\d+)\z/
+      # The order matches are looked for in: the most specific first.
+      KINDS = %w[ticket pr link].freeze
+
+      module_function
+
+      # broadcast.ticket_pattern as a Regexp; nil, empty or invalid → the
+      # default (an invalid one is reported through +warn+).
+      # @return [Regexp]
+      def ticket_regexp(pattern, warn: nil)
+        return Regexp.new(DEFAULT_TICKET_PATTERN) if pattern.to_s.strip.empty?
+
+        Regexp.new(pattern.to_s)
+      rescue RegexpError => e
+        warn&.call("broadcast.ticket_pattern #{pattern.inspect} is not a valid pattern (#{e.message}); using the default")
+        Regexp.new(DEFAULT_TICKET_PATTERN)
+      end
+
+      # @return [Array<Tag>] the tags in +text+ (a note, the user's prompts)
+      def of_text(text, from:, ticket: ticket_regexp(nil))
+        text = text.to_s
+        found = tickets(text, ticket, from: from)
+        found += text.scan(PR_TEXT_RE).map { |(number)| Tag.new(kind: "pr", value: "##{number}", from: from) }
+        text.scan(URL_RE).each { |url| found += of_url(url, from: from) }
+        found.uniq
+      end
+
+      # A session's tags: its branch (matched whatever its case: branches
+      # are often lowercase), the user's messages, its attached context
+      # (a pr-<n> source and every source's URL hint).
+      # @param sources [Array<Array(String, String)>] [name, hint] pairs
+      # @return [Array<Tag>]
+      def of_session(branch:, messages:, sources:, ticket: ticket_regexp(nil))
+        found = tickets(branch.to_s, Regexp.new(ticket.source, ticket.options | Regexp::IGNORECASE), from: "branch")
+        found += messages.flat_map { |text| of_text(text, from: "messages", ticket: ticket) }
+        sources.each do |name, hint|
+          from = "context #{name}"
+          from_hint = hint.to_s.scan(URL_RE).flat_map { |url| of_url(url, from: from) }
+          number = name.to_s[PR_SOURCE_RE, 1]
+          # pr-<n> with no PR URL in its hint: the number alone, any repo
+          found << Tag.new(kind: "pr", value: "##{number}", from: from) if number && from_hint.none? { |t| t.kind == "pr" }
+          found += from_hint
+        end
+        found.uniq { |tag| [tag.kind, tag.value] }
+      end
+
+      # The first session tag a note tag matches, tickets first, then pull
+      # requests, then links.
+      # @return [Match, nil]
+      def match(note_tags, session_tags)
+        KINDS.each do |kind|
+          note_tags.each do |tag|
+            next unless tag.kind == kind
+
+            hit = session_tags.find { |other| tag.matches?(other) }
+            return Match.new(note_tag: tag, session_tag: hit) if hit
+          end
+        end
+        nil
+      end
+
+      # "acme/shop#42" → ["42", "acme/shop"]; "#42" → ["42", nil].
+      def pr_parts(value)
+        repo, number = value.to_s.split("#", 2)
+        [number, repo.to_s.empty? ? nil : repo.downcase]
+      end
+
+      def tickets(text, regexp, from:)
+        text.to_enum(:scan, regexp).filter_map do
+          id = Regexp.last_match(0).upcase
+          next if NOT_TICKETS.include?(id.split("-", 2).first)
+
+          Tag.new(kind: "ticket", value: id, from: from)
+        end
+      end
+      private_class_method :tickets
+
+      # A link's host and path, without the scheme, www., the query, the
+      # fragment or a trailing slash; a pull request URL is a pr tag too. A
+      # bare host ("https://github.com/") says too little to be a tag.
+      def of_url(url, from:)
+        uri = URI.parse(url.sub(/[.,;:!?]+\z/, ""))
+        host = uri.host.to_s.downcase.delete_prefix("www.")
+        path = uri.path.to_s.chomp("/")
+        return [] if host.empty? || path.empty?
+
+        link = "#{host}#{path}"
+        tags = [Tag.new(kind: "link", value: link, from: from)]
+        if (pr = link.match(PR_URL_RE))
+          tags.unshift(Tag.new(kind: "pr", value: "#{pr[1].downcase}##{pr[2]}", from: from))
+        end
+        tags
+      rescue URI::Error
+        []
+      end
+      private_class_method :of_url
+    end
+  end
+end

data/lib/samagotchi/broadcast_command.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "session"
+require_relative "session_inbox"
+require_relative "note_delivery"
+require_relative "broadcast/recipients"
+require_relative "broadcast/scope_card"
+require_relative "broadcast/tags"
+require_relative "cli/command"
+require_relative "cli/flags"
+
+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.
+  class BroadcastCommand
+    include CLI::Command
+
+    SOURCE = "broadcast"
+    # Bytes kept free under SessionInbox's 16 KiB for the line each note
+    # ends with (#body).
+    BODY_ROOM = 512
+    # The longest "because" #body quotes (a link tag can be long).
+    BECAUSE_CHARS = 200
+    # The env every execute/task call exports (Tools::Builtins): set, the
+    # command runs inside a chi session, i.e. an agent runs it.
+    PARENT_ENV = "SAMAGOTCHI_PARENT_SESSION"
+
+    USAGE = <<~TEXT
+      Usage: chi broadcast [-m TEXT] [--all] [--dry-run]
+        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.
+        Recipients: your own sessions (not delegate children, not scratch
+        ones) that a worker or a chi REPL runs now, or that ended a turn in
+        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.
+        -m TEXT    the note; without it, stdin is read
+        --all      every recipient, tag or not
+        --dry-run  show each recipient's scope card, tags and verdict; deliver nothing
+        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
+
+    FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS, args: false) do |f|
+      f.switch "--all"
+      f.switch "--dry-run"
+      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?
+    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)
+    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"))
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @state_dir = state_dir || Session.default_state_dir
+      @env = env
+      @now = now
+      @active_hours = active_hours || 8
+      @ticket = Broadcast::Tags.ticket_regexp(ticket_pattern, warn: ->(line) { @stderr.puts("chi broadcast: #{line}") })
+    end
+
+    # @return [Integer] exit status: 0 done (skipped sessions included),
+    #   1 refused, nothing to send to or a delivery failed, 2 usage
+    def run
+      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
+
+      text = utf8(options[:text] || read_stdin)
+      return usage_error("no note text: pass -m TEXT or pipe it in") unless text
+
+      begin
+        text = SessionInbox.checked_text(text)
+        limit = SessionInbox::NOTE_MAX_BYTES - BODY_ROOM
+        if text.bytesize > limit
+          raise SessionInbox::NoteRejected, "the note is #{text.bytesize} bytes; a broadcast takes up to #{limit} " \
+                                            "(16 KiB less room for the line chi adds)"
+        end
+      rescue SessionInbox::NoteRejected => e
+        error_line("chi broadcast: #{e.message}")
+        return 1
+      end
+
+      broadcast(text, all: options[:all], dry_run: options[:dry_run])
+    end
+
+    private
+
+    def command_name = "chi broadcast"
+
+    def parse
+      parsed = parse_flags(FLAGS, @argv)
+      parsed.is_a?(Integer) ? parsed : parsed.options
+    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)
+      if recipients.empty?
+        error_line("chi broadcast: no sessions to send to: none runs now or ended a turn in the last " \
+                   "#{format_hours(@active_hours)} (chi sessions list --scope=all)")
+        return 1
+      end
+
+      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)}")
+      @stdout.puts("note tags: #{note_tags.empty? ? "none" : note_tags.map(&:label).join(" · ")}") if dry_run
+      return dry_run(verdicts, cards) if dry_run
+
+      deliver_all(verdicts, text)
+    end
+
+    def verdict(recipient, card, note_tags, all:)
+      return Verdict.new(recipient: recipient, match: nil, skip: "open in a chi REPL") if recipient.repl?
+
+      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)
+    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(/^/, "          "))
+      end
+      delivered = verdicts.count(&:deliver?)
+      @stdout.puts("would deliver #{delivered} · skipped #{verdicts.size - delivered}")
+      0
+    end
+
+    def deliver_all(verdicts, text)
+      ok = true
+      lines = verdicts.map do |v|
+        next [v.recipient, false, "skipped", v.skip] unless v.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?
+
+        [v.recipient, true, "delivered", "#{reason(v)}#{"; waits for its next start" if result.status == :waits}"]
+      rescue SessionInbox::NoteRejected, SystemCallError => e
+        ok = false
+        [v.recipient, false, "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))
+      end
+      delivered = lines.count { |_, d| d }
+      @stdout.puts("delivered #{delivered} · skipped #{lines.size - delivered}")
+      ok ? 0 : 1
+    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)
+      shared = "Shared by your user on #{@now.localtime.strftime("%Y-%m-%d %H:%M")}"
+      return "#{text}\n(#{shared} with every active session.)" unless match
+
+      because = 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.
+    def headline(text)
+      lines = text.lines
+      first = lines.first.to_s.strip
+      first = "#{first[0, 59]}…" if first.length > 60
+      first = "#{first} …" if lines.size > 1 && !first.end_with?("…")
+      "\"#{first}\""
+    end
+
+    def format_hours(hours)
+      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

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -128,6 +128,17 @@ rules:
     scopes: [once]
     reason: attaches a command chi will run every few minutes, outside the guardrails
 
+  # ── chi broadcast: for the user, not an agent ─────────────────────────
+  # chi broadcast refuses to run inside a session (SAMAGOTCHI_PARENT_SESSION
+  # is set there), but an agent can unset that; this asks every time, and
+  # only the user may allow it. Quoted words and continuations still match.
+  - id: chi-broadcast
+    tool: shell
+    command: '\bchi["'']?[\s\\]+["'']?broadcast\b'
+    verdict: ask
+    scopes: [once]
+    reason: shares a note with every session it may concern; chi broadcast is for the user, not an agent
+
   # ── answering chi's own questions around chi answer ───────────────────
   # A parent agent answers a child's approval with chi answer, which holds it
   # to guardrails.parent_approvals. These shapes go around that: chi --attach

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

@@ -1,8 +1,8 @@
 ---
 name: guardrails
-version: 0.6.0
+version: 0.7.0
 scope: system
-description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, answering chi around chi answer; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
+description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, chi broadcast, answering chi around chi answer; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed
 # models: in small-models.yml (guardrails.small_models) needs 0.8.1; git: in rules.yml needs 0.17.0;
 # skip_read_only:, touches:, rm: and modes: need 0.20.0

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -8,7 +8,9 @@ require "open3"
 # web, each ref in the answer becomes a link (`[JIRA-123](https://…)`,
 # through event[:present]: display only, the model's text stays as it was,
 # and it survives a reload). Every UI also gets one line right after the
-# turn, the terminals' only view of the links:
+# turn, the terminals' only view of the links (marked fallback_for:
+# :display when the answer links every URL it names, so the web with
+# markdown on leaves it out; needs chi 0.35.0):
 #
 #   sources: JIRA JIRA-123 → https://myjira.com/browse/JIRA-123, JIRA JIRA-10 → https://myjira.com/browse/JIRA-10
 #
@@ -48,8 +50,8 @@ require "open3"
 # of these stays text (warned at load).
 #
 # The note is not stored in the conversation: it is an event, replayed by a
-# UI only while the session's worker lives (a reload keeps it; a stopped
-# worker loses it). The links are stored as the answer's display. A ref in
+# UI with the session's cards (a reload keeps it, after the worker stopped
+# too: cards.json). The links are stored as the answer's display. A ref in
 # code (a `span` or a fenced block) or in a markdown link is not linked in
 # the answer. The hook is inert until sources are configured.
 class SourceLinks
@@ -114,17 +116,34 @@ class SourceLinks
     return if text.nil? || text.empty?
 
     hits = occurrences(text[0, MAX_SCAN])
-    if @note
-      found = collect(hits)
-      event[:notify]&.call(line(found), level: :info) unless found.empty?
-    end
-    # The answer as shown: the model's text unless an earlier hook changed
-    # it (then its offsets differ, so it is scanned again).
-    event[:present]&.call { |shown| link(shown, shown == text ? hits : nil) }
+    linked = present_links(event[:present], text, hits)
+    return unless @note
+
+    found = collect(hits)
+    return if found.empty?
+
+    # The display links every URL the note names: the note only stands in
+    # for it, and a UI that renders the display's links leaves it out.
+    covered = linked && found.all? { |_name, _ref, url| linked.key?(url.downcase) }
+    event[:notify]&.call(line(found), level: :info, fallback_for: covered ? :display : nil)
   end
 
   private
 
+  # Links the refs in the answer as shown: the model's text unless an
+  # earlier hook changed it (then its offsets differ, so it is scanned
+  # again). The URLs it linked (downcased, as #collect dedups), or nil when
+  # the display didn't take them (no event[:present], nothing to present, or
+  # the presenter rejected the text).
+  def present_links(present, text, hits)
+    return nil unless present
+
+    linked = {}
+    ours = nil
+    shown = present.call { |display| ours = link(display, display == text ? hits : nil, linked) }
+    ours.nil? || shown != ours ? nil : linked
+  end
+
   # The content of the last `role: "model"` message, or nil. Handles both
   # string- and symbol-keyed messages. A turn that ended without a visible
   # answer stores a `kind: turn_note` system message instead, so the role
@@ -198,8 +217,8 @@ class SourceLinks
 
   # +text+ with each ref as a markdown link, every occurrence; the part
   # beyond MAX_SCAN stays as it is. +hits+ are the scan of that text when
-  # the caller has it.
-  def link(text, hits = nil)
+  # the caller has it; +linked+ gets each linked URL, downcased.
+  def link(text, hits = nil, linked = {})
     head = text[0, MAX_SCAN]
     hits ||= occurrences(head)
     out = +""
@@ -208,6 +227,7 @@ class SourceLinks
       next if hit[:quiet] || hit[:start] < pos # two sources on one ref: the first wins
 
       out << head[pos...hit[:start]] << "[#{hit[:ref].gsub(/[\[\]]/) { |c| "\\#{c}" }}](#{link_target(hit[:url])})"
+      linked[hit[:url].downcase] = true
       pos = hit[:finish]
     end
     return text if pos.zero?

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,14 +1,15 @@
 ---
 name: source-links
-version: 0.3.4
+version: 0.4.0
 scope: system
 description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
+requires_chi: ">= 0.35.0"
 files:
-  source_links.md: sha256:aebd37f1e25491780994ecc4afc20ed6e8db32b724dc038302bb050177efada8
+  source_links.md: sha256:1670a3051b67610f41a680fc8e61bc1c99657a87f0f32121d040e05512896748
 hooks:
   source_links.rb:
-    sha256: sha256:c93269964ebc824b5f15ab60db81a458facd50de61446c550f254ea4c68964e2
+    sha256: sha256:8ce4d11659f4bc151167f99e47299c0f6ef246797c9167c609c1699e3edea2e5
     event: after_turn
     on_error: log
     priority: 90

data/lib/samagotchi/bundles/source-links/source_links.md

@@ -1,5 +1,5 @@
 # Source links
 
-The `source-links` bundle's `after_turn` hook links the source refs (a JIRA ticket, a GitHub issue, …) in your answers. In the web, each ref in the answer becomes a link; that is how the answer is **shown**, not what you wrote: your own message keeps the plain ref. A `sources: NAME ref → url, …` line right after an answer is the same hook's note, which every UI shows (the terminals only see this line). The line is **not part of the conversation**: it is an event, so it is not in the session file and you cannot refer back to it. A UI replays it while the session's worker lives (a page reload keeps it; a stopped worker loses it).
+The `source-links` bundle's `after_turn` hook links the source refs (a JIRA ticket, a GitHub issue, …) in your answers. In the web, each ref in the answer becomes a link; that is how the answer is **shown**, not what you wrote: your own message keeps the plain ref. A `sources: NAME ref → url, …` line right after an answer is the same hook's note (the terminals only see this line). The web leaves it out when markdown is on and the answer links every ref it names; otherwise every UI shows it. The line is **not part of the conversation**: it is an event, so it is not in the session file and you cannot refer back to it. A UI replays it with the session's cards (a page reload keeps it, after the worker stopped too).
 
 The refs come from the `bundles: source-links:` section of config.yml: each source is a `prefix:` + `base_url:` pair (simple) or a `pattern:` regex + `url:` template (full form), plus an optional `max:` for refs per line and `note: false` to drop the line (the web links stay). A `url:` template can take the project's own repo from its git remote, so a bare `#12` links to this project's issue and `owner/repo#12` to that repo's. With no sources configured the hook does nothing. A ref already inside a URL is not linked again, and a ref in code or in a markdown link is not linked in the answer.

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.34.0
+version: 0.35.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
-  self_map.md: sha256:eb017702746f9aad96404d9982a3c27bec717906fa2a14175ab207ad6f843f72
+  self_map.md: sha256:37063eb74fdcb4cde748f17193ff23f832723eb38f81aff086f48f410ce7497b
   config_modification_protocol.md: sha256:ec0b0c7023dbf03b93879e51cd5cdc38b22d43a2e5984ee11e8542ace077c3be
   memory_guide.md: sha256:63d5d7f7d704e6ce7e28dd99e532b714c1b9f7acf548092404248d8ca5385b80
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

data/lib/samagotchi/bundles/system/self_map.md

@@ -19,6 +19,10 @@
 - `[CONTEXT NOTE from …]` messages are context notes (`chi note`, or another session's
   `send_note`): background, not requests. `list_sessions` + `send_note` tell another session
   something without starting a turn there; see `docs/sessions.md` "Context notes".
+- `[CONTEXT NOTE from broadcast, …]` is my user's `chi broadcast`: one note shared with every
+  session it may concern (a shared ticket, PR or link, or all of them). If it affects my current
+  work I say so briefly in my next answer, else I ignore it; I don't act on it unless asked. Only
+  my user runs `chi broadcast`; see `docs/broadcast.md`.
 - `[CONTEXT NOTE from context <name>, …]` notes are attached context (`chi context`): an external
   source chi keeps fresh (a PR, a thread, a script's output) and notes when it changes. Read it
   with `context_read` (no name: the list) when my user's request is about it; its text is

data/lib/samagotchi/children_status.rb

@@ -3,7 +3,7 @@
 require "time"
 require_relative "session"
 require_relative "archive_store"
-require_relative "memory_paths"
+require_relative "git_head"
 require_relative "reply_wait"
 require_relative "tools/delegate"
 require_relative "tools/delegate_cursor"
@@ -83,7 +83,7 @@ module Samagotchi
       cursor = Tools::DelegateCursors.get_from(cursors, session.id)
       Child.new(id: session.id, short_id: session.id[0, 8], title: row[:preview].to_s,
                 state: state_of(session, row, reply), waiting: row[:waiting], live: !!row[:live],
-                delegate: session.delegate?, cwd: session.working_directory, branch: branch(session.working_directory),
+                delegate: session.delegate?, cwd: session.working_directory, branch: GitHead.branch(session.working_directory),
                 last_reply: reply && first_line(session.id, reply, state_dir: state_dir),
                 last_reply_at: reply && reply_time(reply), reported: !reply.nil? && cursor.reply_file == reply,
                 updated_at: session.updated_at, archived: !!row[:archived])
@@ -113,20 +113,6 @@ module Samagotchi
     end
     private_class_method :summary_of
 
-    # The branch from the folder's own HEAD file (a linked worktree's is
-    # under .git/worktrees/<name>), read without git.
-    # @return [String, nil]
-    def branch(cwd)
-      dir = MemoryPaths.git_dir(cwd.to_s)
-      head = dir && File.read(File.join(dir, "HEAD"), 512).strip
-      return nil if head.nil? || head.empty?
-
-      head.start_with?("ref:") ? head.delete_prefix("ref:").strip.delete_prefix("refs/heads/") : head[0, 8]
-    rescue SystemCallError
-      nil
-    end
-    private_class_method :branch
-
     def first_line(id, file, state_dir:)
       text = File.read(File.join(ReplyWait.reply_dir(id, state_dir: state_dir), file), 4096)
       text.each_line.map(&:strip).find { |line| !line.empty? }.to_s

data/lib/samagotchi/config.rb

@@ -84,6 +84,12 @@ module Samagotchi
       # "N-M" or "N" sentences (1-10); unset = 2-4. Parsed by RecapPrompt.sentences_range.
       Entry.new(key: "recap.sentences",          yaml_path: %w[recap sentences],           type: :string,  default: nil,             expose: %i[env config cli]),
 
+      # chi broadcast (Broadcast::Recipients, Broadcast::Tags): a session that ended no turn in this many hours (and
+      # no worker or REPL runs) gets no broadcast; a ticket id in the note and in a session's branch or prompts
+      # delivers it there without triage.
+      Entry.new(key: "broadcast.active_hours",   yaml_path: %w[broadcast active_hours],   type: :float,   default: 8.0,             expose: %i[env config]),
+      Entry.new(key: "broadcast.ticket_pattern", yaml_path: %w[broadcast ticket_pattern], type: :string,  default: '\b[A-Z][A-Z0-9]+-\d+\b', expose: %i[env config]),
+
       Entry.new(key: "session.retention_days",        yaml_path: %w[session retention_days],        type: :integer, default: 14,   expose: %i[env config cli]),
       Entry.new(key: "session.max_count",             yaml_path: %w[session max_count],             type: :integer, default: 500,  expose: %i[env config cli]),
       Entry.new(key: "session.keep_status",           yaml_path: %w[session keep_status],           type: :string, default: "", expose: %i[env config cli]),