samagotchi 0.133.0 → 0.135.0

data/lib/samagotchi/project_env.rb

@@ -80,7 +80,8 @@ module Samagotchi
     # chi home doctor's row when session.project_env is mise and no mise is found.
     NO_MISE = "project env: no mise found (home.json's, PATH, /opt/homebrew/bin, /usr/local/bin, ~/.local/bin): " \
               "tools run in the env of whoever starts the worker; install mise, or set session.project_env: off"
-    # How much of the debug log's end chi home doctor reads for #last_warning.
+    # How much of the debug log's end chi home doctor reads (#last_warning,
+    # HomeDoctor's boot row).
     LOG_TAIL_BYTES = 4 * 1024 * 1024
 
     # A worker's `project_env` warning from the debug log (#last_warning).
@@ -327,7 +328,7 @@ module Samagotchi
 
       want = Array(dirs).map { |dir| ChiHome.real(dir) }
       newest = {}
-      each_tail_record(log_path) do |record|
+      LogLine.each_tail_record(log_path, bytes: LOG_TAIL_BYTES) do |record|
         next unless record.tag == "worker" && %w[project_env project_env_applied].include?(record.event)
 
         dir = record.fields["dir"]
@@ -342,15 +343,6 @@ module Samagotchi
       nil
     end
 
-    def each_tail_record(log_path, &)
-      File.open(log_path, "rb") do |io|
-        size = io.size
-        io.seek([size - LOG_TAIL_BYTES, 0].max)
-        io.gets if size > LOG_TAIL_BYTES # a torn first line
-        LogLine.each_record(io, &)
-      end
-    end
-
     def configured_mode
       Config.get("session.project_env").to_s
     rescue StandardError

data/lib/samagotchi/revise_anchor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "verify_anchor"
+
+module Samagotchi
+  # The earlier turn a Revise turn rewrites the answer of, carried only by
+  # a Revise turn (TurnAnchors). Its stamp on the turn's opening message
+  # is display metadata, never in the prompt (Engine#revision_target).
+  ReviseAnchor = Data.define(:turn_id) do
+    def self.from(value)
+      return value if value.is_a?(self)
+      return nil unless value.is_a?(Hash)
+
+      fields = value.to_h { |key, entry| [key.to_s, entry] }
+      return nil unless fields.keys == %w[turn_id]
+
+      turn_id = fields["turn_id"]
+      return nil unless turn_id.is_a?(String) && VerifyAnchor::UUID.match?(turn_id)
+
+      new(turn_id:)
+    end
+
+    def to_h = { turn_id: }
+
+    def to_file = { "turn_id" => turn_id }
+  end
+
+  ReviseAnchor::FEATURE = "revise"
+  ReviseAnchor::UNAVAILABLE = {
+    "error" => "revise_unavailable",
+    "detail" => "this session's worker predates Revise turns; restart this session to use Revise"
+  }.freeze
+end

data/lib/samagotchi/self_report.rb

@@ -25,6 +25,7 @@ require_relative "desktop"
 require_relative "live_versions"
 require_relative "web/lan"
 require_relative "chi_home"
+require_relative "home_notice"
 require_relative "project_env"
 
 module Samagotchi
@@ -429,7 +430,8 @@ module Samagotchi
 
       label = "#{home.ruby} (chi #{home.newest_version})"
       return "#{label}; this chi is a source checkout" unless InstalledGem.spec
-      return label if home.running_here?
+      return label if HomeNotice.home?(home)
+      return "#{label}; this chi is #{VERSION}" if home.running_here?
 
       "#{label}; this chi runs on #{RbConfig.ruby}"
     rescue ChiHome::Invalid => e

data/lib/samagotchi/session_inbox.rb

@@ -12,8 +12,10 @@ require_relative "steer"
 require_relative "turn_origin"
 
 module Samagotchi
-  # Loaded on first use (a Verify turn's input): keeps the bundle test kit's
-  # load budget (spec/samagotchi/testing/sandbox_spec.rb).
+  # Loaded on first use (any turn's input, a Verify or a Revise turn's
+  # anchor): keeps the bundle test kit's load budget
+  # (spec/samagotchi/testing/sandbox_spec.rb).
+  autoload :TurnAnchors, File.expand_path("turn_anchors", __dir__)
   autoload :VerifyAnchor, File.expand_path("verify_anchor", __dir__)
 
   # A session directory's file inbox and outbox (see SessionManager for the
@@ -54,10 +56,12 @@ module Samagotchi
     # @param author [String, nil] who wrote the message when it isn't the
     #   session's owner (Web::Principal#author); nil, the owner's, is never
     #   written, so an owner's file is as it always was
+    # @param anchors [TurnAnchors, Hash, nil] a Verify turn's claim, a Revise
+    #   turn's draft (TurnAnchors#to_file's keys; none: none written)
     # @param now [Time] the time the file is named by (a spec's clock)
     # @return [String, false] the input file's path, or false
     def self.write_input(session_dir, prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [],
-                         delivery: nil, author: nil, verify: nil, now: Time.now)
+                         delivery: nil, author: nil, anchors: nil, now: Time.now)
       images = Array(images)
       input_dir = File.join(session_dir, INPUT_DIR)
       FileUtils.mkdir_p(input_dir)
@@ -67,7 +71,8 @@ module Samagotchi
                  "no_interrupt" => (no_interrupt ? true : nil),
                  "delivery" => (Delivery.queue?(delivery) ? Delivery::QUEUE : nil),
                  "images" => (images.empty? ? nil : images.map { |image| image.transform_keys(&:to_s) }),
-                 "author" => author, "verify" => VerifyAnchor.from(verify)&.to_file }.compact
+                 "author" => author }.compact
+      record.merge!(TurnAnchors.from(anchors).to_file) if anchors
       AtomicFile.write(path, JSON.generate(record))
       path
     rescue StandardError
@@ -231,10 +236,12 @@ module Samagotchi
     # no sender), whether its turn runs with the raised iteration limit
     # (+no_interrupt+, --no-interrupt), its +images+ ({file:, name:} refs),
     # and its +delivery+ ("queue" or nil; a file without the key is one an
-    # older chi wrote, so nil).
-    Input = Data.define(:prompt, :origin, :no_interrupt, :images, :delivery, :verify) do
-      def initialize(prompt:, origin: nil, no_interrupt: false, images: [], delivery: nil, verify: nil)
-        super(prompt:, origin: TurnOrigin.of(origin), no_interrupt:, images:, delivery:, verify: verify && VerifyAnchor.from(verify))
+    # older chi wrote, so nil), and its +anchors+ (TurnAnchors, nil when it
+    # names none: TurnAnchors loads on first use, not with UNREADABLE_INPUT).
+    Input = Data.define(:prompt, :origin, :no_interrupt, :images, :delivery, :anchors) do
+      def initialize(prompt:, origin: nil, no_interrupt: false, images: [], delivery: nil, anchors: nil)
+        anchors &&= TurnAnchors.from(anchors)
+        super(prompt:, origin: TurnOrigin.of(origin), no_interrupt:, images:, delivery:, anchors: anchors && anchors.empty? ? nil : anchors)
       end
     end
     # A file that doesn't parse, or isn't a JSON object: no prompt.
@@ -250,7 +257,7 @@ module Samagotchi
       origin = TurnOrigin.from(data.slice("client_id", "enqueued_id", "author"))
       images = Array(data["images"]).select { |image| image.is_a?(Hash) }.map { |image| image.transform_keys(&:to_sym) }
       Input.new(prompt: data["prompt"].to_s, origin: origin, no_interrupt: data["no_interrupt"] == true,
-                images: images, delivery: Delivery.queue?(data["delivery"]) ? Delivery::QUEUE : nil, verify: data["verify"])
+                images: images, delivery: Delivery.queue?(data["delivery"]) ? Delivery::QUEUE : nil, anchors: data)
     rescue JSON::ParserError
       UNREADABLE_INPUT
     end
@@ -282,11 +289,12 @@ module Samagotchi
       true
     end
 
-    # A parsed input file's #waits_for_turn_end?. A Verify turn waits too:
-    # merged into a running turn as a steer, its anchor would be lost.
+    # A parsed input file's #waits_for_turn_end?. A Verify or a Revise turn
+    # waits too: merged into a running turn as a steer, its anchor would be
+    # lost.
     def self.turn_end_data?(data)
       Array(data["images"]).any? || Delivery.queue?(data["delivery"]) || Steer.participant_author?(data["author"]) ||
-        data["verify"].is_a?(Hash)
+        TurnAnchors.named_in?(data)
     end
 
     # Whether a message waits that a running turn's next boundary merges and

data/lib/samagotchi/session_manager.rb

@@ -1368,10 +1368,11 @@ module Samagotchi
     #   session's images/
     # @return [String, false] the input file's path, or false.
     def self.write_turn_input(session_id, prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, state_dir: nil,
-                              images: [], delivery: nil, author: nil, verify: nil)
+                              images: [], delivery: nil, author: nil, anchors: nil)
       session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
       SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, verify: verify)
+                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author,
+                                            anchors: anchors)
     end
 
     # How long a turn waits for the Bridge of a worker a resume just spawned.
@@ -1440,6 +1441,9 @@ module Samagotchi
     # @param pending_limit [Integer, nil] with +author+: how many of their
     #   turns may be running or waiting (the Bridge counts them; with no
     #   worker, their waiting files): :refused 429 too_many_turns past it
+    # @param anchors [TurnAnchors, Hash, nil] a Verify turn's claim, a Revise
+    #   turn's draft: each refused (409, its UNAVAILABLE) by a worker without
+    #   its feature
     # @param manager [#resume_session, #write_turn_input] this class, or a
     #   stand-in (the web's specs); #session_owner is optional
     # @param bridge [#call, nil] returns the BridgeClient or nil; defaults to
@@ -1453,8 +1457,8 @@ module Samagotchi
     # @raise [OwnedByTUI] a chi REPL owns the session
     # @raise [ArgumentError] no such session
     def self.deliver_turn(session_id, prompt:, client_id: nil, images: [], delivery: nil, no_interrupt: false,
-                          author: nil, pending_limit: nil, verify: nil, state_dir: nil, manager: self, bridge: nil)
-      verify = VerifyAnchor.from(verify)
+                          author: nil, pending_limit: nil, anchors: nil, state_dir: nil, manager: self, bridge: nil)
+      anchors = TurnAnchors.from(anchors)
       session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
       bridge ||= lambda do
         link = WorkerLink.await(session_id, session_dir: session_dir, timeout: TURN_BRIDGE_WAIT)
@@ -1462,7 +1466,9 @@ module Samagotchi
       end
       manager.resume_session(session_id, state_dir: state_dir)
       if (client = bridge.call)
-        return verify_unavailable if verify && !worker_has?(client, VerifyAnchor::FEATURE)
+        if (missing = anchors.present.find { |anchor| !worker_has?(client, anchor.class::FEATURE) })
+          return DeliverResult.new(status: :refused, code: 409, ack: missing.class::UNAVAILABLE)
+        end
         # A worker from before queueing (no "delivery" feature) ignores the
         # field or refuses it; either way a file would steer the running turn.
         return queue_unavailable if Delivery.queue?(delivery) && !worker_has?(client, Delivery::QUEUE_FEATURE)
@@ -1477,7 +1483,7 @@ module Samagotchi
           options[:no_interrupt] = true if no_interrupt
           options[:author] = author if author
           options[:pending_limit] = pending_limit if author && pending_limit
-          options[:verify] = verify if verify
+          options[:anchors] = anchors unless anchors.empty?
           reply = client.post_turn(**options)
           ack = reply.json
           return DeliverResult.new(status: :accepted, via: :bridge, ack: ack) if reply.status == 202 && ack.is_a?(Hash)
@@ -1515,7 +1521,7 @@ module Samagotchi
       input[:delivery] = delivery unless Delivery.next_step?(delivery)
       input[:no_interrupt] = true if no_interrupt
       input[:author] = author if author
-      input[:verify] = verify if verify
+      input[:anchors] = anchors unless anchors.empty?
       path = participant_queue_lock(session_dir, author && pending_limit) do
         # No worker: the participant's waiting files are all their turns,
         # counted and written under one lock (the Bridge counts under its).
@@ -1581,10 +1587,6 @@ module Samagotchi
       DeliverResult.new(status: :refused, code: 409, ack: Delivery::REVIEW_UNAVAILABLE)
     end
 
-    private_class_method def self.verify_unavailable
-      DeliverResult.new(status: :refused, code: 409, ack: VerifyAnchor::UNAVAILABLE)
-    end
-
     private_class_method def self.turn_timeout
       DeliverResult.new(status: :timeout, via: :bridge,
                         ack: { "error" => "worker_timeout",

data/lib/samagotchi/system_one/approval_question.rb

@@ -2,6 +2,7 @@
 
 require "digest"
 
+require_relative "../guardrails/approval"
 require_relative "question"
 require_relative "similar"
 
@@ -35,29 +36,31 @@ module Samagotchi
         Question.new(id: ID, type: "noul", instructions: INSTRUCTIONS)
       end
 
-      # @param approval [Hash] payload[:approval]: the ask the user is shown
+      # @param approval [Guardrails::ApprovalFacts, Hash] payload[:approval]:
+      #   the ask the user is shown (a saved card's hash too)
       # @param session_title [String, nil] the session's title, when it has one
       # @param entries [Array<Hash>] SystemOne::Log#entries: the judgments the
       #   user has answered so far, read once per ask and shared with the
       #   record gate (GuardrailWiring#system_one_judge)
       # @return [Hash] the state, with the fields the ask didn't give left out
       def self.state(approval, session_title: nil, entries: nil)
+        approval = Guardrails::ApprovalFacts.from_h(approval)
         {
-          "rule" => approval[:rule],
-          "source" => approval[:source],
-          "reason" => approval[:reason],
-          "tool" => approval[:tool],
-          "command" => cut(approval[:command]),
-          "paths" => Array(approval[:paths]).map { |path| cut(path) },
-          "change" => change_text(approval[:preview]),
-          "cwd" => approval[:cwd],
-          "repo_name" => approval[:repo_name],
-          "branch" => approval[:branch],
+          "rule" => approval.rule,
+          "source" => approval.source,
+          "reason" => approval.reason,
+          "tool" => approval.tool,
+          "command" => cut(approval.command),
+          "paths" => Array(approval.paths).map { |path| cut(path) },
+          "change" => change_text(approval.preview),
+          "cwd" => approval.cwd,
+          "repo_name" => approval.repo_name,
+          "branch" => approval.branch,
           "session" => session_title,
           # Which memory entry the ask is about, when it is a memory ask.
-          "memory" => memory_facts(approval[:memory]),
+          "memory" => memory_facts(approval.memory),
           # The asks this one looks like, and what the user did about them.
-          "examples" => Similar.select(entries: entries, rule: approval[:rule], repo_name: approval[:repo_name],
+          "examples" => Similar.select(entries: entries, rule: approval.rule, repo_name: approval.repo_name,
                                        call_text: call_text(approval))
         }.reject do |_key, value|
           value.nil? || (value.is_a?(String) && value.strip.empty?) ||
@@ -67,14 +70,16 @@ module Samagotchi
 
       # What the call is, whole: the command, the paths, or a plugin tool's
       # arguments.
+      # @param approval [Guardrails::ApprovalFacts, Hash] as built or saved
       def self.call_text(approval)
-        command = approval[:command]
+        approval = Guardrails::ApprovalFacts.from_h(approval)
+        command = approval.command
         return command.to_s if command && !command.to_s.empty?
 
-        paths = Array(approval[:paths])
+        paths = Array(approval.paths)
         return paths.join("\n") unless paths.empty?
 
-        approval[:args].to_s
+        approval.args.to_s
       end
 
       # The judgment log's two fields for the call: what it was, cut to

data/lib/samagotchi/system_one/self_protect.rb

@@ -3,8 +3,10 @@
 require_relative "../config"
 require_relative "../memory_paths"
 require_relative "../paths"
+require_relative "../guardrails/approval"
 require_relative "../guardrails/chi_dirs"
 require_relative "../guardrails/path_resolve"
+require_relative "../guardrails/pair_command"
 require_relative "../guardrails/parent_approvals"
 require_relative "../guardrails/shell_lex"
 require_relative "../guardrails/shell_paths"
@@ -31,7 +33,12 @@ module Samagotchi
     # `/`) read while the dir was known. A word the walk can't follow
     # otherwise (`${PWD%/*}`, `$(dirname $PWD)`, `cd -`) may climb out of the
     # memories dir without saying so, so its memories text stays in and the
-    # text check refuses it.
+    # text check refuses it. So does a script an interpreter or shell runs
+    # that climbs by its own calls (SCRIPT_CLIMB: os.pardir, dirname,
+    # chdir, Dir.pwd, Path.parent, rindex, a slice from the end), and one
+    # chi can't see: a script file it names, or stdin
+    # (Guardrails::PairCommand.script_source). A heredoc or phrase that is
+    # only written (cat >> note <<EOF) is data whatever it says.
     #
     # Pure: it only reads the paths as this process's environment names them,
     # and answers on the approval's own facts (Guardrails::Approval.payload's
@@ -58,6 +65,21 @@ module Samagotchi
         /(?:\A|[\s;&|(])(?:cd|pushd)\s+-(?=[\s;&|)]|\z)/
       )
 
+      # An interpreter's own calls that climb out of a dir or cut a path
+      # from its end, as a script body may spell them without `..` or `$`
+      # (an accident guard, not a parser: a script can always build a path
+      # some other way).
+      SCRIPT_CLIMB = Regexp.union(
+        /\b(?:pardir|dirname|parents?|chdir|getcwd|cwd|pwd|abspath|realpath|normpath|expand_path|absolute_path|
+           resolve|rsplit|rpartition|rindex|rfind|lastIndexOf)\b/x,
+        /\b(?:os\.path|File)\.split\b/, /\[[^\]\[]*:\s*-/
+      )
+
+      # Programs that run a script file (theirs or the dir's) by the words
+      # that make them do it ([]: any call): unseen, like a shell's file.
+      FILE_RUNNERS = { /\Ag?make\z/ => [], /\Arake\z/ => [], /\A[gmn]?awk\z/ => %w[-f], /\Adeno\z/ => %w[run task],
+                       /\A(?:npm|yarn|pnpm|bun)\z/ => %w[run run-script test start exec x] }.freeze
+
       # What resolving a command's words found: whether one lands in chi's
       # dirs (outside the memories dir, or in its installed bundles), and
       # whether every word resolved or is data (#plain).
@@ -65,20 +87,21 @@ module Samagotchi
 
       module_function
 
-      # @param approval [Hash, nil] the ask's approval facts (rule, tool,
-      #   paths, command, cwd)
+      # @param approval [Guardrails::ApprovalFacts, Hash, nil] the ask's
+      #   approval facts (rule, tool, paths, command, cwd), as built or saved
       # @param targets [Guardrails::Targets, nil] the call's targets, for its
       #   env: (Targets#shell_envs, #redefines_shell?)
       # @return [Boolean] whether System 1 must not answer this ask
       def refuse?(approval, targets: nil)
-        return false unless approval.is_a?(Hash)
-        return true if NEVER_AUTO.include?(fetch(approval, :rule).to_s)
+        approval = Guardrails::ApprovalFacts.from_h(approval)
+        return false if approval.nil?
+        return true if NEVER_AUTO.include?(approval.rule.to_s)
         # An env: that redefines the shell (BASH_ENV, BASH_FUNC_…) runs what
         # no word of the command says.
         return true if targets&.redefines_shell?
 
-        command = fetch(approval, :command).to_s
-        words = command.empty? ? nil : words(command, cwd: fetch(approval, :cwd), targets: targets)
+        command = approval.command.to_s
+        words = command.empty? ? nil : words(command, cwd: approval.cwd, targets: targets)
         return true if words&.chi
         return true if chi_paths?(approval)
         # The test that makes an ask user_only (ParentApprovals#chi_files?:
@@ -95,7 +118,7 @@ module Samagotchi
         memories = Guardrails::PathResolve.real(MemoryPaths.system_dir)
         bundles = Guardrails::PathResolve.real(MemoryPaths.bundles_dir)
         dirs = chi_dirs
-        Array(fetch(approval, :paths)).map(&:to_s).reject(&:empty?).any? do |path|
+        Array(approval.paths).map(&:to_s).reject(&:empty?).any? do |path|
           Guardrails::PathResolve.reals(path).any? do |real|
             dirs.any? { |dir| Guardrails::PathResolve.within?(real, dir) } && !memory?(real, memories, bundles)
           end
@@ -108,12 +131,12 @@ module Samagotchi
       def beyond_memories(approval, exempt:)
         memories = Guardrails::PathResolve.real(MemoryPaths.system_dir)
         bundles = Guardrails::PathResolve.real(MemoryPaths.bundles_dir)
-        paths = Array(fetch(approval, :paths)).map(&:to_s).reject do |path|
+        paths = Array(approval.paths).map(&:to_s).reject do |path|
           Guardrails::PathResolve.reals(path).all? { |real| memory?(real, memories, bundles) }
         end
-        command = fetch(approval, :command).to_s
+        command = approval.command.to_s
         command = command.gsub(memories_text) { |text| text.include?("/.bundles") ? text : "" } if exempt
-        { paths: paths, command: command }
+        approval.with(paths: paths, command: command)
       end
 
       # Whether the command's memories text may be taken out: no command,
@@ -133,14 +156,18 @@ module Samagotchi
                 tokens.none? { |_, value| value.include?(Guardrails::ShellLex::SUBST) }
         chi = false
         commands = Guardrails::ShellLex.simple_commands(tokens)
+        pipes = Guardrails::ShellLex.piped_flags(tokens)
         envs = targets ? targets.shell_envs : [[Dir.home, ENV]]
         envs.each do |home, env|
+          piped = pipes.dup
           walk = Guardrails::ShellPaths::Walk.new(cwd.to_s.empty? ? Dir.pwd : cwd.to_s, home, env)
           commands.each do |simple|
             # A cd the walk couldn't follow: no later word is data.
             known = !simple.is_a?(Array) || !walk.paths(".").empty?
+            runs = simple.is_a?(Array) && runs_script?(simple)
+            plain &&= !unseen_script?(simple, piped: simple.is_a?(Array) && piped.shift)
             walk.step(simple).each do |word, path|
-              next plain &&= known && data?(word) unless path
+              next plain &&= known && data?(word) && !(runs && climbs?(word)) unless path
 
               chi ||= Guardrails::PathResolve.reals(path).any? do |real|
                 dirs.any? { |dir| Guardrails::PathResolve.under?(real, dir) } && !memory?(real, memories, bundles)
@@ -165,6 +192,37 @@ module Samagotchi
         word.match?(Guardrails::ShellPaths::GLOB) && !word.include?("/")
       end
 
+      # Whether a simple command hands a script to a shell or interpreter
+      # (one anywhere in it, find -execdir's too) or has a code option.
+      def runs_script?(simple)
+        simple.any? do |word|
+          Guardrails::PairCommand.runner?(word) || Guardrails::PairCommand::CODE_OPTIONS.include?(word)
+        end
+      end
+
+      # Whether a simple command runs a script chi can't see: its shell or
+      # interpreter (any version's name: python3.12, pypy3, Rscript, tclsh)
+      # runs a file or stdin, a pipe into it included whatever its options
+      # (Guardrails::PairCommand.script_source), or another program runs a
+      # file of the dir it is in (FILE_RUNNERS: make, awk -f, deno run,
+      # npm run).
+      def unseen_script?(simple, piped: false)
+        return false unless simple.is_a?(Array)
+        return true if %i[file stdin].include?(Guardrails::PairCommand.script_source(simple, piped: piped))
+
+        simple.each_with_index.any? do |word, i|
+          next false if word.include?("\0")
+
+          verbs = FILE_RUNNERS.find { |pattern, _| Guardrails::ShellLex.program_name(word).match?(pattern) }&.last
+          verbs && (verbs.empty? || simple[(i + 1)..].intersect?(verbs))
+        end
+      end
+
+      # Whether a script word, its memories text aside, climbs (SCRIPT_CLIMB).
+      def climbs?(word)
+        word.match?(Guardrails::ShellPaths::SCRIPT) && word.gsub(memories_text, "").match?(SCRIPT_CLIMB)
+      end
+
       # chi's own dirs (ParentApprovals.chi_dirs) and its whole state dir
       # (DEFAULT_STATE_TEXT's), resolved (Guardrails::ChiDirs.self_protect).
       def chi_dirs = Guardrails::ChiDirs.self_protect
@@ -184,10 +242,6 @@ module Samagotchi
         word = WORD_END.sub("[", "[^")
         Regexp.new("(?:#{prefixes.join("|")})/memories(?=/|#{WORD_END}|\\z)(?:/#{word}*)?")
       end
-
-      def fetch(hash, key)
-        hash.key?(key) ? hash[key] : hash[key.to_s]
-      end
     end
   end
 end

data/lib/samagotchi/testing/waiting.rb

@@ -108,6 +108,19 @@ module Samagotchi
         value
       end
 
+      # A wall-clock upper bound for "this didn't take the full wait"
+      # (expect(elapsed).to be < time_bound(3, below: 5)): +seconds+ scaled,
+      # so a slow runner gets the headroom a helper's deadline gets, and kept
+      # under +below+, the unscaled deadline (a lib timeout, a hung child's
+      # sleep) the bound tells apart from, so the check still fails on the
+      # full wait whatever SPEC_TIME_SCALE is. A bound with nothing to tell
+      # apart from (a cost: "no quadratic blow-up") takes no +below+.
+      # @return [Float]
+      def time_bound(seconds, below: nil)
+        bound = Waiting.scaled(seconds)
+        below ? [bound, below].min : bound
+      end
+
       # Whether no process +pid+ is left (a killed grandchild is reaped a
       # moment later: wait_for("pid gone") { process_gone?(pid) }). One that
       # isn't ours to signal is still there (ProcessGroup.alive?).

data/lib/samagotchi/toolkit_binding.rb

@@ -155,6 +155,22 @@ module Samagotchi
       true
     end
 
+    # On mode's ask gave the turn no suggestion to judge (Engine
+    # #settle_toolkit_suggestion: a timeout, no answer): say, as a warn
+    # notice, that +session+ runs its default (not once a toolkit was
+    # chosen meanwhile). +why+ is fallback_notice's.
+    def fell_back(session, why)
+      return if session.nil? || session.toolkit_origin != "default"
+
+      @notify.call(self.class.fallback_notice(Toolkit.of(session.toolkit).name, why), :warn, "toolkit", extra: {})
+    end
+
+    # "toolkit: full (no suggestion: System 1 took over 5000 ms) · /toolkit
+    # to change"; +why+ follows "no suggestion: ".
+    def self.fallback_notice(name, why)
+      "toolkit: #{name} (no suggestion: #{why}) · /toolkit to change"
+    end
+
     # "toolkit: smoke (suggested, p=0.71) · /toolkit to change"; a
     # deferred switch says "from this turn".
     def self.suggestion_notice(name, confidence, deferred:)

data/lib/samagotchi/tools/delegate_relay.rb

@@ -192,7 +192,7 @@ module Samagotchi
       # of a relay), else its hook; an approval's call (#what_text).
       # @param question [PendingQuestion] the child's
       def what(question)
-        return what_text(symbolized(question.approval)) unless question.kind.to_s == HOOK_KIND
+        return what_text(Guardrails::ApprovalFacts.from_h(question.approval)) unless question.kind.to_s == HOOK_KIND
 
         inner = symbolized(question.relay, nil)
         header = (inner ? inner[:header] : question.header).to_s
@@ -204,11 +204,12 @@ module Samagotchi
       end
 
       # execute: git push origin main
+      # @param facts [Guardrails::ApprovalFacts, nil] the saved card's
       def what_text(facts)
-        facts = {} unless facts.is_a?(Hash)
-        tool = facts[:label] || facts[:tool] || "tool"
-        what = facts[:command] || Array(facts[:paths]).join(", ")
-        what = facts[:args].to_s if what.to_s.empty?
+        facts ||= Guardrails::ApprovalFacts.new
+        tool = facts.label || facts.tool || "tool"
+        what = facts.command || Array(facts.paths).join(", ")
+        what = facts.args.to_s if what.to_s.empty?
         what.to_s.empty? ? tool.to_s : "#{tool}: #{what}"
       end
 

data/lib/samagotchi/tools/delegate_wait.rb

@@ -337,13 +337,13 @@ module Samagotchi
           "truncated=true",
           "preview_strategy=head_tail",
           "reply_bytes=#{text.bytesize}",
-          "returned_preview_bytes=#{preview[:returned_preview_bytes]}",
-          "omitted_bytes=#{preview[:omitted_bytes]}",
+          "returned_preview_bytes=#{preview.returned_preview_bytes}",
+          "omitted_bytes=#{preview.omitted_bytes}",
           "[TRUNCATED_PREVIEW_HEAD]",
-          preview[:head],
-          "[... omitted #{preview[:omitted_bytes]} bytes ...]",
+          preview.head,
+          "[... omitted #{preview.omitted_bytes} bytes ...]",
           "[TRUNCATED_PREVIEW_TAIL]",
-          preview[:tail]
+          preview.tail
         ].join("\n")
       end
     end

data/lib/samagotchi/tools/execute.rb

@@ -469,13 +469,13 @@ module Samagotchi
           "truncated=true",
           "preview_strategy=head_tail",
           "#{label}_bytes=#{bytes}",
-          "returned_preview_bytes=#{preview[:returned_preview_bytes]}",
-          "omitted_bytes=#{preview[:omitted_bytes]}",
+          "returned_preview_bytes=#{preview.returned_preview_bytes}",
+          "omitted_bytes=#{preview.omitted_bytes}",
           "[TRUNCATED_PREVIEW_HEAD]",
-          preview[:head],
-          "[... omitted #{preview[:omitted_bytes]} bytes ...]",
+          preview.head,
+          "[... omitted #{preview.omitted_bytes} bytes ...]",
           "[TRUNCATED_PREVIEW_TAIL]",
-          preview[:tail]
+          preview.tail
         ].join("\n")
       end
 
@@ -492,7 +492,7 @@ module Samagotchi
       # A big log: its size, and the head and tail read by seek, which
       # output_block shows as it shows a long string's.
       class LogPreview
-        attr_reader :bytesize, :preview
+        attr_reader :bytesize, :preview # Integer, OutputGuardrails::PreviewParts
 
         def initialize(bytesize, preview)
           @bytesize = bytesize

data/lib/samagotchi/tools/output_guardrails.rb

@@ -11,6 +11,11 @@ module Samagotchi
       DEFAULT_TELEMETRY_THRESHOLD_PCT = 80.0
       DEFAULT_CHARS_PER_TOKEN = 4.0
 
+      # A large output's head and tail (UTF-8 safe) with the byte counts the
+      # truncated-preview result lines report.
+      PreviewParts = Data.define(:head, :tail, :head_bytes, :tail_bytes, :returned_preview_bytes,
+                                 :omitted_bytes, :total_bytes)
+
       module_function
 
       # The config setting +key+ (read.*, execute.*, context.*) when positive, else +default+.
@@ -41,6 +46,7 @@ module Samagotchi
              .encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")
       end
 
+      # @return [PreviewParts]
       def head_tail_from_file(path:, file_size:, preview_bytes:)
         half = [preview_bytes / 2, 1].max
         head = File.binread(path, half, 0)
@@ -50,6 +56,7 @@ module Samagotchi
         build_preview_parts(head: head, tail: tail, total_bytes: file_size)
       end
 
+      # @return [PreviewParts]
       def head_tail_from_string(content:, preview_bytes:)
         half = [preview_bytes / 2, 1].max
         head = content.byteslice(0, half) || ""
@@ -78,7 +85,7 @@ module Samagotchi
         tail_bytes = tail.bytesize
         omitted_bytes = [total_bytes - (head_bytes + tail_bytes), 0].max
 
-        {
+        PreviewParts.new(
           head: safe_utf8(head),
           tail: safe_utf8(tail),
           head_bytes: head_bytes,
@@ -86,7 +93,7 @@ module Samagotchi
           returned_preview_bytes: head_bytes + tail_bytes,
           omitted_bytes: omitted_bytes,
           total_bytes: total_bytes
-        }
+        )
       end
       private_class_method :build_preview_parts
     end