samagotchi 0.32.0 → 0.34.0

data/lib/samagotchi/context_fetch.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require_relative "context_sources"
 require_relative "context_providers"
 require_relative "log"
+require_relative "process_group"
 
 module Samagotchi
   # Runs an attached context source's command once and records the result
@@ -117,47 +118,26 @@ module Samagotchi
 
       out_r, out_w = IO.pipe
       err_r, err_w = IO.pipe
-      pid = Process.spawn(env, "sh", "-c", cmd, chdir: cwd, pgroup: true, in: File::NULL, out: out_w, err: err_w)
+      pid = ProcessGroup.spawn(env, "sh", "-c", cmd, chdir: cwd, in: File::NULL, out: out_w, err: err_w)
       out_w.close
       err_w.close
-      output = +""
-      over = false
-      out_reader = Thread.new do
-        loop do
-          chunk = out_r.readpartial(READ_CHUNK)
-          if output.bytesize + chunk.bytesize > ContextSources::TEXT_MAX_BYTES
-            over = true
-            break
-          end
-          output << chunk
-        end
-      rescue IOError # EOFError too
-        nil
-      end
-      stderr = +""
-      err_reader = Thread.new do
-        loop do
-          stderr << err_r.readpartial(READ_CHUNK)
-          stderr = stderr.byteslice(-STDERR_TAIL_BYTES, STDERR_TAIL_BYTES) if stderr.bytesize > STDERR_TAIL_BYTES
-        end
-      rescue IOError # EOFError too
-        nil
-      end
+      out_reader = ProcessGroup::PipeReader.new(out_r, cap: ContextSources::TEXT_MAX_BYTES, chunk: READ_CHUNK)
+      err_reader = ProcessGroup::PipeReader.new(err_r, cap: STDERR_TAIL_BYTES, keep: :tail, chunk: READ_CHUNK)
 
-      error, status = wait(pid, timeout: timeout, over: -> { over }, cancelled: cancelled)
+      error, status = wait(pid, timeout: timeout, over: -> { out_reader.over? }, cancelled: cancelled)
       reaped = true
       # Whatever the command left running in its group goes with it.
-      signal_group(pid, "KILL")
-      [out_reader, err_reader].each { |thread| thread.join(KILL_GRACE_SECONDS) || thread.kill }
-      stderr_text = stderr.dup.force_encoding(Encoding::UTF_8).scrub
+      ProcessGroup.signal(pid, "KILL")
+      [out_reader, err_reader].each { |reader| reader.wait(KILL_GRACE_SECONDS) || reader.kill }
+      stderr_text = err_reader.text(Encoding::UTF_8).scrub
       Log.debug(:context, "stderr", text: stderr_text[-1000..] || stderr_text) unless stderr_text.strip.empty?
       return Run.new(output: nil, error: nil, stderr: stderr_text, cancelled: true) if error == :cancelled
 
       # Checked again once the reader is done: a command that exits before
       # wait's next tick never gets an over from it.
-      error = OVER_CAP if over
+      error = OVER_CAP if out_reader.over?
       error ||= exit_error(status, stderr_text)
-      Run.new(output: output, error: error, stderr: stderr_text, cancelled: false)
+      Run.new(output: out_reader.text, error: error, stderr: stderr_text, cancelled: false)
     rescue SystemCallError => e
       Run.new(output: nil, error: "couldn't run it: #{e.message}", stderr: "", cancelled: false)
     ensure
@@ -188,33 +168,22 @@ module Samagotchi
 
     def abandon(pid, readers)
       stop_group(pid)
-      readers.each { |thread| thread&.kill }
+      readers.each { |reader| reader&.kill }
     rescue StandardError => e
       Log.warn(:context, "stop_failed", pid: pid, error: e.class.name)
     end
 
     # TERM, then KILL after a grace; @return [Process::Status, nil]
     def stop_group(pid)
-      signal_group(pid, "TERM")
-      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + KILL_GRACE_SECONDS
-      until Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
-        _, status = Process.wait2(pid, Process::WNOHANG)
-        return status if status
+      status = nil
+      reaped = -> { status = Process.wait2(pid, Process::WNOHANG)&.last }
+      return status if ProcessGroup.stop(pid, grace: KILL_GRACE_SECONDS, poll: 0.05, stopped: reaped)
 
-        sleep(0.05)
-      end
-      signal_group(pid, "KILL")
       Process.wait2(pid).last
     rescue Errno::ECHILD
       nil
     end
 
-    def signal_group(pid, signal)
-      Process.kill(signal, -pid)
-    rescue Errno::ESRCH, Errno::EPERM
-      nil
-    end
-
     def exit_error(status, stderr)
       return nil if status.nil? || status.success?
 

data/lib/samagotchi/context_sources.rb

@@ -67,26 +67,35 @@ module Samagotchi
     # +serial+ counts the revisions (an absorb that missed some says how
     # many); +error+ is the last failure, +error_since+ when the failures
     # began (cleared by a success), so a session hears about each run of
-    # failures once. +summary+, +wake+ and +hint+ come with the revision.
+    # failures once. +summary+, +wake+ and +hint+ come with the revision;
+    # +wake_serial+ is the serial of the newest revision that asked to wake
+    # (nil: none), so a change that doesn't ask, recorded before an absorb,
+    # doesn't hide a wake asked since the session's last one.
     # +fetched_at+ is the last success, +checked_at+ the last try (the
     # poller's clock: a failing source isn't run again every tick).
-    Snapshot = Data.define(:text, :summary, :revision, :serial, :fetched_at, :checked_at, :wake, :hint, :error,
-                           :error_since) do
+    Snapshot = Data.define(:text, :summary, :revision, :serial, :fetched_at, :checked_at, :wake, :wake_serial, :hint,
+                           :error, :error_since) do
       def self.empty
-        new(text: nil, summary: nil, revision: nil, serial: 0, fetched_at: nil, checked_at: nil, wake: false, hint: nil,
-            error: nil, error_since: nil)
+        new(text: nil, summary: nil, revision: nil, serial: 0, fetched_at: nil, checked_at: nil, wake: false,
+            wake_serial: nil, hint: nil, error: nil, error_since: nil)
       end
 
       def to_h
         { "text" => text, "summary" => summary, "revision" => revision, "serial" => serial,
-          "fetched_at" => fetched_at, "checked_at" => checked_at, "wake" => (wake ? true : nil), "hint" => hint,
+          "fetched_at" => fetched_at, "checked_at" => checked_at, "wake" => (wake ? true : nil),
+          "wake_serial" => wake_serial, "hint" => hint,
           "error" => error, "error_since" => error_since }.compact
       end
 
+      # A snapshot 0.32.0 wrote has no wake_serial: its wake is the latest
+      # revision's.
       def self.from_h(data)
-        new(text: data["text"], summary: data["summary"], revision: data["revision"], serial: data["serial"].to_i,
-            fetched_at: data["fetched_at"], checked_at: data["checked_at"] || data["fetched_at"],
-            wake: data["wake"] == true, hint: data["hint"], error: data["error"], error_since: data["error_since"])
+        serial = data["serial"].to_i
+        wake = data["wake"] == true
+        new(text: data["text"], summary: data["summary"], revision: data["revision"], serial: serial,
+            fetched_at: data["fetched_at"], checked_at: data["checked_at"] || data["fetched_at"], wake: wake,
+            wake_serial: data["wake_serial"]&.to_i || (serial if wake), hint: data["hint"], error: data["error"],
+            error_since: data["error_since"])
       end
 
       def text? = !text.nil?
@@ -230,7 +239,8 @@ module Samagotchi
                   else
                     Snapshot.new(text: fetched.text, revision: revision, serial: previous.serial + 1, fetched_at: stamp,
                                  checked_at: stamp, summary: fetched.summary || ContextSources.plain_summary(previous.text, fetched.text),
-                                 wake: fetched.wake, hint: fetched.hint || previous.hint, error: nil, error_since: nil)
+                                 wake: fetched.wake, wake_serial: fetched.wake ? previous.serial + 1 : previous.wake_serial,
+                                 hint: fetched.hint || previous.hint, error: nil, error_since: nil)
                   end
         write_snapshot(name, written)
       end

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

@@ -6,6 +6,7 @@ require "securerandom"
 require "time"
 require "yaml"
 
+require_relative "client_id"
 require_relative "iteration_limit"
 require_relative "config"
 require_relative "context_note"
@@ -48,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"
@@ -108,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
@@ -342,68 +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.
-    # 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
@@ -430,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
@@ -811,6 +757,7 @@ module Samagotchi
       # #stop_idle's work (the scheduler's stop is idempotent), where the
       # callers haven't stopped it already.
       @idle_scheduler&.stop
+      @prompt_warmup.stop
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + join_timeout
       threads.each do |thread|
         next if thread == Thread.current
@@ -1183,17 +1130,18 @@ module Samagotchi
     private :hook_messages
 
     # How the turn ended, on the session (Session#last_turn): the caller's
-    # save puts it in the file the session hub watches.
+    # save puts it in the file the session hub watches. Public for the
+    # Worker's turn that failed before it began (no #end_turn ran).
     # @param limit [Integer, nil] the turn ran out of iterations at this
     #   limit: "exhausted" => true, "limit" => N, so a wait with nobody to
     #   answer the continue offer says so (ReplyWait, ParentReport "limit")
     # @param event [Hash] the turn's end event (#stop_facts)
     def record_last_turn(session, outcome, seconds, origin, event, limit: nil)
       client_id = origin.is_a?(Hash) ? origin[:client_id].to_s : ""
-      source = if client_id.start_with?("#{Tools::Delegate::CLIENT_PREFIX}:") then "delegate"
-               elsif client_id.start_with?(ChildReports::CLIENT_PREFIX) then "delegate_report"
-               elsif client_id.start_with?(Steer::CONTEXT_CLIENT_PREFIX) then "context"
-               elsif client_id == SessionManager::REMINDER_CLIENT_ID then "reminder"
+      source = if client_id.start_with?(ClientId::DELEGATE_PREFIX) then "delegate"
+               elsif client_id.start_with?(ClientId::CHILD_PREFIX) then "delegate_report"
+               elsif client_id.start_with?(ClientId::CONTEXT_PREFIX) then "context"
+               elsif client_id == ClientId::REMINDER then "reminder"
                else "client"
                end
       session.last_turn = { "outcome" => outcome, "ended_at" => Time.now.iso8601(3),
@@ -1201,7 +1149,6 @@ module Samagotchi
       session.last_turn.merge!("exhausted" => true, "limit" => limit) if limit
       session.last_turn.merge!(stop_facts(event))
     end
-    private :record_last_turn
 
     # Why a turn stopped, from its end event, for a parent agent's wait
     # (ReplyWait): a provider error's kind and whether a retry may help, a
@@ -1456,28 +1403,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
@@ -2012,8 +1937,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,
@@ -2470,21 +2394,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/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

data/lib/samagotchi/guardrails/child_boundary.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "outside"
+require_relative "protected_paths"
+require_relative "shell_lex"
+require_relative "shell_paths"
+require_relative "shared_git"
+
+module Samagotchi
+  module Guardrails
+    # A delegate child asks before it changes anything outside its folder
+    # (+root+: the work tree top of its working_directory, never Dir.pwd,
+    # so a child whose worktree is gone still has one). A core check, on in
+    # every guardrails mode and with guardrails.enabled: false, for delegate
+    # sessions only (GuardrailWiring#checks), so ordinary sessions and a
+    # parent's own flows never get it. It asks, once or for the session
+    # (a repo or rule answer would hold in every worktree, for every child),
+    # when:
+    #   write, edit: a path is outside root (Outside: tmp dirs and memory
+    #     files never are);
+    #   execute, task_create: mutating git runs in a dir outside root
+    #     (ShellGitDirs), or a command that isn't read-only starts outside
+    #     root (its cwd:, else Dir.pwd) or names a path in the repository's
+    #     other checkouts (the main one and sibling worktrees) or its
+    #     common git dir; or it runs git that changes what all checkouts
+    #     share, from anywhere (SharedGit: config, update-ref, worktree add,
+    #     stash clear, tags, another branch's delete).
+    # Paths elsewhere in a command (/usr/bin, ~/.gem) don't count, and
+    # read-only commands never ask. Text heuristics: sh -c bodies, scripts
+    # and $(…) aren't looked into.
+    class ChildBoundary
+      RULE = "child-boundary"
+      SOURCE = "core"
+      SCOPES = %w[once session].freeze
+      SHELL_TOOLS = %w[execute task_create].freeze
+
+      # @param root [#call] → String, nil: the child's folder (nil: no check)
+      # @param worktrees [#call] → Array<String>: every checkout of root's
+      #   repository (GitInfo#worktrees); root's own is left out here
+      # @param common_dir [#call] → String, nil: root's common git dir (in
+      #   a bare layout it is in no checkout)
+      # @param branch [#call] → String, nil: the branch checked out in root
+      def initialize(root:, worktrees: -> { [] }, common_dir: -> {}, branch: -> {})
+        @root = root
+        @worktrees = worktrees
+        @common_dir = common_dir
+        @branch = branch
+      end
+
+      # Vote on +verdict+ (its targets).
+      def check(verdict)
+        targets = verdict.targets
+        root = targets && @root.call
+        return verdict unless root && !root.to_s.empty?
+
+        crossing = crosses?(targets, root) or return verdict
+
+        what = crossing == :shared ? "git state every checkout of the repository shares, from its folder" : "something outside its folder"
+        verdict.ask!("a delegate child changes #{what} #{root}: ask the user",
+                     scopes: SCOPES, rule: RULE, source: SOURCE, decided_by: "core")
+      end
+
+      private
+
+      def crosses?(targets, root)
+        case targets.tool
+        when "write", "edit" then targets.paths.any? { |path| Outside.outside?(path, root: root) }
+        when *SHELL_TOOLS then shell_crosses?(targets, root)
+        else false
+        end
+      end
+
+      def shell_crosses?(targets, root)
+        return true if targets.git_dirs.any? { |dir| dir.is_a?(String) && Outside.outside?(dir, root: root) }
+        return :shared if SharedGit.changes?(targets.command, own_branch: @branch.call)
+        return false if targets.read_only?
+        return true if targets.cwd && Outside.outside?(targets.cwd, root: root)
+
+        names_other_checkout?(targets.command, targets.cwd, root)
+      end
+
+      # Whether a word of +command+ resolves into another checkout of the
+      # repository (and not into root, which may sit inside the main one).
+      def names_other_checkout?(command, cwd, root)
+        real_root = ProtectedPaths.real(root)
+        others = [*@worktrees.call, @common_dir.call].compact.map { |dir| ProtectedPaths.real(dir) } - [real_root]
+        return false if others.empty?
+
+        walk = ShellPaths::Walk.new(cwd, Dir.home, ENV)
+        ShellLex.simple_commands(ShellLex.lex(command.to_s)).any? do |words|
+          walk.step(words).any? do |_word, path|
+            next false unless path
+
+            real = ProtectedPaths.real(path)
+            !ShellPaths.within?(real, real_root) && others.any? { |dir| ShellPaths.within?(real, dir) }
+          end
+        end
+      rescue ArgumentError, EncodingError
+        false
+      end
+    end
+  end
+end