samagotchi 0.61.0 → 0.63.0

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -100,14 +100,18 @@ module Samagotchi
       #   (the -p one too) have had their turns; if one failed, #run says so
       # @param children_counts [#call] session id -> its delegates'
       #   ChildrenStatus::Counts, the status row's children segment
+      # @param state_dir [String] the state dir the worker was found in: its
+      #   session folder (@path images, saved records) is under it
       def initialize(client:, screen:, client_id:, first_prompt: nil, first_command: nil, no_interrupt: false,
                      default_input: false, wait_at_eof: false, parent_answers: false,
                      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
                      delete_session: ->(id) { SessionManager.delete_session(id, stop: true, wait: DELETE_WAIT) },
                      archive_session: ->(id) { SessionManager.archive_session(id, wait: DELETE_WAIT) },
                      installed_version: -> { InstalledVersions.new.newest },
-                     children_counts: ->(id) { ChildrenStatus.counts(id, state_dir: Session.default_state_dir) })
+                     state_dir: Session.default_state_dir,
+                     children_counts: ->(id) { ChildrenStatus.counts(id, state_dir: state_dir) })
         @client = client
+        @state_dir = state_dir
         @installed_version = installed_version
         @delete_session = delete_session
         @archive_session = archive_session
@@ -342,7 +346,7 @@ module Samagotchi
         id = @client.session_id
         return :gone if Session.stopped_marker?(id)
 
-        BridgeClient.discover(id, session_dir: Session.session_dir(id), host: @client.host)
+        BridgeClient.discover(id, session_dir: Session.session_dir(id, state_dir: @state_dir), host: @client.host)
       end
 
       # The stream moved to a new worker (a restart): requests go there too.
@@ -683,7 +687,11 @@ module Samagotchi
                   end
         @continue_answer = nil
         @screen.commit(QuestionSlot.continue_summary(outcome, paint: method(:paint))) if outcome && !asked
-        sync_prompt
+        # Back to the > prompt: with the text a question set aside meanwhile
+        # (#close_question), else what the ? read holds.
+        set_aside = @set_aside
+        @set_aside = nil
+        set_aside ? sync_prompt(keep_text: false, prefill: set_aside) : sync_prompt
       end
 
       # The notes slot shows the offer's choices while it waits (a question
@@ -802,7 +810,7 @@ module Samagotchi
         paths = ImageInput.extract(text)
         return [] if paths.empty?
 
-        session_dir = Session.session_dir(@client.session_id)
+        session_dir = Session.session_dir(@client.session_id, state_dir: @state_dir)
         paths.map do |image|
           ref = ImageStore.ingest(session_dir, path: image[:path])
           { file: ref[:file], name: ref[:name] }
@@ -865,7 +873,9 @@ module Samagotchi
 
         @view.finish_thinking_spinner
         # What was typed at the prompt waits for the question to close.
-        @set_aside = @reader&.typed_text unless @question
+        # Not over text already set aside (a question that closed while a
+        # continue offer waits): the ? read holds an answer then, if anything.
+        @set_aside = @reader&.typed_text.to_s.then { |typed| typed.empty? ? nil : typed } unless @question || @set_aside
         @question = QuestionPrompt.new(pending)
         @question_pending = pending
         # The step-limit question stands for the continue offer's own slot
@@ -987,10 +997,14 @@ module Samagotchi
         @screen.clear_slot(:notes)
         @screen.commit(@question.summary(outcome, paint: method(:paint))) if outcome
         @question = nil
+        # A continue offer still waiting keeps the ? prompt (the step-limit
+        # question closes before its offer resolves): the text set aside
+        # waits for the > prompt (#continue_resolved).
+        return sync_continue_slot if @continue_offer
+
         set_aside = @set_aside
         @set_aside = nil
         sync_prompt(keep_text: false, prefill: set_aside)
-        sync_continue_slot if @continue_offer
       end
 
       # Restart the open read when its prompt no longer fits (a question or a
@@ -1195,7 +1209,10 @@ module Samagotchi
         return unless last_user
 
         @screen.commit(join_prompt_line(exchange[last_user]))
-        Array(exchange[last_user][:images]).each { |ref| @screen.commit(format_image_line(ref)) }
+        # An image-only turn's text names its images already.
+        unless ImageRef.placeholder_only?(exchange[last_user][:content])
+          Array(exchange[last_user][:images]).each { |ref| @screen.commit(format_image_line(ref)) }
+        end
         from = messages.index { |m| m.equal?(exchange[last_user]) }
         render_join_steps(messages, from, durations: join_tool_records(exchange[last_user]))
         failed = join_failed_record(exchange[last_user])
@@ -1244,7 +1261,7 @@ module Samagotchi
       # machine's state dir, as #attach_images): none for a prompt with no
       # turn id (an older session) or a session with no analytics.
       def join_tool_records(prompt)
-        SessionMetrics.saved_tool_records(Session.session_dir(@client.session_id), prompt[:turn_id] || prompt["turn_id"])
+        SessionMetrics.saved_tool_records(Session.session_dir(@client.session_id, state_dir: @state_dir), prompt[:turn_id] || prompt["turn_id"])
       rescue Session::InvalidId
         []
       end
@@ -1254,7 +1271,7 @@ module Samagotchi
       # canceled or older turn — or one saved before the failure field —
       # draws its answer as before.
       def join_failed_record(prompt)
-        record = SessionMetrics.saved_turn_record(Session.session_dir(@client.session_id),
+        record = SessionMetrics.saved_turn_record(Session.session_dir(@client.session_id, state_dir: @state_dir),
                                                   prompt[:turn_id] || prompt["turn_id"])
         return nil unless record && record["status"] == "failed" && record["failure"].is_a?(Hash)
 

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -363,7 +363,7 @@ module Samagotchi
 
       # A cancel's reason as the UIs name it (anything else as it is);
       # spec/shared/labels_matrix.json pins it for both.
-      CANCEL_REASONS = { "ctrl_c" => "Ctrl-C", "user" => "stopped", "hook" => "by a hook" }.freeze
+      CANCEL_REASONS = { "ctrl_c" => "Ctrl-C", "user" => "stopped", "hook" => "by a hook", "worker_stopped" => "worker stopped" }.freeze
       # A canceled turn's mark: a stop someone chose (Ctrl-C, Stop, a hook),
       # not an error's ✕ (timing.js STOP_MARK; the labels matrix pins it).
       STOP_MARK = "■"

data/lib/samagotchi/terminal_ui.rb

@@ -121,6 +121,7 @@ module Samagotchi
 
       claim_session!(session_id) if session_id
       @resume_session = session_id ? Session.load(session_id) : nil
+      drop_dead_question(@resume_session) if @resume_session
       if @resume_session
         # --model overrides resumed session's model (runtime only, default unchanged)
         if flag_model_name
@@ -186,7 +187,6 @@ module Samagotchi
         memories: @requested_memories,
         muted_memories: @muted_memory_names,
         appended_prompt_files: @appended_prompt_files,
-        recap: scratch ? nil : recap_config,
         scratch: scratch,
         reminders: {
           callback: lambda { |due_names|
@@ -249,7 +249,8 @@ module Samagotchi
     # post-turn conversation.
     # @return [Symbol, nil] :turn_failed when lines came from a pipe and a
     #   turn failed, :empty_answer when a -p --non-interactive turn ended
-    #   with no answer (bin/chi exits 1 on both), :interrupted when Ctrl-C
+    #   with no answer, :iteration_limit when the iteration limit cut that
+    #   turn short (bin/chi exits 1 on all three), :interrupted when Ctrl-C
     #   cancelled that turn (bin/chi exits 130)
     def run
       # --non-interactive with no --prompt is a harmless no-op exit: build
@@ -309,12 +310,13 @@ module Samagotchi
         # Retry lines and hook notices on stderr; stdout gets the answer below.
         sink = OneShotSink.new
         save_before_first_turn(session)
+        max_iterations = IterationLimit.for(no_interrupt: true)
         begin
           result = @engine.run_turn(
             session,
             one_shot_prompt,
             on_event: sink,
-            max_iterations: IterationLimit.for(no_interrupt: true),
+            max_iterations: max_iterations,
             cancel_controller: nil,
             images: ImageInput.extract(one_shot_prompt)
           )
@@ -337,6 +339,11 @@ module Samagotchi
         session.save
         # The after_turn hooks' notices, after the answer as the REPL shows them.
         sink.flush
+        # The limit cut the turn short: what came so far is no answer, so say
+        # so and fail (bin/chi exits 1), as the REPL's "iteration limit
+        # reached" line does there.
+        return one_shot_exhausted(session, max_iterations) if result.resumable?
+
         return
       end
 
@@ -390,6 +397,16 @@ module Samagotchi
       :turn_failed
     end
 
+    # A -p --non-interactive turn the iteration limit cut short: a line on
+    # stderr, with how to go on unless the session goes with this run.
+    # @return [Symbol] :iteration_limit
+    def one_shot_exhausted(session, max_iterations)
+      line = "chi: the iteration limit (#{max_iterations}) was reached before the turn finished"
+      line += "; continue it with: chi --resume #{session.id}" unless @scratch
+      warn line
+      :iteration_limit
+    end
+
     # `chi -p "/models" --non-interactive`: the command's output; a refused
     # one fails the run (bin/chi exits 1). The session is saved only when
     # the command changed it. Nobody is there to answer a confirm: a
@@ -518,6 +535,17 @@ module Samagotchi
       @pending_card_handle = @engine.subscribe(observer: pending)
     end
 
+    # A question the session's last owner saved and died with (a worker's,
+    # or another REPL's): this TUI owns the session now, so nobody waits on
+    # it. Dropped and saved, as the worker does (Worker#drop_dead_question).
+    def drop_dead_question(session)
+      id = session.drop_dead_question
+      return unless id
+
+      Log.info(:repl, "dead_question_dropped", id: id)
+      session.save
+    end
+
     # Take the session's OwnerLock for this process's lifetime: the TUI runs
     # its own Engine, so no worker may run the session meanwhile.
     # @raise [SessionBusy] when a worker or another TUI owns it
@@ -885,12 +913,35 @@ module Samagotchi
       end
 
       # The REPL keeps the kernel's conversation as-is (no [No response]
-      # placeholder), so /continue resumes from the tool results.
-      session.messages = result.conversation
+      # placeholder), so /continue resumes from the tool results; the
+      # answer keeps what the after_turn hooks stored on it.
+      session.messages = with_answer_display(result.conversation, session.messages)
       @turn_flow.after_turn(result, continue: continue)
       save_session(session)
     end
 
+    # The answer's display keys (Engine#store_answer_display put them on the
+    # session's last message) carried onto +conversation+'s last message,
+    # when that is the same answer; +conversation+ as it is otherwise.
+    ANSWER_DISPLAY_KEYS = [AnswerDisplay::KEY, AnswerRefs::KEY].freeze
+    private_constant :ANSWER_DISPLAY_KEYS
+
+    def with_answer_display(conversation, stored)
+      answer = Array(conversation).last
+      kept = Array(stored).last
+      return conversation unless answer.is_a?(Hash) && kept.is_a?(Hash) && message_field(answer, :role).to_s == "model"
+      return conversation unless message_field(kept, :role).to_s == "model" &&
+                                 message_field(kept, :content) == message_field(answer, :content)
+
+      extra = ANSWER_DISPLAY_KEYS.each_with_object({}) do |key, found|
+        value = message_field(kept, key)
+        found[key] = value unless value.nil?
+      end
+      extra.empty? ? conversation : conversation[0...-1] + [answer.merge(extra)]
+    end
+
+    def message_field(message, key) = message.key?(key) ? message[key] : message[key.to_s]
+
     def save_session(session)
       @engine.store_model!(session)
       session.save
@@ -970,7 +1021,7 @@ module Samagotchi
       end
       canceled = result&.canceled?
       if result && !canceled
-        session.messages = result.conversation if result.conversation.is_a?(Array)
+        session.messages = with_answer_display(result.conversation, session.messages) if result.conversation.is_a?(Array)
         @engine.store_model!(session)
         session.save
       end
@@ -1336,14 +1387,6 @@ module Samagotchi
       Log.debug(:repl, "children_counts_failed", error: e.class.name)
     end
 
-    # Resolve the recap config (on by default). Returns false when explicitly
-    # disabled, nil when nothing is configured, or a Hash when enabled so the
-    # Engine can build the detector. Single precedence path via the Config
-    # registry: CLI > ENV (SAMAGOTCHI_RECAP_*) > file (recap:) > default.
-    def recap_config
-      ConfigFile.recap_config
-    end
-
     # Reset the Engine's shared inactivity clock when a prompt opens (a
     # Reline.pre_input_hook) and on each key typed (RelineSeam.key_handler). This is the
     # single seam the Engine-owned idle recap detector reads, so the idle clock

data/lib/samagotchi/tool_activity.rb

@@ -211,12 +211,16 @@ module Samagotchi
     # "stopped" for a
     # task_wait the user's Stop ended (the task itself runs on), for one
     # whose task was stopped (the stop-task button, or the model's task_stop),
-    # and for a command the user's Stop killed or kept from starting: a
-    # cancel, not a failure (its text still starts "Error:" for the model).
+    # and for a command the user's Stop (or a signal to chi) killed or kept
+    # from starting: a cancel, not a failure (its text still starts "Error:"
+    # for the model).
     def tool_activity_status(result, tool_name = nil, command: nil)
       text = result.to_s
-      return "stopped" if text == Tools::Execute::NOT_RUN_ON_STOP
-      return "stopped" if tool_name == Tools::Execute::NAME && text.start_with?(Tools::Execute::STOPPED_BY_USER)
+      return "stopped" if [Tools::Execute::NOT_RUN_ON_STOP, Tools::Execute::NOT_RUN_ON_SIGNAL].include?(text)
+      if tool_name == Tools::Execute::NAME &&
+         text.start_with?(Tools::Execute::STOPPED_BY_USER, Tools::Execute::STOPPED_BY_SIGNAL)
+        return "stopped"
+      end
       return "error" if text.start_with?("Error:")
       # Still running, as a task: its output tail may hold any "exit: N".
       return "ok" if handed_over?(tool_name, text)

data/lib/samagotchi/tool_response.rb

@@ -9,11 +9,11 @@ module Samagotchi
   # (max_tool_output_chars).
   module ToolResponse
     SEPARATOR = "\n\n---\n\n"
-    # Saved with a result for the web's reload (a plugin tool's params line
-    # and label, an edit/write's diff) and for the LLMContextView (each
+    # Saved with a result for the web's reload (a plugin tool's params line,
+    # label and row refs, an edit/write's diff) and for the LLMContextView (each
     # run's chi-owned id, ToolIds, and a strategy's edits by id,
     # LLMContextEdit); the prompt never renders them.
-    SAVED_KEYS = %i[tool_params tool_labels tool_diffs tool_ids edits].freeze
+    SAVED_KEYS = %i[tool_params tool_labels tool_diffs tool_refs tool_ids edits].freeze
     # A run's "[name]" lead: the name, then a newline, a space or the end.
     LEAD = /\A\[([^\]\s]+)\](?:\n| |\z)/
 
@@ -60,7 +60,7 @@ module Samagotchi
         entry[:image_counts] = runs.map { |run| Array(run[:images]).size }
       end
       saved = { tool_params: runs.map { |run| run[:shown_params] }, tool_labels: runs.map { |run| run[:shown_label] },
-                tool_diffs: runs.map { |run| run[:diff] } }
+                tool_diffs: runs.map { |run| run[:diff] }, tool_refs: runs.map { |run| run[:refs] } }
       saved.each { |key, values| entry[key] = values if values.any? }
       entry[:tool_ids] = ids
       entry
@@ -75,6 +75,7 @@ module Samagotchi
       entry[:tool_params] = run[:shown_params] if run[:shown_params]
       entry[:tool_labels] = run[:shown_label] if run[:shown_label]
       entry[:tool_diffs] = run[:diff] if run[:diff]
+      entry[:tool_refs] = run[:refs] if run[:refs]
       entry[:tool_ids] = ids
       entry
     end

data/lib/samagotchi/tool_row_fields.rb

@@ -16,13 +16,15 @@ module Samagotchi
   #   tool_call_completed (ToolActivity.tool_activity_event builds that
   #   activity itself, for the TUI and the metrics);
   # * EVENT_KEYS: top-level on both, so a UI that missed the start (a
-  #   replay gap) builds its row from the completed event.
+  #   replay gap) builds its row from the completed event. +refs+ (a
+  #   plugin tool's, RowRefs) is one, but ToolRunner adds it: #for has no
+  #   plugins, so a reload reads the saved tool_refs instead.
   #
   # params and label stay where they are: their sources differ per path
   # (the registry's preview, a plugin's label, the saved shown params).
   module ToolRowFields
     ACTIVITY_KEYS = %i[title called_as].freeze
-    EVENT_KEYS = %i[view ref].freeze
+    EVENT_KEYS = %i[view ref refs].freeze
     KEYS = (ACTIVITY_KEYS + EVENT_KEYS).freeze
 
     module_function

data/lib/samagotchi/tool_runner.rb

@@ -2,6 +2,7 @@
 
 require_relative "tool_activity"
 require_relative "tool_row_fields"
+require_relative "row_refs"
 require_relative "guardrails"
 require_relative "vision_context"
 require_relative "log"
@@ -41,7 +42,8 @@ module Samagotchi
     #   shown_params: the params line the live row showed, and shown_label:
     #   its label ("chrome: screenshot"), only for a tool that isn't built in
     #   (the loops save them with the result, so a reload without the plugin
-    #   shows the same row), and diff: what an edit/write changed in its
+    #   shows the same row), refs: its row's refs (a plugin tool's refs:,
+    #   RowRefs; saved likewise), and diff: what an edit/write changed in its
     #   file (EditPreview.change; also on tool_call_completed, never in the
     #   model's output)
     def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
@@ -55,9 +57,12 @@ module Samagotchi
       started = { type: :tool_call_started, iteration: iteration, call_count: call_count, call_index: call_index,
                   tool: call[:name], call: call.dup, params: params }
       started[:label] = label if label
-      # Its row fields (ToolRowFields: title, called_as, view, ref); the worker runs in
-      # its session's working directory.
+      # Its row fields (ToolRowFields: title, called_as, view, ref, and a
+      # plugin tool's refs); the worker runs in its session's working
+      # directory.
       fields = ToolRowFields.for(call[:name], call, cwd: Dir.pwd)
+      refs = RowRefs.for(tools && !call[:name].nil? ? tools[call[:name]]&.refs : nil, call, cwd: session_cwd)
+      fields[:refs] = refs unless refs.empty?
       started.merge!(fields)
       emit(on_stream_event, started)
 
@@ -121,6 +126,7 @@ module Samagotchi
       run[:images] = images if images&.any?
       run[:shown_params] = params if params && plugin_tool?(call[:name])
       run[:shown_label] = label if label
+      run[:refs] = refs unless refs.empty?
       run[:diff] = diff if diff
       run
     end
@@ -249,6 +255,13 @@ module Samagotchi
       [result[:output], *notes].join("\n")
     end
 
+    # The session's folder (the Engine's, KernelLoop#session_cwd), else the
+    # process's: a bare kernel (specs) has none.
+    def session_cwd
+      cwd = @kernel.respond_to?(:session_cwd) && @kernel.session_cwd&.call
+      cwd.to_s.empty? ? Dir.pwd : cwd
+    end
+
     # The kernel's tools, for the activity line of a tool that isn't built in.
     def tools = @kernel.tools
 

data/lib/samagotchi/tools/builtins.rb

@@ -77,7 +77,7 @@ module Samagotchi
                     start_line: call[:start_line], end_line: call[:end_line])
         end,
         TaskCreate::NAME => lambda do |call, kctx|
-          next Execute::NOT_RUN_ON_STOP if cancelled_proc(kctx).call
+          next Execute.not_run(stop_reason_proc(kctx)) if cancelled_proc(kctx).call
 
           TaskCreate.call(call[:content], cwd: call[:cwd], env: call[:env],
                           marker_env: task_marker_env(kctx, call[:env]))
@@ -87,7 +87,8 @@ module Samagotchi
                                         done_pattern: call[:done_pattern], cancelled: cancelled_proc(kctx))
         end,
         Execute::NAME => lambda do |call, kctx|
-          Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx), env: parent_env(kctx))
+          Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx), stop_reason: stop_reason_proc(kctx),
+                                       env: parent_env(kctx))
         end,
         RegisterReminder::NAME => lambda do |call, kctx|
           RegisterReminder.call(call[:content], reminder_store: kctx.reminder_store, description: call[:description],
@@ -163,6 +164,12 @@ module Samagotchi
         -> { !!peers&.cancelled? }
       end
 
+      # The running turn's stop reason (:signal, :manual, …), nil without one.
+      def stop_reason_proc(kctx)
+        peers = kctx.peers
+        -> { peers.respond_to?(:cancel_reason) ? peers.cancel_reason : nil }
+      end
+
       # @param command_description [Boolean] false: execute declares no
       #   description parameter (execute.description off)
       # @param policy [String, nil] llm_context.policy, the sentence

data/lib/samagotchi/tools/execute.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require_relative "../config"
+require_relative "../log"
 require_relative "../paths"
 require_relative "../process_group"
 require_relative "output_guardrails"
@@ -27,6 +28,10 @@ module Samagotchi
       NOT_RUN_ON_STOP = "Error: not run, the user stopped the turn"
       # The first words of a command the user's Stop killed.
       STOPPED_BY_USER = "Error: command stopped by the user"
+      # The same two when a signal to chi (a worker's TERM, HUP or INT)
+      # stopped the turn: its cancel reason is :signal.
+      NOT_RUN_ON_SIGNAL = "Error: not run, a signal to chi stopped the turn"
+      STOPPED_BY_SIGNAL = "Error: command stopped by a signal to chi"
       # The first words of a command killed at the limit in kill mode (hooks
       # match on it).
       TIMEOUT_PREFIX = "Error: command timed out after"
@@ -73,11 +78,13 @@ module Samagotchi
 
       # @param cancelled [#call] true once the user stopped the turn: the
       #   command is killed (or not started) and its output so far returned
+      # @param stop_reason [#call] the stop's reason (:signal: a signal to
+      #   chi, which the result then names instead of the user)
       # @param env [Hash, nil] added to the command's environment
       # @param on_timeout [Symbol, String, nil] :task or :kill (ON_TIMEOUT);
       #   nil reads execute.on_timeout
-      def self.call(command, cwd: nil, cancelled: -> { false }, env: nil, on_timeout: nil)
-        return NOT_RUN_ON_STOP if cancelled.call
+      def self.call(command, cwd: nil, cancelled: -> { false }, stop_reason: -> {}, env: nil, on_timeout: nil)
+        return not_run(stop_reason) if cancelled.call
 
         command = command.strip
         resolved_cwd = resolve_cwd(cwd)
@@ -109,11 +116,17 @@ module Samagotchi
         # a long command, and return whatever it printed before it was killed.
         stopped_result("#{TIMEOUT_PREFIX} #{timeout_sec}s\n#{TIMEOUT_HINT}", e)
       rescue CommandCancelled => e
-        stopped_result("#{STOPPED_BY_USER} after #{e.elapsed.round}s (killed; rerun it if still needed)", e)
+        first = signal?(stop_reason) ? STOPPED_BY_SIGNAL : STOPPED_BY_USER
+        stopped_result("#{first} after #{e.elapsed.round}s (killed; rerun it if still needed)", e)
       rescue StandardError => e
         "Error: #{e.message}"
       end
 
+      # What a command the turn's stop kept from starting returns.
+      def self.not_run(stop_reason) = signal?(stop_reason) ? NOT_RUN_ON_SIGNAL : NOT_RUN_ON_STOP
+
+      def self.signal?(stop_reason) = stop_reason.call == :signal
+
       # execute.on_timeout, or the caller's: :task (the default) or :kill.
       def self.on_timeout_mode(value)
         value = Samagotchi::Config.get("execute.on_timeout") if value.nil? || value.to_s.strip.empty?
@@ -157,10 +170,14 @@ module Samagotchi
         exit_code_path = File.join(dir, TaskRuntime::EXIT_CODE_FILENAME)
         begin
           pid = spawn_logged(command, env: env, cwd: cwd, logs: logs, exit_code_path: exit_code_path)
-        rescue StandardError
+        rescue StandardError => e
+          Log.info(:turn, "execute_spawn_failed", id: id, error: e.class.name)
           FileUtils.rm_rf(dir)
           raise
         end
+        # Never the command line or its output: a command may carry a
+        # secret, and its output is the tool result's.
+        Log.debug(:turn, "execute_started", id: id, pid: pid, timeout_sec: timeout_sec, on_timeout: on_timeout)
         wait_thr = Process.detach(pid)
         # A stop is done once the shell is reaped and nothing holds the logs:
         # a child that ignores TERM keeps them, so the stop goes on to KILL.
@@ -183,6 +200,7 @@ module Samagotchi
                              timeout_sec: timeout_sec, dir: dir, logs: logs, exit_code_path: exit_code_path)
             if text
               handed_over = true
+              Log.info(:turn, "execute_handed_over", id: id, after_sec: timeout_sec)
               raise HandedOver, text
             end
             # Not adopted because it ended meanwhile: finished too.
@@ -193,10 +211,11 @@ module Samagotchi
           status = wait_thr.value
         rescue HandedOver
           raise
-        rescue Exception # rubocop:disable Lint/RescueException -- kill the child, then re-raise
+        rescue Exception => e # rubocop:disable Lint/RescueException -- kill the child, then re-raise
           # An Interrupt (or anything else) mid-wait: the child is in its own
           # process group, so it never saw the SIGINT. Kill it.
           aborted = true
+          Log.info(:turn, "execute_aborted", id: id, error: e.class.name)
           terminate_process_tree(pid, stopped: stopped) if wait_thr.alive?
           raise
         ensure
@@ -218,9 +237,18 @@ module Samagotchi
           end
         end
 
-        raise CommandTimedOut.new(stdout_text, stderr_text) if timed_out
-        raise CommandCancelled.new(stdout_text, stderr_text, monotonic_time - started) if was_cancelled
+        elapsed_ms = ((monotonic_time - started) * 1000).round
+        if timed_out
+          Log.info(:turn, "execute_timed_out", id: id, after_sec: timeout_sec)
+          raise CommandTimedOut.new(stdout_text, stderr_text)
+        end
+        if was_cancelled
+          Log.info(:turn, "execute_stopped", id: id, ms: elapsed_ms)
+          raise CommandCancelled.new(stdout_text, stderr_text, monotonic_time - started)
+        end
 
+        Log.debug(:turn, "execute_finished", id: id, exit: status&.exitstatus, ms: elapsed_ms,
+                                             background: held_open || nil)
         [stdout_text, stderr_text, status, held_open]
       end
       private_class_method :run_command
@@ -336,6 +364,8 @@ module Samagotchi
           Thread.current.report_on_exception = false
           code = waiter.value&.exitstatus
           File.write(path, code.to_s) if code && !File.exist?(path) && Dir.exist?(File.dirname(path))
+        rescue StandardError => e
+          Log.debug(:turn, "execute_exit_code_failed", error: e.class.name, msg: e.message)
         end
       end
       private_class_method :write_missing_exit_code

data/lib/samagotchi/tools/peers.rb

@@ -10,11 +10,12 @@ module Samagotchi
     # can't host one), and the model the session runs on (model_ref: the
     # resolved ref, live after /model), and the session's own thinking level
     # (thinking: nil without one) and reasoning_history level
-    # (reasoning_history: nil without one). Engine hands KernelLoop one that follows its current
+    # (reasoning_history: nil without one), and why the turn was canceled
+    # (cancel_reason: :signal, :manual, …; nil while it runs). Engine hands KernelLoop one that follows its current
     # session (Engine::PeerView); this plain one is for specs and a kernel
     # without an Engine.
     Peers = Struct.new(:session_id, :cwd, :state_dir, :cancelled, :relay, :model_ref, :thinking, :reasoning_history,
-                       keyword_init: true) do
+                       :cancel_reason, keyword_init: true) do
       # @return [Boolean] the turn was canceled (:cancelled is a proc or a value)
       def cancelled?
         cancelled.respond_to?(:call) ? !!cancelled.call : !!cancelled

data/lib/samagotchi/tools/registry.rb

@@ -20,11 +20,13 @@ module Samagotchi
       #   tool" when nil); ToolActivity knows the built-ins' own
       # @!attribute preview [#call, nil] call → the activity line's params
       # @!attribute targets [#call, nil] call → what guardrail rules match
+      # @!attribute refs [#call, nil] call → the row's refs (a plugin's
+      #   refs:, RowRefs checks what it gives)
       # @!attribute source [String] "core", or the bundle that added it
       # @!attribute layer [Symbol, nil] the LLM context layer the tool
       #   belongs to (LLMContextStrategy): offered only in a turn running
       #   under it (forget_outputs, :forget); nil: always
-      Entry = Struct.new(:name, :schema, :handler, :label, :preview, :targets, :source, :layer, keyword_init: true) do
+      Entry = Struct.new(:name, :schema, :handler, :label, :preview, :targets, :refs, :source, :layer, keyword_init: true) do
         def core? = source == "core"
 
         # Offered in a turn under +layers+ (the turn's LLM context layers).
@@ -36,11 +38,11 @@ module Samagotchi
       end
 
       # @return [Entry]
-      def register(name, schema:, handler:, label: nil, preview: nil, targets: nil, source: "core", layer: nil)
+      def register(name, schema:, handler:, label: nil, preview: nil, targets: nil, refs: nil, source: "core", layer: nil)
         raise ArgumentError, "tool #{name} is already registered" if @entries.key?(name)
 
         @entries[name] = Entry.new(name: name, schema: schema, handler: handler, label: label, preview: preview,
-                                   targets: targets, source: source, layer: layer)
+                                   targets: targets, refs: refs, source: source, layer: layer)
       end
 
       # Remove a tool (a plugin's tool set changed after load).

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.61.0"
+  VERSION = "0.63.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end