samagotchi 0.90.0 → 0.92.0

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -154,7 +154,7 @@ module Samagotchi
       #   source, recorded as DEV_SHA (no sha256 check) with "dev": true
       def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
                 guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil,
-                scripts_files: {}, context_providers: [], file_descriptions: {}, session_settings: [], dev: false)
+                scripts_files: {}, context_providers: [], file_descriptions: {}, session_settings: [], session_setting_types: {}, dev: false)
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -255,6 +255,7 @@ module Samagotchi
         end
         manifest_data["context_providers"] = context_providers.map(&:to_h) unless context_providers.empty?
         manifest_data["session_settings"] = Array(session_settings).map(&:to_s) unless Array(session_settings).empty?
+        manifest_data["session_setting_types"] = session_setting_types.to_h { |k, v| [k.to_s, v.to_s] } unless session_setting_types.to_h.empty?
 
         write_manifest(manifest_data)
       end

data/lib/samagotchi/parent_report.rb

@@ -6,6 +6,7 @@ require "json"
 require_relative "cli/exit"
 require_relative "pending_question"
 require_relative "session"
+require_relative "turn_checkpoint"
 require_relative "guardrails/parent_policy"
 
 module Samagotchi
@@ -339,6 +340,8 @@ module Samagotchi
     end
 
     def no_reply_line(result, session_id = nil, strategy: nil)
+      return command_line(result) if result.origin == TurnCheckpoint::COMMAND_ORIGIN
+
       case result.outcome
       when "failed" then failed_line(result)
       when "canceled"
@@ -360,6 +363,15 @@ module Samagotchi
       end
     end
 
+    # A file-delivered session command's outcome: no turn ran for it.
+    def command_line(result)
+      case result.outcome
+      when "completed" then "the command ran (no turn)"
+      when "failed" then "the command failed"
+      else "the command was refused (#{result.cancel_reason || "canceled"})"
+      end
+    end
+
     # A failed turn's line; one whose work stayed says so, so the task isn't
     # sent again over what it changed.
     def failed_line(result)

data/lib/samagotchi/reply_wait.rb

@@ -59,8 +59,11 @@ module Samagotchi
     #   :canceled and :timeout
     # @!attribute turn_id [String, nil] the id of the turn this result is
     #   about, when known
+    # @!attribute origin [String, nil] "command" for a :no_reply that a
+    #   file-delivered session command settled (no turn ran:
+    #   TurnCheckpoint.record_command_outcome); nil otherwise
     Result = Struct.new(:status, :text, :file, :question, :outcome, :limit, :error_kind, :retryable, :cancel_reason,
-                        :stopped_by, :kept_steps, :session, :turn_id, keyword_init: true)
+                        :stopped_by, :kept_steps, :session, :turn_id, :origin, keyword_init: true)
 
     module_function
 
@@ -163,7 +166,8 @@ module Samagotchi
         # command finished without a turn. After the reply check: a worker
         # killed between writing the reply and its idle save left the reply.
         if turn && (settled = TurnCheckpoint.settled_turn(session_dir, turn))
-          return Result.new(status: :no_reply, outcome: settled.outcome, session: session, **settled.stop_facts)
+          return Result.new(status: :no_reply, outcome: settled.outcome, session: session, origin: settled.origin,
+                            **settled.stop_facts)
         end
 
         case session.status

data/lib/samagotchi/sandbox_layout.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+require "yaml"
+require_relative "paths"
+
+module Samagotchi
+  # The temp folders a sandboxed chi runs in, shared by `chi bundle try`'s
+  # child (BundleCommand::Try::Sandbox) and the test kit
+  # (Testing::Sandbox): one realpath'd root holding config/, state/,
+  # work/ and whatever else the sandbox wants, the XDG pair pointing at
+  # them, and the switches every sandbox turns off. Where the environment
+  # goes is each sandbox's own: try builds its child's Hash, the kit
+  # changes ENV.
+  class SandboxLayout
+    DIRS = %w[config state work].freeze
+    # No recap request and no cache warm-up request in a sandbox.
+    QUIET_ENV = { "SAMAGOTCHI_RECAP_ENABLED" => "false", "SAMAGOTCHI_CACHE_WARMUP" => "off" }.freeze
+
+    # A new temp root (Dir.mktmpdir +prefix+, its realpath) with DIRS and
+    # +extra+ folders in it.
+    # @return [SandboxLayout]
+    def self.create(prefix, extra: [])
+      root = File.realpath(Dir.mktmpdir(prefix))
+      (DIRS + extra).each { |dir| FileUtils.mkdir_p(File.join(root, dir)) }
+      new(root)
+    rescue StandardError
+      FileUtils.rm_rf(root) if root
+      raise
+    end
+
+    # @return [String]
+    attr_reader :root
+
+    def initialize(root)
+      @root = root
+    end
+
+    def dir(name) = File.join(root, name)
+
+    def config_home = dir("config")
+
+    def state_home = dir("state")
+
+    def work_dir = dir("work")
+
+    # XDG_CONFIG_HOME and XDG_STATE_HOME at the sandbox's, and QUIET_ENV.
+    # @return [Hash{String=>String}]
+    def env = { "XDG_CONFIG_HOME" => config_home, "XDG_STATE_HOME" => state_home }.merge(QUIET_ENV)
+
+    # config.yml under +config_home+ (default the sandbox's): a Hash (as
+    # YAML) or YAML text.
+    # @return [String] its path
+    def write_config(data, config_home: self.config_home)
+      path = File.join(config_home, Paths::APP_DIR, "config.yml")
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, data.is_a?(String) ? data : YAML.dump(data))
+      path
+    end
+
+    def remove
+      FileUtils.rm_rf(root)
+    end
+  end
+end

data/lib/samagotchi/send_command.rb

@@ -93,9 +93,9 @@ module Samagotchi
         --set BUNDLE.KEY=VALUE
                     (--new) a bundle setting for this session, over
                     config.yml's bundles: (repeatable; a key its bundle's
-                    manifest lists in session_settings:; 3, 2.5, true,
-                    false and off are typed, the rest is text:
-                    --set cost-cap.cap=3)
+                    manifest lists in session_settings:; numbers (3,
+                    .5) and booleans (true, off, no) are typed, the
+                    rest is text: --set cost-cap.cap=3)
         --parent-answers LEVEL
                     (--new) what a parent agent may answer on its
                     questions: hard, standard or soft, only stricter than

data/lib/samagotchi/session_manager.rb

@@ -5,6 +5,7 @@ require "json"
 require "time"
 require "securerandom"
 require "rbconfig"
+require_relative "child_env"
 require_relative "client_id"
 require_relative "analytics_file"
 require_relative "atomic_file"
@@ -210,7 +211,7 @@ module Samagotchi
     # is when the worker starts); opts[:env] adds to it (merged, not
     # replaced) what it can't read there: this `chi`'s CLI settings
     # (Config.cli_env) and the absolute log file. It unsets
-    # SAMAGOTCHI_GUARDRAILS_* and the session markers (SESSION_MARKER_ENV).
+    # what ChildEnv lists (SAMAGOTCHI_GUARDRAILS_*, the session markers).
     # XDG_CONFIG_HOME passes: whoever starts or
     # wakes the worker picks which config.yml it reads (docs/guardrails.md).
     # XDG_STATE_HOME and XDG_CONFIG_HOME, when set, pass made absolute
@@ -244,18 +245,15 @@ module Samagotchi
       # And the spawner's XDG dirs, absolute: a relative XDG_STATE_HOME or
       # XDG_CONFIG_HOME would otherwise be read from the session's directory.
       child_env.merge!(Paths.absolute_xdg)
-      # The spawner's environment must not reach the worker's guardrails (a
-      # parent agent starting or waking a session): Process.spawn unsets a
-      # key mapped to nil. config.yml no longer reads them; this keeps an
-      # older or future env-exposed one out as well.
-      ENV.each_key { |key| child_env[key] = nil if key.start_with?(GUARDRAILS_ENV_PREFIX) }
-      # The markers a session's execute exports (Tools::Builtins.parent_env)
-      # are that session's: a worker started from its commands (chi send)
-      # is another session. Its execute and tasks set its own; nothing else
-      # it runs (a user's !cmd, an MCP server, a context command) has one.
-      SESSION_MARKER_ENV.each { |key| child_env[key] = nil }
-      # A smoke's fake "newest installed" is for this process's notices only.
-      child_env[InstalledVersions::ENV_KEY] = nil
+      # Unset (Process.spawn unsets a key mapped to nil) what no child chi
+      # takes from its spawner (ChildEnv): the spawner's guardrails settings
+      # (a parent agent starting or waking a session; config.yml no longer
+      # reads them, this keeps an older or future env-exposed one out as
+      # well); the session markers, a session's own (a worker started from
+      # its commands, chi send, is another session: its execute and tasks
+      # set its own; nothing else it runs has one); and a smoke's fake
+      # "newest installed", for this process's notices only.
+      child_env.merge!(ChildEnv.unset)
       # A worker process: run_session_loop traps signals, and leaves this
       # process's tree.
       child_env[WORKER_PROCESS_ENV] = "1"
@@ -263,17 +261,11 @@ module Samagotchi
       # A gem-mode worker activates the newest installed chi itself: under
       # `bundle exec` (a Gemfile that has samagotchi) Bundler's RUBYOPT would
       # hold it to the bundle's version, and its badge would never clear.
-      child_env.merge!(InstalledGem.unbundled_env_changes) if InstalledGem.spec
+      child_env.merge!(ChildEnv.unbundled)
       opts[:env] = child_env unless child_env.empty?
       opts
     end
 
-    GUARDRAILS_ENV_PREFIX = "SAMAGOTCHI_GUARDRAILS_"
-    WORKER_ENV_PREFIX = "SAMAGOTCHI_WORKER_"
-    # Tools::Builtins.parent_env's (Tools::TaskRuntime::MARKER_ENV_KEYS).
-    SESSION_MARKER_ENV = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL SAMAGOTCHI_SESSION_THINKING
-                            SAMAGOTCHI_SESSION_REASONING_HISTORY].freeze
-
     # List all sessions, reading status from persisted session.json files.
     # +project_root+: only that project's sessions (nil: every session).
     # +include_archived+: archived sessions too (Session#archived says which).

data/lib/samagotchi/task_finish_note.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "context_note"
+require_relative "tool_output_cut"
+require_relative "tools/task_wait"
+
+module Samagotchi
+  # The note a finished background task leaves in its session (TaskWatch,
+  # the Worker's finish wake): a context note under its own header
+  # (ContextNote::TASK_HEADER), as Engine#add_context_note takes it. The
+  # wake variant opens a wake turn (turn_start, turn_id) and ends with the
+  # ask (WAKE_TEXT); the plain one joins the next turn (queue mode, a spent
+  # budget, a note-only task, the unmark after a failed wake).
+  module TaskFinishNote
+    WAKE_TEXT = "chi started this turn because a background task you started finished; your user didn't write " \
+                "anything.\nCarry on with what you planned to do with its result. If you planned nothing, tell your " \
+                "user in a sentence or two how it went."
+
+    module_function
+
+    # @param record [Tools::TaskRecord] the finished task
+    # @param limit_sec [Integer, nil] the limit an execute handed it over at
+    # @param wake [Boolean] the wake variant
+    # @param cap [Integer] max_tool_output_chars: task_wait's text is cut to
+    #   it as ToolRunner cuts the tool's result
+    # @return [Hash] the note (ContextNote.message's keys)
+    def note(record, limit_sec:, wake:, cap:, turn_id: nil, now: Time.now)
+      note = { note_id: "task-#{record.id}", source: "task #{short_id(record.id)}", header: ContextNote::TASK_HEADER,
+               text: text(record, limit_sec: limit_sec, wake: wake, cap: cap), created_at: now.iso8601 }
+      wake ? note.merge(turn_start: true, turn_id: turn_id) : note
+    end
+
+    def text(record, limit_sec:, wake:, cap:)
+      [headline(record, limit_sec), "command: #{record.command}", body(record, cap), (WAKE_TEXT if wake)].compact.join("\n")
+    end
+
+    def headline(record, limit_sec)
+      seconds = duration(record)
+      outcome = record.exit_code.nil? ? record.status.to_s : "exit #{record.exit_code}"
+      handed = " (handed over by execute at its #{limit_sec}s limit)" if limit_sec
+      "Background task #{short_id(record.id)} finished: #{outcome}#{" after #{duration_text(seconds)}" if seconds}#{handed}."
+    end
+
+    # task_wait's own text for the task, cut to +cap+ as its result would be
+    # (ToolOutputCut's :head_tail_ref, naming the logs).
+    def body(record, cap)
+      text = Tools::TaskWait.finished_text(record).to_s
+      return text if text.length <= cap
+
+      ToolOutputCut.apply(text, cap: cap, tool: Tools::TaskWait::NAME, ref: record.output_path,
+                                ref_stderr: record.stderr_path).first
+    end
+
+    # From started_at to the exit_code file's mtime (the shell's EXIT trap
+    # wrote it as it ended), else finished_at: that is when a refresh first
+    # noticed the end, which may be long after. nil when neither is known.
+    # @return [Float, nil] seconds
+    def duration(record)
+      started = time(record.started_at)
+      return nil unless started
+
+      ended = exit_code_mtime(record) || time(record.finished_at)
+      ended && [ended - started, 0].max
+    end
+
+    def duration_text(seconds)
+      seconds = seconds.round
+      return "#{seconds}s" if seconds < 60
+      return format("%dm%02ds", seconds / 60, seconds % 60) if seconds < 3600
+
+      format("%dh%02dm", seconds / 3600, (seconds % 3600) / 60)
+    end
+
+    def short_id(id) = Tools::TaskRecord.short_id(id)
+
+    def exit_code_mtime(record)
+      path = record.exit_code_path.to_s
+      path.empty? || !File.file?(path) ? nil : File.mtime(path)
+    rescue SystemCallError
+      nil
+    end
+
+    def time(value)
+      value && Time.iso8601(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/samagotchi/task_watch.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+require_relative "tools/task_runtime"
+
+module Samagotchi
+  # The background tasks a worker's session started that the model hasn't
+  # seen finish (docs/internals/background-tasks.md, Finish wake). Held by
+  # the Worker (the --no-shared REPL has none) and fed by the Engine's raw
+  # :tool_call_completed events (#observe), the input Bridge#own_task_ids
+  # reads too; the idle loop takes the finished ones (#take_finished) for a
+  # wake turn or a plain note. In memory only: a crash loses them, and they
+  # behave as before (the model sees them at its next look).
+  #
+  # Thread-safe: the turn thread feeds it, the loop's thread takes from it,
+  # and anytime commands run on threads of their own.
+  class TaskWatch
+    # A watched task: +limit_sec+, the limit an execute handed it over at
+    # (nil for task_create's); +note_only+, the user stopped the turn that
+    # started or waited on it (M5): its finish is a plain note, no wake;
+    # +failures+, how often its note couldn't be written (#put_back) or the
+    # look for it failed (#look_failed).
+    Entry = Data.define(:id, :limit_sec, :note_only, :failures) do
+      def initialize(id:, limit_sec: nil, note_only: false, failures: 0) = super
+    end
+
+    # A task whose note or look failed this often still gets tried at each
+    # look, but no longer holds the worker up (#holding): a failure that
+    # never passes must not keep it alive for good.
+    MAX_FAILURES = 3
+
+    # The cancel reasons that are the user's own Stop (Bridge::CANCEL_REASONS
+    # less session_stopped, and the TUI's ctrl_c).
+    USER_CANCEL_REASONS = %i[manual user ctrl_c].freeze
+
+    # The first line of a task tool's result, after a gate-corrected call's
+    # "ran as: …" line and the optional "[tool]" lead.
+    TASK_LINE = /\A#{Tools::TaskRuntime::RAN_AS_LINE}(?:\[task_(?:wait|get|stop)\]\n)?task_id: (\S+)/
+    LOOK_TOOLS = %w[task_wait task_get task_stop].freeze
+    HANDED_OVER_LIMIT = /#{Regexp.escape(Tools::Execute::HANDED_OVER)} (\d+)s limit/
+
+    MODE_KEY = "session.task_wakes"
+    MODES = %w[wake queue off].freeze
+
+    # session.task_wakes: wake (default), queue or off; anything else is
+    # wake, and so is a config that can't be read (logged once per error
+    # class: it is read at every idle pass).
+    def self.mode
+      value = Config.get(MODE_KEY).to_s
+      MODES.include?(value) ? value : "wake"
+    rescue StandardError => e
+      @mode_errors ||= {}
+      unless @mode_errors[e.class]
+        @mode_errors[e.class] = true
+        Log.warn(:worker, "task_wakes_unreadable", error: e.class.name, msg: e.message)
+      end
+      "wake"
+    end
+
+    def initialize
+      @mutex = Mutex.new
+      @entries = {}
+      @turn_ids = []
+    end
+
+    # A raw Engine event: a result that started a task adds it, one that
+    # shows the model the task's end removes it (#seen_id).
+    def observe(event)
+      return unless event[:type] == :tool_call_completed
+
+      tool = event[:tool].to_s
+      output = event[:output].to_s
+      output = output.scrub unless output.valid_encoding?
+      if (id = Tools::TaskRuntime.created_id(tool, output))
+        add(id, limit_sec: tool == Tools::Execute::NAME ? output[HANDED_OVER_LIMIT, 1]&.to_i : nil)
+      elsif LOOK_TOOLS.include?(tool) && (id = output[TASK_LINE, 1])
+        touched(id)
+        remove(id) if seen?(tool, output)
+      end
+    end
+
+    def add(id, limit_sec: nil)
+      @mutex.synchronize do
+        @entries[id] = Entry.new(id: id, limit_sec: limit_sec)
+        @turn_ids << id
+      end
+    end
+
+    def remove(id)
+      @mutex.synchronize { @entries.delete(id) }
+    end
+
+    # A turn begins: the tasks it starts or waits on are its own (#turn_canceled).
+    def turn_started
+      @mutex.synchronize { @turn_ids = [] }
+    end
+
+    # A turn ended canceled for +reason+: the user's Stop makes that turn's
+    # tasks note-only (M5); a signal's, a hook's or a session stop's don't.
+    def turn_canceled(reason)
+      return unless USER_CANCEL_REASONS.include?(reason&.to_sym)
+
+      @mutex.synchronize do
+        @turn_ids.each { |id| @entries[id] &&= @entries[id].with(note_only: true) }
+      end
+    end
+
+    def ids = @mutex.synchronize { @entries.keys }
+
+    # The watched tasks, oldest first (a copy).
+    # @return [Array<Entry>]
+    def entries = @mutex.synchronize { @entries.values }
+
+    def any? = @mutex.synchronize { @entries.any? }
+
+    # The watched tasks that finished, taken out of the watch with their
+    # records ([Entry, TaskRecord], oldest first). One the user stopped (the
+    # web's stop-task button) or whose record is gone is dropped, not
+    # returned. +keep+: the ids the conversation still holds
+    # (TaskRuntime.created_ids_in): a !rollback or a restored turn may have
+    # dropped the result that added one, which is dropped too. One `ps` per
+    # running task (TaskRuntime.get_record); nothing with an empty watch.
+    # @return [Array<Array(Entry, Tools::TaskRecord)>]
+    def take_finished(keep: nil)
+      watched = entries
+      return [] if watched.empty?
+
+      watched.filter_map do |entry|
+        # Safe for any llm_context strategy: stale and forget stubs are drawn
+        # in the view sent to the model (LLMContextView, the entry's edits),
+        # never written over the saved tool_response text; only a !rollback
+        # or a restored turn takes the result that names the id out.
+        next drop(entry, log: "not_in_conversation") if keep && !keep.include?(entry.id)
+
+        record, error = Tools::TaskRuntime.get_record(entry.id)
+        if error || record.nil?
+          # Gone (its task dir deleted) or unreadable: no note can be written.
+          next drop(entry, log: "record_unreadable", level: :info, error: error.to_s.lines.first&.strip)
+        end
+        next nil if record.running?
+        # Removed by a look meanwhile (a task_wait on an anytime command's thread).
+        next nil unless drop(entry, kept: true)
+        next nil if record.stopped_by_user?
+
+        [entry, record]
+      end
+    end
+
+    # +entries+ taken by #take_finished whose note couldn't be written:
+    # watched again, the failure counted (an id watched meanwhile keeps its
+    # own entry).
+    def put_back(entries)
+      @mutex.synchronize do
+        entries.each { |entry| @entries[entry.id] ||= entry.with(failures: entry.failures + 1) }
+      end
+    end
+
+    # The look for finished tasks failed before it could tell which ended
+    # (the conversation's task ids couldn't be read): every watched task
+    # counts a failure.
+    def look_failed
+      @mutex.synchronize { @entries.transform_values! { |entry| entry.with(failures: entry.failures + 1) } }
+    end
+
+    # Whether a watched task has finished (#take_finished would take it):
+    # Engine#next_turn_waiting asks at a turn's end. Takes nothing. A record
+    # that can't be read counts as not finished here (and not running in
+    # #running): #take_finished drops it at the next look, logged.
+    def finished?
+      ids.any? do |id|
+        record, = Tools::TaskRuntime.get_record(id)
+        record && !record.running?
+      end
+    end
+
+    # The watched tasks a finish would wake for, running or finished and
+    # not yet taken (#take_finished takes them at the idle loop's next
+    # look): they hold the worker's idle exit (WorkerIdleExit's
+    # watched_tasks). Not a note-only one (no wake would come for it), nor
+    # one whose note or look failed MAX_FAILURES times. No `ps`: in memory.
+    # @return [Array<Entry>]
+    def holding = entries.reject { |entry| entry.note_only || entry.failures >= MAX_FAILURES }
+
+    # The #holding tasks still running ({id:, command:}), for /exit
+    # (WorkerIdleExit's watched_running): one finished meanwhile is noted
+    # as the worker leaves. One `ps` per task.
+    # @return [Array<Hash>]
+    def running
+      holding.filter_map do |entry|
+        record, = Tools::TaskRuntime.get_record(entry.id)
+        { id: entry.id, command: record.command.to_s } if record&.running?
+      end
+    end
+
+    private
+
+    # Removes +entry+; nil (a filter_map's skip), or with +kept+ whether it
+    # was there. +log+: why a task leaves without a note, at +level+ (debug
+    # by default), with +error+ when there is one.
+    def drop(entry, kept: false, log: nil, level: :debug, error: nil)
+      removed = !remove(entry.id).nil?
+      if log && removed
+        Log.public_send(level, :worker, "task_watch_dropped", **{ task_id: entry.id, reason: log, error: error }.compact)
+      end
+      kept ? removed : nil
+    end
+
+    def touched(id)
+      @mutex.synchronize { @turn_ids << id unless @turn_ids.include?(id) }
+    end
+
+    # Whether +tool+'s +output+ for a task shows the model its end:
+    # task_wait's final status or a done_pattern match (D5), task_get's
+    # final status (the status alone is enough), any task_stop.
+    def seen?(tool, output)
+      status = output[/^status: (\S+)/, 1]
+      case tool
+      when "task_stop" then true
+      when "task_get" then final?(status)
+      when "task_wait" then final?(status) || output.match?(/^wait_result: pattern_matched$/)
+      else false
+      end
+    end
+
+    def final?(status) = !status.nil? && status != "running"
+  end
+end

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -60,8 +60,12 @@ module Samagotchi
       HELD_REASONS = {
         "turn_running" => "a turn is running", "input_queued" => "prompts are queued",
         "continue_offered" => "a continue offer is pending", "client_connected" => "another UI is attached",
-        "reminders" => "reminders are set", "starting" => "the worker is still starting"
+        "reminders" => "reminders are set", "starting" => "the worker is still starting",
+        "background_tasks" => "background tasks it started are still running"
       }.freeze
+      # How to end a background task that holds the worker up (an older
+      # worker's 409 has no hint of its own).
+      TASK_STOP_HINT = "stop one with the web's stop-task button or by asking for task_stop"
       # How much of the last answer a join shows.
       JOIN_ANSWER_LINES = 12
       JOIN_ANSWER_CHARS = 1200
@@ -556,7 +560,8 @@ module Samagotchi
           "Detached; the session's worker is stopping. Resume with: chi --resume #{id}"
         when 409
           reason = reply.json&.fetch("reason", nil).to_s
-          "Detached; the session keeps running (#{HELD_REASONS.fetch(reason, reason)}). Re-attach with: chi --attach #{id}"
+          "Detached; the session keeps running (#{held_words(reason, reply.json&.fetch("tasks", nil))}). " \
+            "Re-attach with: chi --attach #{id}"
         when 0 then exit_failed_line("no reply")
         when 408 then exit_failed_line(LATE)
         else
@@ -567,6 +572,14 @@ module Samagotchi
         end
       end
 
+      # Why the worker stayed up; the background tasks it waits for by
+      # their short id and command (a finish wake's, D3), and how to stop one.
+      def held_words(reason, tasks)
+        words = HELD_REASONS.fetch(reason, reason)
+        listed = Array(tasks).filter_map { |t| "#{Tools::TaskRecord.short_id(t["id"])} (#{t["command"]})" if t.is_a?(Hash) }
+        listed.empty? ? words : "#{words}: #{listed.join(", ")}; #{TASK_STOP_HINT}"
+      end
+
       # An older worker leaves the field out.
       def discards?(reply) = reply.json&.fetch("discard", nil) == true
 
@@ -1628,8 +1641,10 @@ module Samagotchi
       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)"
+      def task_origin?(origin) = origin[:client_id].to_s.start_with?(ClientId::TASK_PREFIX)
+      # A turn with no prompt: "(continuing)"; a context wake's or a task
+      # finish wake's label alone.
+      def continuing_text(origin) = context_origin?(origin) || task_origin?(origin) ? nil : "(continuing)"
     end
   end
 end

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -9,6 +9,7 @@ require_relative "../steer_cut"
 require_relative "../memory_bundle/index_size"
 require_relative "../prompt_note"
 require_relative "../prompt_files"
+require_relative "../tools/task_record"
 require_relative "model_segments_text"
 
 module Samagotchi
@@ -207,8 +208,9 @@ module Samagotchi
 
       # Who sent a line, by its client_id: CLIENT_LABELS by the whole id or
       # its prefix, a turn an attached context source started
-      # (context:<name>) as "context <name> changed", AUTOMATIC_LABEL for
-      # an id chi doesn't know; +fallback+ for none (the user's own).
+      # (context:<name>) as "context <name> changed", a finished background
+      # task's (task:<id>) as "task <id8> finished", AUTOMATIC_LABEL for an
+      # id chi doesn't know; +fallback+ for none (the user's own).
       def client_label(client_id, fallback = "user")
         return fallback unless client_id
 
@@ -216,6 +218,9 @@ module Samagotchi
         name = id.delete_prefix(ClientId::CONTEXT_PREFIX)
         return "context #{name} changed" if id.start_with?(ClientId::CONTEXT_PREFIX) && !name.empty?
 
+        task = id.delete_prefix(ClientId::TASK_PREFIX)
+        return "task #{Tools::TaskRecord.short_id(task)} finished" if id.start_with?(ClientId::TASK_PREFIX) && !task.empty?
+
         prefix = id[/\A[^:]*:/]
         CLIENT_LABELS[id] || (prefix && CLIENT_LABELS[prefix]) || AUTOMATIC_LABEL
       end