samagotchi 0.32.0 → 0.34.0

data/lib/samagotchi/process_group.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A command run in a process group of its own, so a stop reaches what it
+  # started too: TERM the group, a grace, then KILL it. Execute, TaskRuntime
+  # and ContextFetch spawn and stop their commands here, each with its own
+  # grace and its own "has it stopped?" check (the leader gone, the pipes
+  # closed, the pid reaped). The mcp bundle's client stops its server here
+  # too (after closing its stdin), so it requires chi >= 0.33.0.
+  module ProcessGroup
+    # A group that is gone, or one that isn't ours to signal.
+    QUIET = [Errno::ESRCH, Errno::EPERM].freeze
+    READ_CHUNK_BYTES = 65_536
+
+    module_function
+
+    # Process.spawn in a new process group, whose id is the pid.
+    # @return [Integer] the pid
+    def spawn(env, *argv, **) = Process.spawn(env, *argv, pgroup: true, **)
+
+    # Sends +sig+ to every process in the group +pgid+.
+    # @param leader [Boolean] when the group can't be signalled, signal the
+    #   process +pgid+ alone (a leader that left its group)
+    # @param quiet [Array<Class>] the errors that mean there is nothing to
+    #   signal; any other is raised
+    # @return [Boolean] whether a signal was sent
+    def signal(pgid, sig, leader: false, quiet: QUIET)
+      check!(pgid)
+      Process.kill(sig, -pgid)
+      true
+    rescue *quiet
+      return false unless leader
+
+      begin
+        Process.kill(sig, pgid)
+        true
+      rescue *quiet
+        false
+      end
+    end
+
+    # A pid chi may signal or ask about: an Integer above 1. kill(0) and
+    # kill(-1) reach chi's own group and every process of the user, so a
+    # pid that isn't one (a broken or edited record) never gets that far.
+    def signalable?(pid) = pid.is_a?(Integer) && pid > 1
+
+    # @raise [ArgumentError] unless #signalable?
+    def check!(pid)
+      raise ArgumentError, "not a process group chi may signal: #{pid.inspect}" unless signalable?(pid)
+    end
+
+    # Whether +pid+ runs and leads its own group, as #spawn's process does
+    # (not, then, a reused pid in some other group).
+    def leader?(pid)
+      signalable?(pid) && Process.getpgid(pid) == pid
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    # Whether +pid+ is still running (or a zombie not reaped yet).
+    # @raise [ArgumentError] unless #signalable?
+    def alive?(pid)
+      check!(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+
+    # TERMs the group, waits up to +grace+ for +stopped+, then KILLs it.
+    # @param stopped [#call] true once it has stopped (default: the leader
+    #   is gone)
+    # @param wait [#call] (seconds) between two checks (default: a sleep)
+    # @param signal_options [Hash] for #signal (leader:, quiet:)
+    # @return [Boolean] true when it stopped within the grace (no KILL sent)
+    # @raise [ArgumentError] unless #signalable?
+    def stop(pgid, grace:, poll:, stopped: -> { !alive?(pgid) }, wait: ->(seconds) { sleep(seconds) }, **signal_options)
+      check!(pgid)
+      signal(pgid, "TERM", **signal_options)
+      deadline = monotonic + grace
+      until (done = stopped.call) || monotonic >= deadline
+        wait.call(poll)
+      end
+      return true if done
+
+      signal(pgid, "KILL", **signal_options)
+      false
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Reads a pipe in chunks on a thread of its own, so the output read so
+    # far survives the pipe being closed under it (or the thread killed).
+    class PipeReader
+      # @param cap [Integer, nil] the most bytes it keeps
+      # @param keep [:head, :tail] past the cap: :head stops reading (and
+      #   #over? is true), :tail keeps the last +cap+ bytes
+      def initialize(io, cap: nil, keep: :head, chunk: READ_CHUNK_BYTES)
+        @io = io
+        @buffer = String.new(encoding: Encoding::BINARY)
+        @over = false
+        @thread = Thread.new do
+          Thread.current.report_on_exception = false
+          loop { break unless take(io.readpartial(chunk), cap, keep) }
+        rescue IOError # EOFError is one
+          nil
+        end
+      end
+
+      def done? = !@thread.alive?
+
+      # Whether a :head reader stopped at its cap.
+      def over? = @over
+
+      # @return [Thread, nil] the thread when it ended within +seconds+
+      def wait(seconds) = @thread.join(seconds)
+
+      def kill = @thread.kill
+
+      # Closes the pipe once the thread had +poll+ to end by itself (a
+      # reader still blocked gets IOError), then ends the thread, killing it
+      # after +grace+. The text is safe to read afterwards.
+      def finish(poll:, grace:)
+        @thread.join(poll) unless done?
+        close_quietly
+        @thread.kill unless @thread.join(grace)
+      end
+
+      # What it read, in +encoding+ (default: the pipe's).
+      def text(encoding = @io.external_encoding || Encoding.default_external)
+        @buffer.dup.force_encoding(encoding)
+      end
+
+      private
+
+      # @return [Boolean] whether to read on
+      def take(chunk, cap, keep)
+        if cap && keep == :head && @buffer.bytesize + chunk.bytesize > cap
+          @over = true
+          return false
+        end
+
+        @buffer << chunk
+        @buffer = @buffer.byteslice(-cap, cap) if cap && keep == :tail && @buffer.bytesize > cap
+        true
+      end
+
+      def close_quietly
+        @io.close unless @io.closed?
+      rescue IOError
+        nil
+      end
+    end
+  end
+end

data/lib/samagotchi/prompt_warmup.rb

@@ -32,6 +32,8 @@ module Samagotchi
     # Seconds #take_pin waits for the busy-slot check (Client#slot_status
     # gives up within 3 s).
     DECIDE_TIMEOUT = 3
+    # Seconds #stop waits for a killed warm-up's thread to end.
+    STOP_JOIN_SECONDS = 1
 
     # Whether cache.warmup allows a warm-up (auto, the default; off, false,
     # no or 0 turn it off; anything else warns once and is auto).
@@ -54,13 +56,16 @@ module Samagotchi
       # The pin (#take_pin forgets it) and the last warm-up's thread.
       @state = nil
       @thread = nil
+      @stopped = false
     end
 
     # Start a warm-up of +prompt+ on +client+ in its own thread.
     # @param slot [Integer, nil] the last request's slot (nil: unpinned, and
     #   nothing to pin the next request to)
-    # @return [Thread]
+    # @return [Thread, nil] nil once #stop ran
     def start(client:, prompt:, model:, slot:, images: [])
+      return nil if @mutex.synchronize { @stopped }
+
       # Whether the warm-up went to its slot (true) or was skipped: the
       # first value pushed is the answer.
       sent = Queue.new
@@ -111,6 +116,20 @@ module Samagotchi
       thread&.alive? || false
     end
 
+    # Ends a warm-up still running and starts none after (Engine#shutdown:
+    # no next turn will use it). Its request is cut, which frees the slot.
+    def stop(timeout = STOP_JOIN_SECONDS)
+      thread = @mutex.synchronize do
+        @stopped = true
+        @state = nil
+        @thread
+      end
+      return unless thread&.alive?
+
+      thread.kill
+      thread.join(timeout)
+    end
+
     # Wait up to +timeout+ seconds for the running warm-up (specs).
     def wait(timeout = nil)
       thread = @mutex.synchronize { @thread }

data/lib/samagotchi/question_desk.rb

@@ -5,6 +5,7 @@ require "monitor"
 require "securerandom"
 require "time"
 
+require_relative "client_id"
 require_relative "log"
 require_relative "tools/ask_user_question"
 require_relative "guardrails/parent_approvals"
@@ -266,7 +267,7 @@ module Samagotchi
       sel = Array(selected).map { |v| v.to_s.strip }.reject(&:empty?)
       fm = freeform.to_s.strip
       fm = nil if fm.empty?
-      parent_agent = client_id.to_s == Guardrails::ParentApprovals::CLIENT_ID if parent_agent.nil?
+      parent_agent = client_id.to_s == ClientId::CLI_ANSWER if parent_agent.nil?
       # Read before the lock (config may touch the disk); this worker's own.
       parent_setting = Guardrails::ParentApprovals.setting if parent_agent
       parent_continue = Guardrails::ParentContinue.allowed? if parent_agent

data/lib/samagotchi/relay_verifier.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "client_id"
 require_relative "session"
 require_relative "bridge_client"
 require_relative "worker_sidecar"
@@ -15,9 +16,6 @@ module Samagotchi
   # answers its own question with that, only when it is about this session
   # and the question pending now, and is answered.
   class RelayVerifier
-    # The client id a relayed answer is recorded with: relay:<parent8>.
-    CLIENT_PREFIX = "relay"
-
     # @param engine [Engine] this (the child's) worker's Engine
     def initialize(engine:, state_dir:, session_id:)
       @engine = engine
@@ -44,7 +42,7 @@ module Samagotchi
     def apply(relay, parent_id:, question_id:, relay_id:)
       answer = relay["answer"].is_a?(Hash) ? relay["answer"] : {}
       parent_agent = relay["by"] != "user"
-      client_id = "#{CLIENT_PREFIX}:#{parent_id[0, 8]}"
+      client_id = "#{ClientId::RELAY_PREFIX}#{parent_id[0, 8]}"
       if answer["dismissed"]
         return not_pending(question_id) unless @engine.cancel_question("dismissed", id: question_id)
 

data/lib/samagotchi/reply_wait.rb

@@ -62,8 +62,9 @@ module Samagotchi
     #   question already pending then is not the answer's. A nil
     #   messages: skips the count. last_turn: (the session's
     #   last_turn["ended_at"] then, maybe nil) ends the wait on any turn
-    #   that ended since, idle again, however fast it ran: a failure after
-    #   a failure replaces the note and leaves the count as it was.
+    #   that ended since, idle again, however fast it ran (a failure after
+    #   a failure replaces the note and leaves the count as it was), and
+    #   with it the count isn't used: a note between turns grows it too.
     # @param owner_grace [Numeric, nil] seconds with no live worker before
     #   :worker_gone (one that died before its rescue leaves it running)
     # @param interject [#call, nil] called once a poll, before the sleep
@@ -145,13 +146,17 @@ module Samagotchi
     end
 
     # An idle session whose turn ended after the baseline was taken: its
-    # last_turn moved on, or its messages grew (a turn's note).
+    # last_turn moved on. Every turn's end records last_turn as it goes
+    # idle (Engine#end_turn), so with one in the baseline that alone
+    # decides: messages also grow between turns (a new worker's context
+    # note, a chi note) with no turn run. A baseline without it falls back
+    # to the count (a turn's note).
     def turn_ended_since?(session, baseline)
       return false unless baseline
 
       if baseline.key?(:last_turn)
         ended = session.last_turn.is_a?(Hash) ? session.last_turn["ended_at"] : nil
-        return true if ended && ended != baseline[:last_turn]
+        return !ended.nil? && ended != baseline[:last_turn]
       end
       !!(baseline[:messages] && session.messages.size > baseline[:messages])
     end

data/lib/samagotchi/send_command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "client_id"
 require_relative "session"
 require_relative "session_inbox"
 require_relative "session_manager"
@@ -26,7 +27,7 @@ module Samagotchi
     include CLI::Command
     include CLI::ParentWait
 
-    CLIENT_ID = "cli:send"
+    CLIENT_ID = ClientId::CLI_SEND
     # The cap on one turn's images the Bridge checks.
     MAX_IMAGES = ImageStore::MAX_TURN_REFS
 

data/lib/samagotchi/session_manager.rb

@@ -5,6 +5,7 @@ require "json"
 require "time"
 require "securerandom"
 require "rbconfig"
+require_relative "client_id"
 require_relative "atomic_file"
 require_relative "config"
 
@@ -59,9 +60,6 @@ module Samagotchi
   autoload :SessionRetention, File.expand_path("session_retention", __dir__)
 
   class SessionManager
-    # Origin of the synthetic turn queued when reminders are due.
-    REMINDER_CLIENT_ID = "system:reminder"
-
     # Raised when the interactive TUI owns the session: it runs its own Engine
     # and reads no input files, so a worker must not be spawned or signalled.
     class OwnedByTUI < StandardError
@@ -583,7 +581,7 @@ module Samagotchi
     # @raise [OwnedByTUI] a chi REPL owns the session
     # @raise [RestartRefused]
     # @raise [ArgumentError] no such session
-    def self.restart_session(session_id, state_dir: nil, wait: RESTART_WAIT, client_id: "cli:restart")
+    def self.restart_session(session_id, state_dir: nil, wait: RESTART_WAIT, client_id: ClientId::CLI_RESTART)
       sd = state_dir || Session.default_state_dir
       Session.load(session_id, state_dir: sd) # ArgumentError for none
       owner = refuse_tui!(session_id, state_dir: sd)

data/lib/samagotchi/steer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "client_id"
+
 module Samagotchi
   # A plugin's steer: text a plugin puts into the running turn (Engine#steer),
   # the way a UI's steering does. The drain a loop gets returns items: a
@@ -12,8 +14,9 @@ module Samagotchi
   # "input": they are part of that turn, not a turn of their own, so a
   # reloaded history keeps the turn in one piece. A line can be a Line
   # naming who sent it (a worker's input from chi send, a delegating parent,
-  # a plugin); its input message then carries that source:. The user's own
-  # lines carry none, so their saved bytes are as they always were.
+  # a plugin, a client chi doesn't know); its input message then carries
+  # that source:. The user's own lines carry none, so their saved bytes are
+  # as they always were.
   module Steer
     KIND = "steer"
     INPUT_KIND = "input"
@@ -27,18 +30,10 @@ module Samagotchi
       def initialize(text:, source:, mark: nil) = super
     end
 
-    # The client ids whose input is not the user's own words. Literals, not
-    # SendCommand::CLIENT_ID / Tools::Delegate::CLIENT_PREFIX, so this file
-    # needs no requires (a spec pins them equal).
-    CHI_SEND_CLIENT = "cli:send"
-    DELEGATE_CLIENT_PREFIX = "delegate:"
-    # A delegate child's report (ChildReports::CLIENT_PREFIX).
-    CHILD_CLIENT_PREFIX = "child:"
-    # A turn chi ran because an attached context source changed
-    # (context:<name>, Worker's context wake).
-    CONTEXT_CLIENT_PREFIX = "context:"
     DELEGATE_REPORT = "delegate_report"
-    PLUGIN_CLIENT = "plugin"
+    # The source of a line from a client that is not a human's
+    # (ClientId.human?) and not one chi names: automatic:<client id>.
+    AUTOMATIC_SOURCE_PREFIX = "automatic:"
 
     # What one drain brought: the merged user text (nil when none) and how
     # many lines made it, the input messages' text grouped by sender
@@ -98,35 +93,48 @@ module Samagotchi
                            "Don't call delegate_result for it; to retry or redirect that child, use delegate with " \
                            "its session:.]"
     }.freeze
+    # A line from a client chi doesn't know (AUTOMATIC_SOURCE_PREFIX):
+    # never taken for the user's.
+    AUTOMATIC_HEADER = "[Automatic input from %s, sent mid-task; not your user's message. " \
+                       "If it asks for nothing, carry on with the task.]"
 
     module_function
 
     # The saved source of a worker input line from +client_id+: nil for the
-    # user (no client id, the web, an attached TUI, anything unknown).
+    # user (no client id, the web, an attached TUI); automatic:<client id>
+    # for a client that is no human's and chi doesn't name (an unknown id is
+    # not the user).
     def source_for_client(client_id)
       id = client_id.to_s
-      if id == CHI_SEND_CLIENT then "chi_send"
-      elsif id.start_with?(DELEGATE_CLIENT_PREFIX) then "parent_agent"
-      elsif id.start_with?(CHILD_CLIENT_PREFIX) then DELEGATE_REPORT
-      elsif id == PLUGIN_CLIENT then "plugin_send"
+      if id == ClientId::CLI_SEND then "chi_send"
+      elsif id.start_with?(ClientId::DELEGATE_PREFIX) then "parent_agent"
+      elsif id.start_with?(ClientId::CHILD_PREFIX) then DELEGATE_REPORT
+      elsif id == ClientId::PLUGIN then "plugin_send"
+      elsif !ClientId.human?(client_id) then "#{AUTOMATIC_SOURCE_PREFIX}#{id}"
       end
     end
 
     # The header for a steer or merged input message, else nil. No source
     # (or "") is the user's; an input with an unknown source too; a steer
-    # with an unknown source is a plugin's (its bundle or hook label).
+    # with an unknown source is a plugin's (its bundle or hook label); an
+    # automatic:<client id> source names that client, not the user.
     def header(message)
       kind = (message[:kind] || message["kind"]).to_s
       return unless [KIND, INPUT_KIND].include?(kind)
 
       source = (message[:source] || message["source"]).to_s
       return HEADERS[source] if HEADERS.key?(source)
+      return automatic_header(source.delete_prefix(AUTOMATIC_SOURCE_PREFIX)) if source.start_with?(AUTOMATIC_SOURCE_PREFIX)
 
       source = "user" if source.empty?
       sender = SENDERS[source] || (kind == KIND ? "from the #{source} plugin" : SENDERS["user"])
       "[Steer #{sender}, #{HEADER_TAIL}"
     end
 
+    def automatic_header(client_id)
+      format(AUTOMATIC_HEADER, client_id.empty? ? "an unnamed client" : client_id)
+    end
+
     # The text a steer or merged input goes out as: its header, a newline,
     # then +text+ (the message's content by default). Other messages: +text+.
     def wire_text(message, text = (message[:content] || message["content"]).to_s)

data/lib/samagotchi/steer_cut.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+require_relative "steer"
+require_relative "generation_phase"
+require_relative "waiting_steer"
+
+module Samagotchi
+  # A message for the running turn cutting the generation it came during:
+  # what the generation streams (GenerationPhase, fed by #observe from the
+  # turn's stream) and a message that came too early to cut (WaitingSteer).
+  # The Engine's seam: Bridge and TerminalUI call Engine#cut_for_steer and
+  # #input_epoch, the turn thread feeds #observe and #delivered!, and the
+  # turn's end calls #finished!. Callable from any thread: GenerationPhase
+  # and WaitingSteer hold their own locks.
+  class SteerCut
+    # A chunk's thinking and text. A chunk without the lanes (no loop of
+    # ours sends one) counts as text.
+    def self.lanes(event)
+      text = event.key?(:text) ? event[:text] : event[:content]
+      { thinking: event[:thinking].to_s, text: text.to_s }
+    end
+
+    # +clock+: monotonic seconds; +controller+: the running turn's cancel
+    # controller (nil between turns), read only when a cut is due.
+    def initialize(clock:, controller:)
+      # What the running generation streams: whether a steer may cut it.
+      @phase = GenerationPhase.new(clock: clock)
+      # A message that may cut it but came too early: it cuts later.
+      @waiting = WaitingSteer.new
+      @controller = controller
+    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 (CutPolicy) 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, 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).
+    # @return [Boolean] whether a generation was cut now
+    def cut_for_steer(source, epoch: nil)
+      return false unless Steer.cuts?(source)
+
+      after = Config.get("steer.cut_after").to_i
+      return false unless after.positive?
+
+      ctrl = @controller.call
+      return false unless ctrl
+      return cut!(ctrl, source.to_s) if @phase.cuttable?(after)
+
+      Log.info(:turn, "steer_cut_waits", source: source.to_s) if @waiting.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.epoch
+    end
+
+    # The turn's stream: the generation's phase follows it, and a thinking
+    # chunk rechecks a waiting message. +progress+: a chunk's lanes
+    # (.lanes), read from it when not given.
+    def observe(event, progress = nil)
+      case event[:type]
+      when :generation_started then @phase.started!
+      when :generation_chunk
+        progress ||= self.class.lanes(event)
+        @phase.chunk!(**progress, tool_call: event[:tool_call])
+        recheck unless progress[:thinking].empty?
+      when :generation_retrying then @phase.retrying!
+      when :generation_completed, :generation_cancelled then @phase.finished!
+      end
+    end
+
+    # The turn's input went to the model: a message that waited to cut is in.
+    def delivered!
+      @waiting.delivered!
+    end
+
+    # The turn ended: no generation, nothing waiting.
+    def finished!
+      @phase.finished!
+      @waiting.clear!
+    end
+
+    private
+
+    # A thinking chunk streamed: a waiting message cuts once the thinking
+    # passes steer.cut_after.
+    def recheck
+      return unless @waiting.waiting?
+
+      after = Config.get("steer.cut_after").to_i
+      return unless after.positive? && @phase.cuttable?(after)
+
+      source = @waiting.take
+      ctrl = @controller.call
+      cut!(ctrl, source, waited: true) if source && ctrl
+    rescue StandardError
+      nil
+    end
+
+    def cut!(ctrl, source, waited: false)
+      age = @phase.age
+      cut = ctrl.cancel_generation!(:steer, { by: "steer", steer: true, source: source, reason: "a new message" })
+      if cut
+        @waiting.clear!
+        fields = { source: source, age: age&.round(1) }
+        fields[:waited] = true if waited
+        Log.info(:turn, "steer_cut", **fields)
+      end
+      cut
+    end
+  end
+end

data/lib/samagotchi/system_prompt.rb

@@ -195,7 +195,7 @@ module Samagotchi
           6. Use write for full-file rewrites or creating new files.
 
         Memory convention:
-          Project scope: one folder per git repository, shared by its worktrees and subdirectories (its path is on the "Project memories folder:" line below)
+          Project scope: one folder per git repository, shared by its worktrees and subdirectories (its path is on the "Project memories folder" line below)
           System scope:  ~/.config/samagotchi/memories/ (cross-project)
           memory_read accepts optional scope (project|system).
           memory_write requires explicit scope and entry name.
@@ -413,21 +413,33 @@ module Samagotchi
         .find { |path| File.file?(path) }
     end
 
-    # Where the session runs and which project memory folder it uses. The root
-    # line appears only when it differs from the cwd (a worktree or subdir).
+    # Where the session runs and which project memory folder it uses. Only
+    # this checkout is named: its top (at its root too, so a model doesn't
+    # take the memories folder for the project and cd there, Qwen
+    # 2026-10-06), and in a linked worktree a line that work stays in it. The repository's main
+    # checkout (MemoryPaths.project_root, which scopes memories and session
+    # lists) is never shown: a model told its path went to work there
+    # (a worktree child committed onto main, 2026-10-03 and 2026-10-06).
     # The home directory is spelled out once so the model copies the right
     # sequence, with the advice to write it as ~ or $HOME instead.
     def project_location
       cwd = Dir.pwd
-      root = MemoryPaths.project_root(cwd)
+      top = MemoryPaths.work_tree_root(cwd)
       lines = ["Current working directory:", cwd]
-      unless root == cwd
-        lines << "Project root (only where shared project memories come from; read, edit, run and commit in the current working directory above):"
-        lines << root
+      if top && top != cwd
+        lines << "Top of this checkout (where the project's commands run from; stay inside it):"
+        lines << top
+      elsif top
+        lines << "This checkout (the project's files; its commands run here):"
+        lines << top
+      end
+      if top && MemoryPaths.project_root(cwd) != top
+        lines << "This checkout is a linked git worktree: read, edit, run and commit only in it, never in the " \
+                 "repository's other checkouts."
       end
       home = Dir.home
       lines << "Home directory: #{home} (write it as ~ or $HOME in commands and paths)" unless home.to_s.empty?
-      lines << "Project memories folder:"
+      lines << "Project memories folder (your notes about the project, not its files; never work or run commands there):"
       lines << home_relative(Tools::MemoryRead.memories_dir("project"))
       lines.join("\n")
     rescue StandardError

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../client_id"
 require_relative "event_renderer"
 require_relative "formatting"
 require_relative "../prompt_history"
@@ -773,7 +774,7 @@ module Samagotchi
           return @screen.commit(answer.error)
         end
 
-        parent = @parent_answers ? { client_id: Guardrails::ParentApprovals::CLIENT_ID } : {}
+        parent = @parent_answers ? { client_id: ClientId::CLI_ANSWER } : {}
         reply = @client.answer(id: @question.id, selected: answer.selected, freeform: answer.freeform, **parent)
         case reply.status
         when 200
@@ -1268,9 +1269,9 @@ module Samagotchi
         nil
       end
 
-      def reminder_origin?(origin) = origin[:client_id].to_s.start_with?("system:")
-      def report_origin?(origin) = origin[:client_id].to_s.start_with?(Steer::CHILD_CLIENT_PREFIX)
-      def context_origin?(origin) = origin[:client_id].to_s.start_with?(Steer::CONTEXT_CLIENT_PREFIX)
+      def reminder_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::SYSTEM_PREFIX)
+      def report_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::CHILD_PREFIX)
+      def context_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::CONTEXT_PREFIX)
       # A turn with no prompt: "(continuing)"; a context wake's label alone.
       def continuing_text(origin) = context_origin?(origin) ? nil : "(continuing)"
     end