samagotchi 0.90.0 → 0.92.0

data/lib/samagotchi/testing/bundle.rb

@@ -11,6 +11,7 @@ require_relative "../peer_sources"
 require_relative "../toolkit"
 require_relative "../guardrails/gate"
 require_relative "../memory_bundle/manifest"
+require_relative "../memory_bundle/source"
 require_relative "../session_setup"
 require_relative "sandbox"
 require_relative "recorder"
@@ -69,7 +70,7 @@ module Samagotchi
     # raises HookFailed after the call (chi would log it and go on);
     # #lenient collects them in #errors instead.
     class Bundle
-      SHIPPED_DIR = File.expand_path("../bundles", __dir__)
+      SHIPPED_DIR = MemoryBundle::SourceNormalizer::SHIPPED_DIR
 
       class << self
         # @param dir [String] the bundle's folder (its manifest.yml)
@@ -88,6 +89,20 @@ module Samagotchi
 
         # A bundle chi ships (lib/samagotchi/bundles/<name>), as #load.
         def shipped(name, **) = load(File.join(SHIPPED_DIR, name.to_s), **)
+
+        # Registries as an Engine's start: chi's built-in commands and
+        # tools, empty services, toolkits, tool index and peer sources;
+        # +fields+ set the rest (hooks:, context_for:, init: ...) or replace
+        # these. Bundle#build_registries and Install's load both start here.
+        # @api private
+        # @return [Plugin::Registries]
+        def registries(**fields)
+          Plugin::Registries.new(
+            commands: SessionCommands.register_builtins(Commands::Registry.new), tools: Tools::Builtins.registry,
+            services: Plugin::Services.new, stage_tools: ->(*) {}, toolkits: [], tool_index: Tools::ToolIndex.new,
+            peer_sources: PeerSources.new, **fields
+          )
+        end
       end
 
       # @return [String] the bundle's name (manifest.yml)
@@ -132,6 +147,13 @@ module Samagotchi
         own = session_settings.nil? || session_settings.empty? ? {} : { setup: setup_with(session_settings, host[:setup]) }
         @own_sandbox = sandbox.nil? && Sandbox.current.nil?
         @sandbox = sandbox || Sandbox.current || Sandbox.enter
+        build(host, own)
+      rescue Exception # rubocop:disable Lint/RescueException -- leave the sandbox it entered, whatever failed
+        @sandbox.leave if @own_sandbox && @sandbox
+        raise
+      end
+
+      def build(host, own)
         @recorder = Recorder.new(cwd: @sandbox.work_dir, **host, **own)
         @sessions = Sessions.new
         @http = FakeHttp.new
@@ -143,6 +165,7 @@ module Samagotchi
         @contexts = {}
         @registries = build_registries
       end
+      private :build
 
       # @api private (Bundle.load)
       def load!
@@ -349,28 +372,22 @@ module Samagotchi
       private
 
       def build_registries
-        builtin_tools = Tools::Builtins.registry
         toolkits = []
         host = Host.build(@recorder, toolkits: -> { Toolkit::BUILTIN_KITS.keys + toolkits.map(&:name) },
                                      tool_names: -> { @registries.tools.names })
-        Plugin::Registries.new(
-          commands: SessionCommands.register_builtins(Commands::Registry.new),
-          tools: builtin_tools,
+        Bundle.registries(
           hooks: Hooks::Registry.new.tap { |registry| registry.runtime = Runtime.build(@recorder) },
           context_for: lambda { |bundle, settings, label|
             @contexts[label] = Plugin::Context.new(bundle: bundle, label: label, settings: settings, host: host,
                                                    env: ENV, sessions: @sessions, http_transport: @http)
           },
           tools_changed: -> { @tools_changes += 1 },
-          services: Plugin::Services.new,
           stage_tools: ->(_bundle, specs, context) { @staged_tools << StagedTools.new(specs: specs, context: context) },
           init: lambda { |_bundle, label, plugin_label, provides_tools:, quiet:, timeout:, failed: nil, &block|
             @inits << Init.new(label: label, plugin_label: plugin_label, provides_tools: provides_tools, quiet: quiet,
                                timeout: timeout, failed: failed, block: block)
           },
-          toolkits: toolkits,
-          tool_index: Tools::ToolIndex.new,
-          peer_sources: PeerSources.new
+          toolkits: toolkits
         )
       end
 
@@ -388,21 +405,17 @@ module Samagotchi
 
       # +setup+ (the recorder's, nil for none) with +session_settings+ as
       # this bundle's own values, checked against the manifest's
-      # session_settings: as chi --set checks them.
-      # @raise [ArgumentError] a key the manifest doesn't list
+      # session_settings: (keys and types) as chi --set checks them.
+      # @raise [ArgumentError] a key the manifest doesn't list, or a value
+      #   of another type than it gives the key
       def setup_with(session_settings, setup)
         values = { @name => stringify(session_settings) }
-        BundleSessionSettings.check!(values, bundles: { @name => @manifest.session_settings }, flag: "session_settings")
+        BundleSessionSettings.check!(values, bundles: { @name => @manifest.session_settings },
+                                             types: { @name => @manifest.session_setting_types }, flag: "session_settings")
         (setup || SessionSetup.new).with(bundle_settings: values)
       end
 
-      def stringify(value)
-        case value
-        when Hash then value.to_h { |key, item| [key.to_s, stringify(item)] }
-        when Array then value.map { |item| stringify(item) }
-        else value
-        end
-      end
+      def stringify(value) = Sandbox.stringify(value)
     end
   end
 end

data/lib/samagotchi/testing/install.rb

@@ -19,16 +19,24 @@ module Samagotchi
     # failed names the bundle's source files, not the installed copies.
     #
     #   result = Samagotchi::Testing::Install.run("path/to/bundle", settings: { "every" => 3 })
-    #   result.warnings, result.plugin_failures, result.hook_failures, result.registered[:commands]
+    #   result.warnings, result.plugin_failures, result.hook_failures, result.registered.commands
     module Install
       # warnings: the Installer's; plugin_failures / hook_failures:
       # [Guardrails::LoadFailures::Failure] of this bundle, each location
       # in the source dir; registered: what it registered (#registered).
       Result = Data.define(:name, :warnings, :plugin_failures, :hook_failures, :registered) do
         def failures = plugin_failures + hook_failures
-        def ok? = failures.empty?
       end
 
+      # What a bundle registered (#registered): commands, tools (names),
+      # hooks per event, inits (labels), toolkits, tool sources and peer
+      # sources (names).
+      Registered = Data.define(:commands, :tools, :hooks, :inits, :toolkits, :tool_sources, :peer_sources)
+      # A command: its mid_turn policy and its selection-bar labels (chi.annotation).
+      Command = Data.define(:name, :mid_turn, :labels)
+      # A hook on an event: the bundle, the hook (its file, or the plugin's) and its priority.
+      Hook = Data.define(:bundle, :hook, :priority)
+
       module_function
 
       # Install the bundle at +dir+ into +sandbox+ (default Sandbox.current,
@@ -57,15 +65,12 @@ module Samagotchi
         hook_failures = Guardrails::LoadFailures.new
         plugin_failures = Guardrails::LoadFailures.new
         extension = ExtensionLoad.new(hook_failures: hook_failures)
-        registries = Plugin::Registries.new(
-          commands: SessionCommands.register_builtins(Commands::Registry.new),
-          tools: Tools::Builtins.registry, hooks: extension.hooks,
+        registries = Bundle.registries(
+          hooks: extension.hooks,
           context_for: lambda { |bundle, bundle_settings, label|
             Plugin::Context.new(bundle: bundle, label: label, settings: bundle_settings, host: host)
           },
-          services: Plugin::Services.new, stage_tools: ->(*) {},
-          init: ->(_bundle, label, _plugin_label, **, &_block) { inits << { label: label } },
-          toolkits: [], tool_index: Tools::ToolIndex.new, peer_sources: PeerSources.new
+          init: ->(_bundle, label, _plugin_label, **, &_block) { inits << { label: label } }
         )
         extension.load_plugins(registries, failures: plugin_failures)
         installed = File.join(MemoryBundle::Provenance.bundles_dir, name)
@@ -79,26 +84,30 @@ module Samagotchi
       private_class_method :load_installed
 
       # What bundle +name+ registered, from the registries it loaded into:
-      # commands ([name, mid_turn, annotation labels]), tools, hooks per
-      # event ([bundle, hook, priority]; Hooks::EVENTS, then any other event
-      # the bundle registered for), inits, toolkits, tool sources and
-      # peer sources.
+      # hooks per event are Hooks::EVENTS, then any other event the bundle
+      # registered for.
       # @param inits [Array<Hash>] {label:} of each chi.init
-      # @return [Hash]
+      # @return [Registered]
       def registered(registries, name, inits)
-        {
-          commands: registries.commands.entries.select { |e| e.source == name }.map { |e| [e.name, e.mid_turn, e.annotations.map(&:label)] },
+        Registered.new(
+          commands: registries.commands.entries.select { |e| e.source == name }.map do |e|
+            Command.new(name: e.name, mid_turn: e.mid_turn, labels: e.annotations.map(&:label))
+          end,
           tools: registries.tools.by_source(name).map(&:name),
           hooks: hooks_of(registries.hooks, name),
           inits: inits.map { |init| init[:label] },
           toolkits: Array(registries.toolkits).map(&:name),
           tool_sources: registries.tool_index.sources.map(&:label),
           peer_sources: registries.peer_sources.names
-        }
+        )
       end
 
       def hooks_of(hooks, name)
-        own = ->(event) { hooks.bundle_hook_names(event).select { |bundle, _, _| bundle == name } }
+        own = lambda do |event|
+          hooks.bundle_hook_names(event).filter_map do |bundle, hook, priority|
+            Hook.new(bundle: bundle, hook: hook, priority: priority) if bundle == name
+          end
+        end
         others = (hooks.bundle_events - Hooks::EVENTS).to_h { |event| [event, own.call(event)] }.reject { |_, list| list.empty? }
         Hooks::EVENTS.to_h { |event| [event, own.call(event)] }.merge(others)
       end

data/lib/samagotchi/testing/sandbox.rb

@@ -5,6 +5,7 @@ require "tmpdir"
 require "yaml"
 require_relative "../log"
 require_relative "../paths"
+require_relative "../sandbox_layout"
 require_relative "fake_executable"
 
 module Samagotchi
@@ -38,7 +39,16 @@ module Samagotchi
           sandbox&.leave
         end
 
+        # +value+ with every Hash key a String, as config.yml and a
+        # handler's args read (Bundle uses it too).
         # @api private
+        def stringify(value)
+          case value
+          when Hash then value.to_h { |key, item| [key.to_s, stringify(item)] }
+          when Array then value.map { |item| stringify(item) }
+          else value
+          end
+        end
       end
 
       # @return [String] the temp folder holding everything
@@ -55,31 +65,16 @@ module Samagotchi
       def enter
         raise ArgumentError, "the sandbox was entered already" if @root
 
-        @root = File.realpath(Dir.mktmpdir("chi-bundle-test-"))
-        @saved = ENV.to_h
-        @outer = Sandbox.current
-        ENV.each_key.select { |key| key.start_with?("SAMAGOTCHI_") && !KEPT.include?(key) }.each { |key| ENV.delete(key) }
-        %w[config state data cache home work bin].each { |dir| FileUtils.mkdir_p(File.join(@root, dir)) }
-        File.write(File.join(@root, "gitconfig"), "")
-        ENV.update(
-          "HOME" => File.join(@root, "home"),
-          "XDG_CONFIG_HOME" => File.join(@root, "config"),
-          "XDG_STATE_HOME" => File.join(@root, "state"),
-          "XDG_DATA_HOME" => File.join(@root, "data"),
-          "XDG_CACHE_HOME" => File.join(@root, "cache"),
-          "CLAUDE_CONFIG_DIR" => File.join(@root, "home", ".claude"),
-          "CODEX_HOME" => File.join(@root, "home", ".codex"),
-          "GIT_CONFIG_GLOBAL" => File.join(@root, "gitconfig"),
-          "GIT_CONFIG_NOSYSTEM" => "1",
-          "SAMAGOTCHI_KEYCHAIN" => "off",
-          "SAMAGOTCHI_ENV" => "test",
-          "SAMAGOTCHI_RECAP_ENABLED" => "false",
-          "SAMAGOTCHI_CACHE_WARMUP" => "off",
-          "PATH" => [bin_dir, ENV.fetch("PATH", nil)].compact.join(File::PATH_SEPARATOR)
-        )
-        # The log resolves its file from the (now temp) state home.
-        Log.reset!
-        Sandbox.current = self
+        layout = SandboxLayout.create("chi-bundle-test-", extra: %w[data cache home bin])
+        begin
+          @root = layout.root
+          @saved = ENV.to_h
+          @outer = Sandbox.current
+          point_env(layout)
+        rescue Exception # rubocop:disable Lint/RescueException -- put ENV back, whatever failed
+          leave
+          raise
+        end
         self
       end
 
@@ -87,7 +82,7 @@ module Samagotchi
       def leave
         return unless @root
 
-        ENV.replace(@saved)
+        ENV.replace(@saved) if @saved
         Log.reset!
         FileUtils.rm_rf(@root)
         Sandbox.current = @outer
@@ -97,10 +92,7 @@ module Samagotchi
       # Write config.yml (what Config.get reads): a Hash or YAML text.
       # @return [String] its path
       def config(data)
-        path = File.join(Paths.config_home, Paths::APP_DIR, "config.yml")
-        FileUtils.mkdir_p(File.dirname(path))
-        File.write(path, data.is_a?(String) ? data : YAML.dump(stringify(data)))
-        path
+        SandboxLayout.new(@root).write_config(data.is_a?(String) ? data : stringify(data), config_home: Paths.config_home)
       end
 
       # @return [String] $XDG_STATE_HOME/samagotchi (ctx.data_dir's parent)
@@ -145,6 +137,28 @@ module Samagotchi
 
       private
 
+      # ENV at +layout+'s folders, none of the SAMAGOTCHI_* settings but KEPT.
+      def point_env(layout)
+        ENV.each_key.select { |key| key.start_with?("SAMAGOTCHI_") && !KEPT.include?(key) }.each { |key| ENV.delete(key) }
+        File.write(File.join(@root, "gitconfig"), "")
+        ENV.update(
+          **layout.env,
+          "HOME" => File.join(@root, "home"),
+          "XDG_DATA_HOME" => File.join(@root, "data"),
+          "XDG_CACHE_HOME" => File.join(@root, "cache"),
+          "CLAUDE_CONFIG_DIR" => File.join(@root, "home", ".claude"),
+          "CODEX_HOME" => File.join(@root, "home", ".codex"),
+          "GIT_CONFIG_GLOBAL" => File.join(@root, "gitconfig"),
+          "GIT_CONFIG_NOSYSTEM" => "1",
+          "SAMAGOTCHI_KEYCHAIN" => "off",
+          "SAMAGOTCHI_ENV" => "test",
+          "PATH" => [bin_dir, ENV.fetch("PATH", nil)].compact.join(File::PATH_SEPARATOR)
+        )
+        # The log resolves its file from the (now temp) state home.
+        Log.reset!
+        Sandbox.current = self
+      end
+
       # Run the block with +dir+ as the process's cwd (the memory tools
       # read the project from it); nil: as it is.
       def in_dir(dir, &)
@@ -153,13 +167,7 @@ module Samagotchi
         Dir.chdir(dir, &)
       end
 
-      def stringify(value)
-        case value
-        when Hash then value.to_h { |key, item| [key.to_s, stringify(item)] }
-        when Array then value.map { |item| stringify(item) }
-        else value
-        end
-      end
+      def stringify(value) = Sandbox.stringify(value)
     end
   end
 end

data/lib/samagotchi/testing/waiting.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../process_group"
+
 module Samagotchi
   module Testing
     # Waiting with a deadline, for a test that waits on a thread or a
@@ -24,13 +26,9 @@ module Samagotchi
       end
 
       # Whether no process +pid+ is left (a killed grandchild is reaped a
-      # moment later: wait_until { process_gone?(pid) }).
-      def process_gone?(pid)
-        Process.kill(0, pid)
-        false
-      rescue Errno::ESRCH
-        true
-      end
+      # moment later: wait_until { process_gone?(pid) }). One that isn't
+      # ours to signal is still there (ProcessGroup.alive?).
+      def process_gone?(pid) = !ProcessGroup.alive?(pid)
     end
   end
 end

data/lib/samagotchi/tool_declarations.rb

@@ -518,6 +518,22 @@ module Samagotchi
 
     GEMMA_QUOTE = '<|"|>'
 
+    # What a worker's finish wake (session.task_wakes not off) lets the
+    # model know: a task it leaves running is reported when it ends.
+    TASK_FINISH_LINE = "if you end your turn before it finishes, chi tells you when it does."
+
+    # +schema+ with TASK_FINISH_LINE in execute's hand-over sentence and at
+    # task_create's end; any other schema as given.
+    def with_task_finish_line(schema)
+      case schema[:name]
+      when "execute"
+        schema.merge(description: schema[:description].sub("and task_wait waits for it.",
+                                                           "and task_wait waits for it; #{TASK_FINISH_LINE}"))
+      when "task_create" then schema.merge(description: "#{schema[:description]} #{TASK_FINISH_LINE.sub(/\Ai/, "I")}")
+      else schema
+      end
+    end
+
     # +schema+ without execute's description property: what a session
     # with execute.description off declares (the parameter isn't offered
     # at all). Any other schema as given.

data/lib/samagotchi/tool_response.rb

@@ -28,20 +28,42 @@ module Samagotchi
 
     # Runs +calls+ in order (ToolRunner#run each), yielding each run and its
     # index as it finishes. +emit+ takes the dispatch events, the runner's
-    # own go to +on_stream_event+.
+    # own go to +on_stream_event+. An Interrupt (Ctrl-C) mid-batch yields an
+    # #interrupted run for every call left (the one it cut short too), so
+    # the loop's conversation answers each call, then goes on up: the turn
+    # keeps its progress (Engine#ctrl_c_messages).
     # @return [Array<ToolRun>] the runs
     def run_batch(runner, calls, iteration:, emit:, on_stream_event:, cap:)
+      # Before anything can be interrupted: the rescue counts it.
+      runs = []
       emit.call({ type: :tool_dispatch_started, iteration: iteration, call_count: calls.length })
-      runs = calls.each_with_index.map do |call, index|
-        run = runner.run(call, iteration: iteration, call_index: index + 1, call_count: calls.length,
-                               on_stream_event: on_stream_event, max_tool_output_chars: cap)
-        yield run, index if block_given?
-        run
+      calls.each_with_index do |call, index|
+        runs << runner.run(call, iteration: iteration, call_index: index + 1, call_count: calls.length,
+                                 on_stream_event: on_stream_event, max_tool_output_chars: cap)
+        yield runs.last, index if block_given?
       end
       emit.call({ type: :tool_dispatch_completed, iteration: iteration, call_count: calls.length })
       runs
+    rescue Interrupt
+      calls.each_with_index.drop(runs.size).each { |call, index| yield interrupted(call[:name]), index } if block_given?
+      raise
     end
 
+    # The result of a call an Interrupt cut short (or never started): the
+    # model reads that it may have partly run.
+    def interrupted(name)
+      text = interrupted_text(name)
+      ToolRun.new(output: text, capped_output: text)
+    end
+
+    INTERRUPTED = "Interrupted (Ctrl-C) before it returned: it may have partly run."
+
+    def interrupted_text(name) = "[#{name}] #{INTERRUPTED}"
+
+    # Whether +content+ is an #interrupted result, whatever tool it names
+    # (an aliased call's saved name is the model's, the text the tool's).
+    def interrupted_text?(content) = content.to_s.match?(/\A\[[^\]\s]+\] #{Regexp.escape(INTERRUPTED)}\z/)
+
     # The runs' activity, for the turn's tool list (none for a call whose
     # dispatcher raised).
     def activities(runs)

data/lib/samagotchi/tools/builtins.rb

@@ -185,13 +185,17 @@ module Samagotchi
       #   description parameter (execute.description off)
       # @param policy [String, nil] llm_context.policy, the sentence
       #   forget_outputs' description carries
+      # @param task_finish_notes [Boolean] a worker's session whose finish
+      #   wake reports a task left running (session.task_wakes not off):
+      #   execute and task_create say so (ToolDeclarations::TASK_FINISH_LINE)
       # @return [Registry] a new registry with the built-ins, in
       #   TOOL_SCHEMAS order (an Engine's own, which bundles add to), then
       #   forget_outputs, offered only under the forget layer
-      def registry(command_description: true, policy: ToolDeclarations::FORGET_OUTPUTS_POLICY)
+      def registry(command_description: true, policy: ToolDeclarations::FORGET_OUTPUTS_POLICY, task_finish_notes: false)
         by_name = CLASSES.to_h { |klass| [klass::NAME, klass] }
         registry = ToolDeclarations::TOOL_SCHEMAS.each_with_object(Registry.new) do |schema, built|
           schema = ToolDeclarations.without_command_description(schema) unless command_description
+          schema = ToolDeclarations.with_task_finish_line(schema) if task_finish_notes
           klass = by_name.fetch(schema[:name])
           handler = HANDLERS.fetch(klass::NAME) { ->(call, _kctx) { klass.call(call[:content]) } }
           built.register(klass::NAME, schema: schema, handler: handler)

data/lib/samagotchi/tools/task_record.rb

@@ -44,6 +44,15 @@ module Samagotchi
         to_h.reject { |key, value| value.nil? && self.class::OPTIONAL.include?(key) }.transform_keys(&:to_s)
       end
 
+      # A task id as people read it: the random part a task_create id ends
+      # with (TaskRuntime.generate_task_id starts it with the time, the same
+      # for every task that second), else its first 8 chars. The web's
+      # turn_events.js has the JS twin (shortTaskId).
+      def self.short_id(id)
+        id = id.to_s
+        id[/-(\h{8})\z/, 1] || id[0, 8]
+      end
+
       def running? = status == "running"
 
       def stopped_by_user? = stop_reason == "stopped_by_user"

data/lib/samagotchi/tools/task_runtime.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "shellwords"
 require "time"
 require_relative "../atomic_file"
+require_relative "../child_env"
 require_relative "../log"
 require_relative "../process_group"
 require_relative "shell"
@@ -29,8 +30,7 @@ module Samagotchi
       OUTPUT_TAIL_READ_BYTES = 16 * 1024
       SANITIZED_ENV_KEYS = %w[RUBYOPT RUBYLIB BUNDLE_GEMFILE BUNDLE_BIN_PATH BUNDLER_VERSION].freeze
       # Set by chi (Builtins.parent_env); the model's env can't change it.
-      MARKER_ENV_KEYS = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL SAMAGOTCHI_SESSION_THINKING
-                           SAMAGOTCHI_SESSION_REASONING_HISTORY].freeze
+      MARKER_ENV_KEYS = ChildEnv::SESSION_MARKERS
       # task_wait and task_get add it to a task the user stopped (the web's
       # stop-task button), so the model doesn't rerun the job.
       # A record whose pid isn't a process group chi started (missing, 0, 1,

data/lib/samagotchi/tools/task_wait.rb

@@ -80,12 +80,19 @@ module Samagotchi
       end
       private_class_method :cancelled_response
 
-      # Always give the log's last lines: a test run's summary, an error. A
-      # task the user stopped also says so.
-      def self.finished_response(record, tail_lines)
+      # A finished task's text, as task_wait gives it: its status lines and
+      # always the log's last lines (a test run's summary, an error), then a
+      # stderr_tail when the record has a non-empty one. A task the user
+      # stopped also says so. Public: a task finish wake's note
+      # (TaskFinishNote) carries the same text.
+      # @param record [TaskRecord] a finished one
+      # @return [String] a RefText of its output_path when it has one
+      def self.finished_text(record, tail_lines: TAIL_LINES_DEFAULT)
         extra = record.stopped_by_user? ? [TaskRuntime::USER_STOP_NOTE] : []
         format_response(record, output_tail: output_tail(record, tail_lines), tail_lines: tail_lines, extra: extra)
       end
+
+      def self.finished_response(record, tail_lines) = finished_text(record, tail_lines: tail_lines)
       private_class_method :finished_response
 
       def self.output_tail(record, tail_lines)

data/lib/samagotchi/turn_checkpoint.rb

@@ -91,16 +91,25 @@ module Samagotchi
     end
     private_class_method :settled_record
 
+    # A command's status (its command_ran's) as a settled outcome; any
+    # other status (busy, dropped) is a cancel for that reason.
+    COMMAND_OUTCOMES = { "ok" => "completed", "error" => "failed" }.freeze
+    # Its record's origin: no turn ran (ParentReport says "the command").
+    COMMAND_ORIGIN = "command"
+
     # A file-delivered command ends its sender's wait without running a
-    # turn. Keep a terminal outcome under the same per-input settled path.
-    def self.record_command_outcome(session_dir, enqueued_id)
+    # turn. Keep a terminal outcome under the same per-input settled path:
+    # +status+ is its command_ran's ("ok", "error", "busy", "dropped" at a
+    # teardown), so the wait reads completed, failed, or canceled with that
+    # reason.
+    def self.record_command_outcome(session_dir, enqueued_id, status:)
       id = enqueued_id.to_s
       return if id.empty? || !SessionInbox::ENQUEUED_ID_NAME.match?(id)
 
-      dir = File.join(session_dir, SessionInbox::INPUT_DIR, SETTLED_DIR)
-      FileUtils.mkdir_p(dir)
-      record = LastTurn.new(outcome: "completed", ended_at: Time.now.iso8601(3), enqueued_id: id)
-      AtomicFile.write(File.join(dir, id), JSON.generate(record.to_file))
+      outcome = COMMAND_OUTCOMES.fetch(status.to_s, "canceled")
+      record = LastTurn.new(outcome: outcome, cancel_reason: (status.to_s if outcome == "canceled"),
+                            ended_at: Time.now.iso8601(3), origin: COMMAND_ORIGIN, enqueued_id: id)
+      write_settled(session_dir, id, record)
     rescue SystemCallError, IOError => e
       Log.warn(:worker, "command_outcome_write_failed", error: e.class.name, msg: e.message, enqueued_id: id)
     end
@@ -109,14 +118,18 @@ module Samagotchi
       id = mark.enqueued_id.to_s
       return unless SessionInbox::ENQUEUED_ID_NAME.match?(id)
 
-      dir = File.join(session_dir, SessionInbox::INPUT_DIR, SETTLED_DIR)
-      FileUtils.mkdir_p(dir)
-      record = settled_record(id, ended_at: Time.now.iso8601(3), seconds: seconds)
-      AtomicFile.write(File.join(dir, id), JSON.generate(record.to_file))
+      write_settled(session_dir, id, settled_record(id, ended_at: Time.now.iso8601(3), seconds: seconds))
     rescue SystemCallError => e
       # The settle goes on; a wait for that turn runs to its timeout.
       Log.warn(:worker, "settled_turn_write_failed", error: e.class.name, msg: e.message)
     end
+
+    def self.write_settled(session_dir, id, record)
+      dir = File.join(session_dir, SessionInbox::INPUT_DIR, SETTLED_DIR)
+      FileUtils.mkdir_p(dir)
+      AtomicFile.write(File.join(dir, id), JSON.generate(record.to_file))
+    end
+    private_class_method :write_settled
     private_class_method :record_settled
 
     # @param session [Session] the worker's session (saved as a whole)

data/lib/samagotchi/version.rb

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