samagotchi 0.33.0 → 0.35.0

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.33.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:8b05db6989662e4409b34d73ce4368588c874501e6e917e6dee70dfb1e3f5157
+  self_map.md: sha256:37063eb74fdcb4cde748f17193ff23f832723eb38f81aff086f48f410ce7497b
   config_modification_protocol.md: sha256:ec0b0c7023dbf03b93879e51cd5cdc38b22d43a2e5984ee11e8542ace077c3be
-  memory_guide.md: sha256:17126f5adb9ef7b33c40e920ef339388c8c8c045b38a7de825b08760604db4e4
-  delegated.md: sha256:eaaf66830d3ab1346c75812a5fc8fcb9d3dbaa6a3f6bcf47c103155d96e415b5
+  memory_guide.md: sha256:63d5d7f7d704e6ce7e28dd99e532b714c1b9f7acf548092404248d8ca5385b80
+  delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

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

@@ -15,7 +15,7 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 | `system` | `$XDG_CONFIG_HOME/samagotchi/memories/`, default `~/.config/samagotchi/memories/` (`MemoryPaths.system_dir`) | User-wide preferences, identity, cross-project knowledge |
 | `project` | `<system dir>/projects/<basename>_<hash>/` (`MemoryPaths.project_dir`: `basename(root)` + 8-char `MD5(root)`, root = `MemoryPaths.project_root`) | Repo-specific conventions, workflow, stack decisions |
 
-- The project root is the git repository: its common git dir, which every linked worktree shares. All worktrees and subdirectories of one repository share one project folder; the system prompt shows the resolved root and folder. Outside a repository the root is the working directory. A separate clone is a different project.
+- The project root is the git repository: its common git dir, which every linked worktree shares. All worktrees and subdirectories of one repository share one project folder; the system prompt shows that folder (not the root: in a linked worktree, work stays in the worktree). Outside a repository the root is the working directory. A separate clone is a different project.
 - `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`; a memory a bundle installed adds `· from <bundle>` before the description. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write` (and refreshed when `write`/`edit` change a memory's file).
 
 ## Tools you have

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
@@ -30,8 +34,10 @@
   `chi send --new --wait -m TEXT` starts a session the user can watch in the web and prints its
   answer (exit 3: it waits for the user's answer); see "Starting a session".
 - `delegate` hands a task to a child session that runs in parallel and returns only its final
-  reply (`delegate_result` waits for it; with `wait: false` chi brings the reply to me by itself
-  as a delegate report when the child ends its turn; `session:` sends a follow-up to a child). A child is a
+  reply (`wait: false` is the usual way: I end my turn or keep talking with my user, and chi
+  brings the reply to me by itself as a delegate report when the child ends its turn, starting a
+  turn for it if I'm idle; `delegate_result` only when this turn can't go on without the reply;
+  `session:` sends a follow-up to a child). A child is a
   normal session: it shows in `chi sessions list` with `↳ <parent>`, and the user can steer it
   with `chi --attach <id>`. While I wait for a child, its tool approvals go to my user as my own
   approvals (I see only how each was answered); see `docs/sessions.md` "Delegating".

data/lib/samagotchi/children_status.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "session"
+require_relative "archive_store"
+require_relative "git_head"
+require_relative "reply_wait"
+require_relative "tools/delegate"
+require_relative "tools/delegate_cursor"
+
+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__)
+
+  # A parent's children as `/children` and the glance views show them: one
+  # Child per child session, read from the files layer 1 already writes
+  # (the session JSON, its output/ replies, the parent's delegates.json).
+  # Nothing here runs git or a subprocess.
+  module ChildrenStatus
+    # One child of a session.
+    # @!attribute state [String] waiting, running, failed, stopped, done or
+    #   idle (STATES, in the order they are decided)
+    # @!attribute waiting [String, nil] what it waits for: question,
+    #   approval, hook or continue
+    # @!attribute delegate [Boolean] a `delegate` child; false for a fork
+    # @!attribute branch [String, nil] the branch checked out in its folder
+    #   (a short sha when detached); nil outside git
+    # @!attribute last_reply [String, nil] the first line of its newest reply
+    # @!attribute reported [Boolean] the parent was already given that reply
+    #   (a delegate report or a wait); false when there is none
+    Child = Data.define(:id, :short_id, :title, :state, :waiting, :live, :delegate, :cwd, :branch,
+                        :last_reply, :last_reply_at, :reported, :updated_at, :archived)
+
+    # The glance views' numbers: children running, waiting for an answer,
+    # and with a reply the parent wasn't given yet.
+    Counts = Data.define(:running, :waiting, :unreported) do
+      def self.none = new(running: 0, waiting: 0, unreported: 0)
+    end
+
+    STATES = %w[waiting running failed stopped done idle].freeze
+
+    module_function
+
+    # Every child of +parent_id+, newest first: delegates and forks (a fork
+    # is delegate: false), archived ones only with +include_archived+. Scans
+    # every session (SessionManager.children_of): for on-demand use.
+    # @return [Array<Child>]
+    def of(parent_id, state_dir:, include_archived: false)
+      cursors = Tools::DelegateCursors.read(parent_id, state_dir: state_dir)
+      SessionManager.children_of(parent_id, state_dir: state_dir).filter_map do |row|
+        next if row[:archived] && !include_archived
+
+        session = load(row[:id], state_dir: state_dir)
+        session && child(session, row, cursors, state_dir: state_dir)
+      end
+    end
+
+    # The cheap path for the glance views: only the children in the
+    # parent's delegates.json (one Session.load and an owner check each, no
+    # scan). Its keys can also name a fork the model passed to delegate
+    # session: or a deleted child: only live delegates of this parent count,
+    # archived ones don't.
+    # @return [Counts]
+    def counts(parent_id, state_dir:)
+      cursors = Tools::DelegateCursors.read(parent_id, state_dir: state_dir)
+      children = cursors.keys.filter_map do |id|
+        session = load(id, state_dir: state_dir)
+        next unless session&.delegate? && session.parent_id == parent_id
+        next if ArchiveStore.archived?(Session.session_dir(id, state_dir: state_dir))
+
+        child(session, summary_of(session, state_dir: state_dir), cursors, state_dir: state_dir)
+      end
+      Counts.new(running: children.count { |c| c.state == "running" },
+                 waiting: children.count { |c| c.state == "waiting" },
+                 unreported: children.count { |c| c.last_reply && !c.reported })
+    end
+
+    # @param row [Hash] a children_of row, or summary_of's keys
+    # @param cursors [Hash] the parent's delegates.json
+    def child(session, row, cursors, state_dir:)
+      reply = ReplyWait.newest_reply(session.id, state_dir: state_dir)
+      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: 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])
+    end
+    private_class_method :child
+
+    def state_of(session, row, reply)
+      return "waiting" if row[:waiting]
+      return "running" if Tools::Delegate.running?(row)
+      return "stopped" if session.status == Session::STATUS_STOPPED
+
+      outcome = session.last_turn.is_a?(Hash) ? session.last_turn["outcome"] : nil
+      return "failed" if session.status == Session::STATUS_ERROR || outcome == "failed"
+      return "done" if outcome == "completed" && reply
+
+      "idle"
+    end
+    private_class_method :state_of
+
+    # The keys of a children_of row that state_of and child read, for a
+    # session counts loaded itself.
+    def summary_of(session, state_dir:)
+      live = SessionManager.worker_live?(session.id, state_dir: state_dir)
+      { live: live, busy: live && session.status == Session::STATUS_RUNNING, status: session.status,
+        updated_at: session.updated_at, waiting: session.waiting_question(live: live)&.dig(:kind),
+        preview: session.last_prompt.to_s }
+    end
+    private_class_method :summary_of
+
+    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
+    rescue SystemCallError
+      nil
+    end
+    private_class_method :first_line
+
+    # Reply files are named by the local time they were written
+    # (SessionInbox.write_output, %Y%m%d%H%M%S then nanoseconds).
+    # @return [Time, nil] nil for a name that isn't one
+    def reply_time(file)
+      Time.strptime(File.basename(file, ".txt")[0, 14], "%Y%m%d%H%M%S")
+    rescue ArgumentError, TypeError
+      nil
+    end
+    private_class_method :reply_time
+
+    def load(id, state_dir:)
+      return nil unless Session.exist?(id, state_dir: state_dir)
+
+      Session.load(id, state_dir: state_dir)
+    rescue ArgumentError
+      nil
+    end
+    private_class_method :load
+  end
+end

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/cut_policy.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "turn_note"
+
+module Samagotchi
+  # What a turn does after a generation was cut (stop_generation: a
+  # plugin's cut, or Engine#cut_for_steer's), shared by the native loop
+  # (KernelLoop) and the chat loop (ChatLoop::Run); each maps the outcome to
+  # its own ending.
+  #
+  # A generation a plugin cut is an empty answer made early. Queued input
+  # (a user's line, a plugin's steer) goes in first, with or without a
+  # retry left, and spends no attempt: the model answers it. A steer's cut
+  # with nothing queued (its message was taken at a boundary already) is
+  # asked again as is. Else it is asked again with its own nudge while the
+  # retry budget lasts, else the turn ends as cancelled (hook), with
+  # nothing salvaged and without the spent nudge. A Stop that came right
+  # after the cut is a plain cancel.
+  module CutPolicy
+    # :stopped (a Stop after the cut), :again (the turn goes on) or :hook
+    # (the turn ends as cancelled by the cut's bundle).
+    Outcome = Data.define(:kind) do
+      def stopped? = kind == :stopped
+      def again? = kind == :again
+      def hook? = kind == :hook
+    end
+
+    STOPPED = Outcome.new(kind: :stopped)
+    AGAIN = Outcome.new(kind: :again)
+    HOOK = Outcome.new(kind: :hook)
+
+    module_function
+
+    # +cut+: the cut's detail (the stop_generation payload). +emit+ takes an
+    # event Hash; +inject+ puts queued input in (true when there was any).
+    # +finish_reason+ and +thinking_chars+: the cut generation's, for the
+    # retry's row.
+    # On :hook the turn controller is cancelled (:hook, +cut+) already.
+    def decide(cut:, cancel_controller:, empty_retry:, conversation:, iteration:, emit:, inject:, finish_reason:,
+               thinking_chars:)
+      return STOPPED if cancel_controller.cancelled?
+
+      # The row under the cut step, above the message it was cut for.
+      emit.call({ type: :steer_cut, iteration: iteration, source: cut[:source].to_s }) if cut[:steer]
+      return AGAIN if inject.call || cut[:steer]
+
+      if empty_retry.left?
+        empty_retry.nudge!(conversation, TurnNote.cut_retry(cut[:by], cut[:reason]),
+                           emit: emit, iteration: iteration, finish_reason: finish_reason,
+                           thinking_chars: thinking_chars, stopped_by: cut[:by])
+        return AGAIN
+      end
+      empty_retry.drop_nudge!(conversation)
+      cancel_controller.cancel!(:hook, cut)
+      HOOK
+    end
+  end
+end

data/lib/samagotchi/engine.rb

@@ -49,8 +49,8 @@ require_relative "tools/memory"
 require_relative "muted_memories"
 require_relative "used_memories"
 require_relative "turn_state"
-require_relative "generation_phase"
-require_relative "waiting_steer"
+require_relative "steer_cut"
+require_relative "engine_peers"
 require_relative "bundle_needs"
 require_relative "model_overlay"
 require_relative "served_model"
@@ -109,10 +109,8 @@ module Samagotchi
       # steers) and the idle layer's activity clock. Built first: a plugin
       # may steer or ask whether a turn runs while it loads.
       @turn_state = TurnState.new(clock: -> { monotonic_now })
-      # What the running generation streams: whether a steer may cut it.
-      @generation_phase = GenerationPhase.new(clock: -> { monotonic_now })
-      # A message that may cut it but came too early: it cuts later.
-      @waiting_steer = WaitingSteer.new
+      # A message for the running turn cutting its generation.
+      @steer_cut = SteerCut.new(clock: -> { monotonic_now }, controller: -> { active_cancel_controller })
       @scratch = scratch
       @no_interrupt = no_interrupt
       @chat_backend = nil
@@ -205,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
@@ -343,69 +341,15 @@ module Samagotchi
       @turn_state.steer(text, source: source)
     end
 
-    # A message for the running turn from +source+ (Steer.source_for_client:
-    # nil for the user, "chi_send", "parent_agent") cuts the streaming
-    # generation when it has streamed only thinking for steer.cut_after
-    # seconds (GenerationPhase): the loops' cut path then starts the step
-    # again with the message, no nudge, no retry spent. Too early, the
-    # message waits (WaitingSteer) and cuts once the thinking passes it
-    # (#recheck_waiting_steer, on each thinking chunk), unless a boundary
-    # hands it to the model first. A plugin's message never cuts, nor an
-    # unknown client's (automatic:<id>).
-    # Call it after the message is queued, with the #input_epoch read
-    # before queueing it. Outside any lock; a cut that lands just after the
-    # generation ended is harmless (the loop re-asks).
+    # A message for the running turn from +source+ cuts the generation
+    # streaming only thinking (SteerCut#cut_for_steer). Call it after the
+    # message is queued, with the #input_epoch read before queueing it.
     # @return [Boolean] whether a generation was cut now
-    def cut_for_steer(source, epoch: nil)
-      return false unless Steer.cuts?(source)
+    def cut_for_steer(source, epoch: nil) = @steer_cut.cut_for_steer(source, epoch: epoch)
 
-      after = Config.get("steer.cut_after").to_i
-      return false unless after.positive?
-
-      ctrl = active_cancel_controller
-      return false unless ctrl
-      return steer_cut!(ctrl, source.to_s) if @generation_phase.cuttable?(after)
-
-      Log.info(:turn, "steer_cut_waits", source: source.to_s) if @waiting_steer.wait!(source, epoch: epoch)
-      false
-    rescue StandardError
-      false
-    end
-
-    # The drains that took input so far (WaitingSteer#epoch): read it before
-    # queueing a message for #cut_for_steer.
-    def input_epoch
-      @waiting_steer.epoch
-    end
-
-    # A thinking chunk streamed: a waiting message cuts once the thinking
-    # passes steer.cut_after.
-    def recheck_waiting_steer
-      return unless @waiting_steer.waiting?
-
-      after = Config.get("steer.cut_after").to_i
-      return unless after.positive? && @generation_phase.cuttable?(after)
-
-      source = @waiting_steer.take
-      ctrl = active_cancel_controller
-      steer_cut!(ctrl, source, waited: true) if source && ctrl
-    rescue StandardError
-      nil
-    end
-    private :recheck_waiting_steer
-
-    def steer_cut!(ctrl, source, waited: false)
-      age = @generation_phase.age
-      cut = ctrl.cancel_generation!(:steer, { by: "steer", steer: true, source: source, reason: "a new message" })
-      if cut
-        @waiting_steer.clear!
-        fields = { source: source, age: age&.round(1) }
-        fields[:waited] = true if waited
-        Log.info(:turn, "steer_cut", **fields)
-      end
-      cut
-    end
-    private :steer_cut!
+    # The drains that took input so far: read it before queueing a message
+    # for #cut_for_steer.
+    def input_epoch = @steer_cut.input_epoch
 
     # Like #steer, for the turn that begins next (a continue turn answered
     # with a text): it joins that turn at its first boundary. Callable from
@@ -432,7 +376,7 @@ module Samagotchi
       lambda do |at_answer: false|
         lines = pending_input ? Array(pending_input.call) : []
         # The input went to the model: a message that waited to cut is in.
-        @waiting_steer.delivered! unless lines.empty?
+        @steer_cut.delivered! unless lines.empty?
         lines + take_steers(at_answer)
       end
     end
@@ -1279,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)) },
@@ -1295,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
@@ -1319,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)
@@ -1459,28 +1427,6 @@ module Samagotchi
     # @return [Session] current session (Engine owns create/resume)
     attr_reader :session
 
-    # The kernel's Tools::Peers, following the current session. cancelled?
-    # is the running turn's cancel, for a tool that waits (delegate_result):
-    # the controller is set from another thread and a tool gets no other
-    # way to see it.
-    PeerView = Struct.new(:engine) do
-      def session_id = engine.session&.id
-      def cwd = engine.session&.working_directory
-      def project_root = engine.session&.project_root
-      def state_dir = engine.peer_state_dir
-      def cancelled? = !!engine.active_cancel_controller&.cancelled?
-      def relay = engine.relay_peer
-      def model_ref = engine.effective_model_ref
-    end
-
-    # What the approval relay needs from the parent's Engine (Peers#relay):
-    # its own question flow, which every UI attached to it answers.
-    RelayPeer = Struct.new(:engine) do
-      def open_question(fields, watch: nil) = engine.open_question(fields, watch: watch)
-      def interface = engine.interface
-      def relay_desk = engine.relay_desk
-    end
-
     # This worker's relays of its delegates' approvals (memory only).
     # @return [RelayDesk]
     attr_reader :relay_desk
@@ -2015,8 +1961,7 @@ module Samagotchi
       # shared inactivity clock so the idle recap detector (shared with the REPL)
       # treats the just-finished turn as activity and re-arms its window.
       left = @turn_state.finish!
-      @generation_phase.finished!
-      @waiting_steer.clear!
+      @steer_cut.finished!
       Client.swap_probe_cancel(probe_cancel_before)
       # The next turn's window and served model are asked again: the cache
       # (this host's, process-wide) is dropped here, at the turn's end,
@@ -2364,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)
         },
@@ -2473,21 +2418,13 @@ module Samagotchi
     def build_stream_event_handler(on_event, cancel_controller: nil)
       watch = stream_watch(cancel_controller)
       proc do |event|
-        progress = nil
+        progress = SteerCut.lanes(event) if event[:type] == :generation_chunk
+        @steer_cut.observe(event, progress)
         case event[:type]
         when :generation_started
-          @generation_phase.started!
           @generation_thought = nil
           watch&.started(event[:iteration])
-        when :generation_chunk
-          # A chunk without the lanes (no loop of ours sends one) counts as text.
-          text = event.key?(:text) ? event[:text] : event[:content]
-          progress = { thinking: event[:thinking].to_s, text: text.to_s }
-          @generation_phase.chunk!(**progress, tool_call: event[:tool_call])
-          recheck_waiting_steer unless progress[:thinking].empty?
-          note_generation_thought(progress[:thinking])
-        when :generation_retrying then @generation_phase.retrying!
-        when :generation_completed, :generation_cancelled then @generation_phase.finished!
+        when :generation_chunk then note_generation_thought(progress[:thinking])
         end
         # The chat loop asked again without the thinking fields: a notice,
         # not an event of its own.

data/lib/samagotchi/engine_peers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The views of an Engine its peers get: the kernel's tools
+  # (Engine#initialize sets @kernel.peers) and a delegate's approval relay
+  # (Engine#relay_peer).
+  class Engine
+    # The kernel's Tools::Peers, following the current session. cancelled?
+    # is the running turn's cancel, for a tool that waits (delegate_result):
+    # the controller is set from another thread and a tool gets no other
+    # way to see it.
+    PeerView = Struct.new(:engine) do
+      def session_id = engine.session&.id
+      def cwd = engine.session&.working_directory
+      def project_root = engine.session&.project_root
+      def state_dir = engine.peer_state_dir
+      def cancelled? = !!engine.active_cancel_controller&.cancelled?
+      def relay = engine.relay_peer
+      def model_ref = engine.effective_model_ref
+    end
+
+    # What the approval relay needs from the parent's Engine (Peers#relay):
+    # its own question flow, which every UI attached to it answers.
+    RelayPeer = Struct.new(:engine) do
+      def open_question(fields, watch: nil) = engine.open_question(fields, watch: watch)
+      def interface = engine.interface
+      def relay_desk = engine.relay_desk
+    end
+  end
+end

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/guardrail_wiring.rb

@@ -104,11 +104,26 @@ module Samagotchi
       )
     end
 
-    # The gate's core checks, in order.
+    # The gate's core checks, in order. A delegate child's boundary comes
+    # before the rules, so its ask keeps the child-boundary rule id (and
+    # its once/session scopes) when a strict rule asks too.
     def checks
       rules = self.rules
       [@failures, rules.hook_asks, protected_paths, (@scratch_writes ||= Guardrails::ScratchWrites.new if @scratch),
-       rules].compact
+       child_boundary, rules].compact
+    end
+
+    # The delegate child's boundary (Guardrails::ChildBoundary); nil for
+    # any other session.
+    def child_boundary
+      return nil unless @session_lookup.call&.delegate?
+
+      @child_boundary ||= Guardrails::ChildBoundary.new(
+        root: -> { boundary_root },
+        worktrees: -> { (root = boundary_root) ? @git.worktrees(root) : [] },
+        common_dir: -> { (root = boundary_root) && @git.common_dir(root) },
+        branch: -> { (root = boundary_root) && @git.branch(root) }
+      )
     end
 
     # The YAML rules: config.yml's `guardrails:` section (rules, disable) and
@@ -221,6 +236,16 @@ module Samagotchi
 
     private
 
+    # The work tree top of the session's working_directory (the folder
+    # itself outside a repo, or when it's gone); never Dir.pwd, which is
+    # the waker's cwd for a worker whose folder is gone.
+    def boundary_root
+      dir = @session_lookup.call&.working_directory.to_s
+      return nil if dir.empty?
+
+      @git.root(dir) || File.expand_path(dir)
+    end
+
     # The rules of a bundle that needs a newer chi: the ones last loaded
     # from it, with one notice per bundle version (restart the session to
     # load the new ones). Never loaded (a chi older than the bundle it

data/lib/samagotchi/guardrails/approvals.rb

@@ -26,6 +26,10 @@ module Samagotchi
     class Approvals
       FILE = "approvals.json"
       STORED_SCOPES = %w[session repo rule].freeze
+      # Rules a stored answer allows only for its session: their asks offer
+      # once/session, and a repo entry for the same call (from another
+      # rule) would hold in every worktree, for every child.
+      SESSION_ONLY_RULES = %w[child-boundary].freeze
 
       # @param sessions_dir [String] Session's state dir
       #   ($XDG_STATE_HOME/samagotchi/sessions): the store sits beside it,
@@ -69,7 +73,10 @@ module Samagotchi
         repo = verdict.targets&.repo
         here = ->(e) { e["repo"] ? e["repo"] == repo : e["repo_root"] == place }
         session_id = verdict.context&.session_id
+        session_only = SESSION_ONLY_RULES.include?(verdict.rule.to_s)
         list.find do |e|
+          next false if session_only && e["scope"] != "session"
+
           case e["scope"]
           when "session" then session_id && e["session_id"] == session_id && e["key"] == key
           when "repo" then here.call(e) && e["key"] == key