samagotchi 0.34.0 → 0.36.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.36.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
+  memory_guide.md: sha256:f7049304a333be842b761037bab5c8e31e890b8f4ad12f092b14ee8deb053c51
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

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

@@ -33,14 +33,16 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 - Parameters: `name: "entry_name"`, `content: "..."`, `scope: "project"|"system"`, optional `description: "one-liner"`, optional `current_model_only: true`.
 - `name` is the entry name **without** `.md` (the tool adds it). Use `name`, **not** `path` — `path` belongs to the file tools and is ignored here. `name: "index"` is a verbatim write to `index.md` (no auto-index update) — rarely needed.
 - `scope` is **required** — never omit. Prefer `project` for repo conventions, `system` for user preferences.
-- `description` is appended to the managed `index.md` line (`— description`). Replaces previous description if given; otherwise preserves existing one.
+- `description` is appended to the managed `index.md` line (`— description`): one line, at most 200 characters (longer is refused; newlines become spaces). Replaces previous description if given; a missing or blank one preserves the existing one.
+- To change only the description, pass `name`, `scope` and `description` without `content`: the index line changes (its date becomes today), the file stays as it is. The memory must exist in that scope.
+- To remove a memory, pass `name`, `scope` and `remove: true` (nothing else): its file and model overlays move to the bundle trash (`chi bundle trash` lists and empties it) and its index line goes, a dangling line too. Only when the user asked or a skill's steps say so; the guardrails ask the user first. A memory a bundle installed is refused: `chi bundle uninstall` owns it.
 - For a small change to an existing memory (a step, a line), `edit` its file instead of rewriting it all: the path is in `memory_write`'s result and the scope dirs are in the prompt. Its index line is refreshed either way.
 - On success returns `Memory 'name' saved to <scope> scope (N bytes). File written: <path> Index line refreshed automatically.` — confirm `bytes` and `scope`; the index needs nothing from you.
 
 **When to write:**
 - After learning a durable preference (e.g. commit style, test command, coding guideline) that the user confirmed or you observed repeatedly — ask before overwriting existing entries where appropriate.
 - Keep entries small and focused (one topic per file). Use clear filenames: `commit_preferences`, `testing_guide`, `project_conventions`.
-- Never store secrets, tokens, or transient state. Memories are shared via bundles.
+- Never store secrets, tokens, or transient state. Memories are shared via bundles. One exception: a skill may keep a working handoff memory (its steps say so) whose status is its description, removed when the work is done.
 
 **Placeholders:**
 - Content may contain placeholder hints written as double-curly braces around a name (e.g., test_command, language). Detected by `Placeholder` (`Placeholder::PLACEHOLDER_RE`) — install warns but does not fail. Fill them when you write. The placeholder syntax is two opening braces, a name, two closing braces.

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]),

data/lib/samagotchi/engine.rb

@@ -203,7 +203,7 @@ module Samagotchi
         emit: ->(sink, event) { emit_event(sink, event) },
         show_card: ->(**card) { show_card(**card) },
         tools: -> { @tools },
-        notify: ->(text, level, source) { hook_notify(text, level, source) },
+        notify: ->(text, level, source, fallback_for: nil) { hook_notify(text, level, source, fallback_for: fallback_for) },
         tools_changed: -> { tools_changed! }
       )
       @lifecycle_mutex = Mutex.new
@@ -1223,7 +1223,7 @@ module Samagotchi
     # hook's label (event[:hook]) from the registry.
     def hook_runtime
       Hooks::Runtime.new(
-        notify: ->(text:, level:, hook:) { hook_notify(text, level, hook) },
+        notify: ->(text:, level:, hook:, fallback_for: nil) { hook_notify(text, level, hook, fallback_for: fallback_for) },
         ask_user: ->(question:, options:, header:, allow_freeform:, hook:) { hook_ask_user(question, options, header, allow_freeform, hook) },
         stop_turn: ->(reason:, hook:) { hook_stop_turn(reason, hook) },
         steer: ->(text:, hook:) { steer(text, source: hook_source(hook)) },
@@ -1239,14 +1239,24 @@ module Samagotchi
     end
     private :hook_source
 
+    # What a notice may stand in for (hook_notify's fallback_for:).
+    NOTICE_FALLBACKS = %i[display].freeze
+
     # One line to the user (:hook_notice). During a turn it is a turn
     # event: the turn's sink (the REPL) and the observers (bridge, log).
     # Outside one (a plugin's command at the prompt) it is announced with
     # between_turns: true, which every UI shows as cards are shown.
-    def hook_notify(text, level, hook)
+    #
+    # +fallback_for+ names what the line stands in for (NOTICE_FALLBACKS):
+    # :display, the answer's display (AnswerDisplay), for a UI that doesn't
+    # render its links. A UI that does leaves the line out; the others, the
+    # log among them, show it. An unknown value is dropped, so the line
+    # shows everywhere.
+    def hook_notify(text, level, hook, fallback_for: nil)
       level = (level || :info).to_sym
       level = :info unless %i[info warn].include?(level)
-      notice = { type: :hook_notice, hook: hook.to_s, text: text.to_s, level: level }
+      notice = { type: :hook_notice, hook: hook.to_s, text: text.to_s, level: level,
+                 fallback_for: notice_fallback(fallback_for, hook) }.compact
       return hold_load_event(notice) && nil if @loading_plugins
 
       in_turn, sink = @turn_state.in_turn_sink
@@ -1263,6 +1273,20 @@ module Samagotchi
     end
     private :hook_notify
 
+    # A known fallback_for (a String is symbolized), else nil; an unknown
+    # one is logged once at debug.
+    def notice_fallback(value, hook)
+      return if value.nil?
+
+      fallback = value.to_s.to_sym
+      return fallback if NOTICE_FALLBACKS.include?(fallback)
+
+      @unknown_fallbacks ||= Set.new
+      Log.debug(:hooks, "notice_unknown_fallback", hook: hook.to_s, value: value.to_s) if @unknown_fallbacks.add?(fallback)
+      nil
+    end
+    private :notice_fallback
+
     # A guardrails line to the user after load (:guardrail_warning, as the
     # load failures show): a running turn's event, else announced.
     def guardrail_notify(message)
@@ -2285,7 +2309,7 @@ module Samagotchi
         cwd: -> { @session&.working_directory },
         messages: -> { plugin_messages },
         messages_partial: -> { turn_running? && @running_turn_messages.nil? },
-        notify: ->(text, level, label) { hook_notify(text, level, label) },
+        notify: ->(text, level, label, fallback_for: nil) { hook_notify(text, level, label, fallback_for: fallback_for) },
         ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:|
           hook_ask_user(question, options, header, allow_freeform, hook)
         },

data/lib/samagotchi/git_head.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "memory_paths"
+
+module Samagotchi
+  # What a folder has checked out, read from its HEAD file without running
+  # git (cheap enough for a list of sessions).
+  module GitHead
+    module_function
+
+    # The branch checked out in +dir+'s repository (a linked worktree's own
+    # HEAD is under .git/worktrees/<name>), a short sha when detached.
+    # @return [String, nil] nil outside git or for an unreadable HEAD
+    def branch(dir)
+      git_dir = MemoryPaths.git_dir(dir.to_s)
+      head = git_dir && File.read(File.join(git_dir, "HEAD"), 512).to_s.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
+  end
+end

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -46,6 +46,9 @@ module Samagotchi
       # one). samagotchi/context stops before a word character or a dot, so
       # chi's own lib/samagotchi/context_*.rb isn't one.
       CHI_TEXT = %r{\.config/samagotchi|samagotchi/config\.yml|samagotchi/hooks|samagotchi/guardrails|samagotchi/context(?![\w.])|memories/\.bundles}
+      # The guardrails bundle's ask before a memory removal: its paths are in
+      # the config dir, yet a parent may answer it.
+      MEMORY_REMOVE_RULE = "memory-remove"
       # The guardrails bundle's shell-touches-chi, for a word it can't
       # resolve to a path (Guardrails::ShellPaths): CHI_TEXT and .git/hooks.
       CHI_SHELL_TEXT = Regexp.union(CHI_TEXT, %r{\.git/hooks})
@@ -94,6 +97,9 @@ module Samagotchi
         return false unless facts.is_a?(Hash)
         return true if PROTECTED_RULES.include?(fetch(facts, :rule).to_s)
         return true if fetch(facts, :source).to_s == ProtectedPaths::SOURCE
+        # A memory's file sits in the config dir, but removing one is the
+        # memory-remove rule's ask, which a parent may answer.
+        return false if fetch(facts, :rule).to_s == MEMORY_REMOVE_RULE
 
         dirs = chi_dirs
         paths = Array(fetch(facts, :paths)).map(&:to_s).reject(&:empty?)

data/lib/samagotchi/guardrails/rules.rb

@@ -28,6 +28,7 @@ module Samagotchi
     #   modes:   "strict", "auto" or a list of them: the rule only votes
     #            in those guardrails.mode values (missing = every mode;
     #            a rule from config.yml without it votes in every mode)
+    #   memory:  "remove": a memory_write call with remove: true
     #   skip_read_only: true: a shell command that only reads
     #            (ReadOnlyShell) doesn't match
     # verdict ask|deny, reason, scopes (for an ask; default all).
@@ -38,14 +39,14 @@ module Samagotchi
     class Rules
       class ParseError < StandardError; end
 
-      KEYS = %w[id tool command path git touches rm models modes skip_read_only verdict reason scopes].freeze
-      MATCH_KEYS = %w[tool command path git touches rm].freeze
+      KEYS = %w[id tool command path git touches rm memory models modes skip_read_only verdict reason scopes].freeze
+      MATCH_KEYS = %w[tool command path git touches rm memory].freeze
       VERDICTS = %w[ask deny].freeze
       # guardrails.mode's values.
       MODES = %w[auto strict].freeze
       GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
 
-      Rule = Struct.new(:id, :tools, :command, :path, :git, :touches, :rm, :models, :modes, :skip_read_only, :verdict, :reason,
+      Rule = Struct.new(:id, :tools, :command, :path, :git, :touches, :rm, :memory, :models, :modes, :skip_read_only, :verdict, :reason,
                         :scopes, :source, keyword_init: true) do
         def matches?(targets)
           return false unless targets
@@ -56,6 +57,7 @@ module Samagotchi
           return false if git && !targets.git_outside_repo?
           return false if touches && !targets.touches_chi?
           return false if rm && !targets.rm_outside_tmp?
+          return false if memory && !targets.memory_remove?
           return false if skip_read_only && targets.read_only?
 
           true
@@ -128,7 +130,8 @@ module Samagotchi
 
         Rule.new(id: id, tools: tools_of(raw["tool"], label), command: regex_of(raw["command"], label),
                  path: path_of(raw["path"], label), git: git_of(raw["git"], label),
-                 touches: touches_of(raw["touches"], label), rm: rm_of(raw["rm"], label), models: models_of(raw["models"], label),
+                 touches: touches_of(raw["touches"], label), rm: rm_of(raw["rm"], label), memory: memory_of(raw["memory"], label),
+                 models: models_of(raw["models"], label),
                  modes: modes_of(raw["modes"], label),
                  skip_read_only: flag_of(raw, "skip_read_only", label), verdict: verdict.to_sym,
                  reason: (raw["reason"] || "rule #{id}").to_s, scopes: scopes_of(raw["scopes"], label), source: source)
@@ -185,6 +188,14 @@ module Samagotchi
         value
       end
 
+      # Only "remove" for now.
+      def self.memory_of(value, label)
+        return nil if value.nil?
+        raise ParseError, "#{label}: memory must be remove" unless value == "remove"
+
+        value
+      end
+
       def self.modes_of(value, label)
         return nil if value.nil?
 

data/lib/samagotchi/guardrails/targets.rb

@@ -42,6 +42,11 @@ module Samagotchi
       #   chi's own tools
       attr_reader :args
 
+      # @return [Boolean] a memory_write call that removes a memory (remove:
+      #   true), for a rule's memory: remove
+      attr_reader :memory_remove
+      alias memory_remove? memory_remove
+
       # @param call [Hash] the parsed tool call
       # @param context [Context]
       # @param model_key [String, nil] for a memory_write model overlay, and
@@ -76,8 +81,9 @@ module Samagotchi
           entry = registry && registry[tool]
           args = call[:args] if entry && !entry.core? && call[:args].is_a?(Hash)
         end
+        memory_remove = tool == "memory_write" && call[:remove].to_s.strip.downcase == "true"
         new(tool: tool, command: command, paths: paths.compact, cwd: cwd, repo_root: context.repo_root(cwd),
-            repo: context.repo(cwd), args: args,
+            repo: context.repo(cwd), args: args, memory_remove: memory_remove,
             model_name: model_name, model_key: model_key, session_root: context.repo_root(base) || base,
             chi_dirs: -> { chi_dirs(context, base) })
       end
@@ -128,7 +134,8 @@ module Samagotchi
 
       # @param chi_dirs [#call, nil] → the dirs touches_chi? looks for
       def initialize(tool:, command:, paths:, cwd:, repo_root:, repo: nil, args: nil, model_name: nil, model_key: nil,
-                     session_root: nil, chi_dirs: nil)
+                     session_root: nil, chi_dirs: nil, memory_remove: false)
+        @memory_remove = memory_remove
         @repo = repo
         @chi_dirs = chi_dirs
         @session_root = session_root || repo_root || cwd

data/lib/samagotchi/guardrails/verdict.rb

@@ -13,9 +13,10 @@ module Samagotchi
       STRICTNESS = { allow: 0, ask: 1, deny: 2 }.freeze
       # Rules that ask about chi's own config and hooks: the core
       # ProtectedPaths asks and the guardrails bundle's shell rule; and a
-      # command source for attached context (it runs later, ungated). Only
-      # the user may allow them (ParentApprovals).
-      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd].freeze
+      # command source for attached context (it runs later, ungated); chi
+      # broadcast, which is the user's. Only the user may allow them
+      # (ParentApprovals).
+      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd chi-broadcast].freeze
       SCOPES = %w[once session repo rule].freeze
       DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."
 

data/lib/samagotchi/hooks/registry.rb

@@ -83,8 +83,9 @@ module Samagotchi
 
     # What a hook can do beyond reading its event: the Engine's
     # callables, each given the hook's label. +notify+ takes
-    # (text:, level:, hook:) and shows one line to the user; +ask_user+
-    # takes (question:, options:, header:, allow_freeform:, hook:) and
+    # (text:, level:, hook:, and fallback_for: when the hook gave one: what
+    # the line stands in for, Engine#hook_notify) and shows one line to the
+    # user; +ask_user+ takes (question:, options:, header:, allow_freeform:, hook:) and
     # returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
     # cancels the running turn (true when it did); +steer+ takes (text:,
     # hook:) and puts the text into the running turn (Engine#steer, true
@@ -239,7 +240,10 @@ module Samagotchi
       #
       # All procs get the same hash, so event[:hook] is set before each one;
       # the helpers are set once per fire and read event[:hook] when called:
-      #   event[:notify].call(text, level: :info)   one line to the user
+      #   event[:notify].call(text, level: :info, fallback_for: nil)   one line
+      #     to the user; fallback_for: :display marks a line that stands in
+      #     for the answer's display (event[:present]), which a UI that
+      #     renders the display's links leaves out (Engine#hook_notify)
       #   event[:ask_user].call(question:, options:, header: nil, allow_freeform: false)
       #     -> {selected:, freeform:, selected_indices:} or nil (no one to
       #     ask, cancelled, bad options)
@@ -330,8 +334,10 @@ module Samagotchi
       def with_runtime(event)
         return unless event.is_a?(Hash)
 
-        event[:notify] ||= lambda { |text, level: :info|
-          @runtime&.notify&.call(text: text.to_s, level: level, hook: event[:hook])
+        event[:notify] ||= lambda { |text, level: :info, fallback_for: nil|
+          notice = { text: text.to_s, level: level, hook: event[:hook] }
+          notice[:fallback_for] = fallback_for unless fallback_for.nil?
+          @runtime&.notify&.call(**notice)
           nil
         }
         event[:ask_user] ||= lambda { |question:, options:, header: nil, allow_freeform: false|

data/lib/samagotchi/log_subscriber.rb

@@ -147,7 +147,7 @@ module Samagotchi
     # hook's, not the user's or the model's).
     def on_hook_notice(event)
       level = event[:level].to_s == "warn" ? :warn : :info
-      log(level, :hook_notice, hook: event[:hook], msg: event[:text].to_s[0, 300])
+      log(level, :hook_notice, hook: event[:hook], fallback_for: event[:fallback_for], msg: event[:text].to_s[0, 300])
     end
 
     # after_turn hooks presented the answer (AnswerDisplay): its size only

data/lib/samagotchi/memory_bundle/index_updater.rb

@@ -25,7 +25,7 @@ module Samagotchi
           pattern = managed_pattern(entry_name)
           if content.match?(pattern)
             existing = content[pattern].to_s.chomp
-            resolved_desc = description&.to_s&.strip || extract_description(existing)
+            resolved_desc = blank_description?(description) ? extract_description(existing) : description
             resolved_source = source.nil? ? extract_source(existing) : (source || nil)
             new_line = managed_line(entry_name, scope, byte_count, resolved_desc, resolved_source)
             next content.sub(pattern) { new_line + $1 }
@@ -72,11 +72,14 @@ module Samagotchi
       def self.managed_line(name, scope, byte_count, description, source = nil)
         line = "- **#{name}** · #{scope} · #{date_str} · #{byte_count}"
         line += " · from #{source}" unless source.to_s.strip.empty?
-        desc = description&.to_s&.strip
-        line += " — #{desc}" unless desc.to_s.empty?
+        desc = description.to_s.gsub(/\s+/, " ").strip
+        line += " — #{desc}" unless desc.empty?
         line
       end
 
+      # A blank description (nil, "", whitespace) keeps the line's own.
+      def self.blank_description?(description) = description.to_s.strip.empty?
+
       def self.extract_description(line)
         if line =~ /\s—\s(.*)\s*\z/
           $1

data/lib/samagotchi/note_command.rb

@@ -2,6 +2,7 @@
 
 require_relative "session"
 require_relative "session_inbox"
+require_relative "note_delivery"
 require_relative "session_manager"
 require_relative "cli/command"
 require_relative "cli/flags"
@@ -22,6 +23,7 @@ module Samagotchi
         -m TEXT        the note; without it, stdin is read
         --all          every session a worker runs now, in every project
         Find ids with: chi sessions list --live [--scope=all] [--format tsv]
+        Every session it may concern, without picking them: chi broadcast
     TEXT
 
     FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) do |f|
@@ -83,6 +85,8 @@ module Samagotchi
       options = parsed.options.merge(ids: parsed.args)
       return usage_error("give session ids or --all") if options[:ids].empty? && !options[:all]
       return usage_error("--all takes no ids") if options[:all] && options[:ids].any?
+      # The system prompt reads a note from "broadcast" as chi broadcast's.
+      return usage_error("--source broadcast is chi broadcast's own") if options[:source].to_s.strip == "broadcast"
 
       options
     end
@@ -125,21 +129,17 @@ module Samagotchi
 
     # @return [Boolean] whether the note was queued
     def deliver(id, text, source)
-      short = id[0, 8]
-      owner = SessionManager.session_owner(id, state_dir: @state_dir)
-      if owner&.tui?
-        @stdout.puts("#{short}  refused: it is open in a chi REPL; notes need attached mode")
-        return false
-      end
+      result = NoteDelivery.deliver(id, text: text, source: source, state_dir: @state_dir)
+      @stdout.puts("#{id[0, 8]}  #{outcome(result)}")
+      result.delivered?
+    end
 
-      path = SessionInbox.write_note(id, text: text, source: source, state_dir: @state_dir)
-      if owner
-        @stdout.puts("#{short}  queued: its worker adds it within a few seconds")
-      else
-        queued = SessionInbox.find_new_note_files(File.dirname(path, 2)).size
-        @stdout.puts("#{short}  waits for the session's next start (#{queued} #{queued == 1 ? "note" : "notes"} queued)")
+    def outcome(result)
+      case result.status
+      when :refused then "refused: it is open in a chi REPL; notes need attached mode"
+      when :queued then "queued: its worker adds it within a few seconds"
+      else "waits for the session's next start (#{result.queued} #{result.queued == 1 ? "note" : "notes"} queued)"
       end
-      true
     end
 
     # The note as UTF-8 whatever the locale says: with no LANG/LC_* (an app

data/lib/samagotchi/note_delivery.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "session_inbox"
+
+module Samagotchi
+  # Loaded on first use: session_manager requires terminal_ui, which
+  # requires KernelLoop and so the tools (a require cycle otherwise).
+  autoload :SessionManager, File.expand_path("session_manager", __dir__)
+
+  # The one rule for putting a context note into a session, shared by
+  # `chi note`, the agent's send_note and `chi broadcast`: a session a chi
+  # REPL owns refuses it (notes need attached mode); any other gets the
+  # note in its notes/ folder, which a live worker adds within seconds and
+  # a session with no worker at its next start. Callers word the outcome.
+  module NoteDelivery
+    # The outcome for one session.
+    # @!attribute status [Symbol] :queued (a worker runs it), :waits (no
+    #   worker: it waits for the next start) or :refused (a chi REPL owns it)
+    # @!attribute queued [Integer] notes waiting in its notes/ folder
+    #   (:waits only; 0 otherwise)
+    Result = Data.define(:id, :status, :queued) do
+      def delivered? = status != :refused
+    end
+
+    module_function
+
+    # @param id [String] a full session id (resolved by the caller)
+    # @return [Result]
+    # @raise [SessionInbox::NoteRejected] an empty note or one over 16 KiB
+    def deliver(id, text:, source:, state_dir:, from_session: nil, from_cwd: nil)
+      owner = SessionManager.session_owner(id, state_dir: state_dir)
+      return Result.new(id: id, status: :refused, queued: 0) if owner&.tui?
+
+      path = SessionInbox.write_note(id, text: text, source: source, from_session: from_session, from_cwd: from_cwd,
+                                         state_dir: state_dir)
+      return Result.new(id: id, status: :queued, queued: 0) if owner
+
+      Result.new(id: id, status: :waits, queued: SessionInbox.find_new_note_files(File.dirname(path, 2)).size)
+    end
+  end
+end