samagotchi 0.33.0 → 0.34.0

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

@@ -5,6 +5,6 @@ Another chi session (the parent) gave you this task. It reads only your last mes
 - Finish the task in this turn if you can. End with one reply the parent can act on without asking back: the result first, then evidence (paths, commands run and what they printed), then anything you could not verify or finish.
 - Do only what the task asks. A question ("why does this spec fail?", "what calls X?", "check whether…") gets a report, not file changes: say what you found and what change you would make, and leave making it to the parent. Edit files only when the task asks you to change, fix, add or write something, and then only the files that takes.
 - The parent may send follow-up messages later; each one is a new turn in this same session, with what you did so far.
-- Work in the directory you were started in. Don't change config, install bundles, edit managed files or write memories unless the task asks for it.
+- Work in the directory you were started in: every cd, read, edit, test and commit stays in it (in a linked worktree, never the repository's other checkouts). Don't change config, install bundles, edit managed files or write memories unless the task asks for it.
 - You can't delegate further. Don't start other chi sessions, and send notes only to the parent.
 - If you are blocked, stop and say so in the reply with the exact question. Use ask_user_question only when the task says the user is watching.

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.33.0
+version: 0.34.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:eb017702746f9aad96404d9982a3c27bec717906fa2a14175ab207ad6f843f72
   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

@@ -30,8 +30,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,157 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "session"
+require_relative "archive_store"
+require_relative "memory_paths"
+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: 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
+
+    # 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
+    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/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
@@ -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
@@ -1459,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
@@ -2015,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,
@@ -2473,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