samagotchi 0.5.0 → 0.6.0

data/lib/samagotchi/recap_setup.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "log"
+require_relative "idle_recap"
+require_relative "recap_store"
+
+module Samagotchi
+  # Builds (or disables) an Engine's idle recap job from the `recap:` kwarg
+  # and the Config registry. Init-only: the Engine keeps the job it returns.
+  module RecapSetup
+    # Build (or disable) the idle recap job. On by default: with no recap
+    # host or model configured it asks the session's current model on its
+    # host, resolved at each attempt the way a turn does (a /model switch
+    # counts). An explicit `recap: {host_ref:, model:}` or `{base_url:,
+    # model:}` pins it; an incomplete one warns and leaves recap off.
+    #
+    # Single precedence path: explicit `recap:` kwarg > Config registry
+    # (CLI > ENV > file > default). An explicit disable (`recap: false` as
+    # the kwarg or in the config file, `recap: {enabled: false}`, or
+    # SAMAGOTCHI_RECAP_ENABLED=false) always wins.
+    #
+    # @param recap          [Hash, false, nil] the Engine's `recap:` kwarg
+    # @param engine         [Engine] the recap job's engine
+    # @param host_registry  [HostRegistry]
+    # @param session_target [#call] → the session's current model as a recap target
+    # @param session_id     [#call] → String, nil
+    # @param state_dir      [#call] → String
+    # @return [IdleRecap, nil]
+    def self.build(recap, engine:, host_registry:, session_target:, session_id:, state_dir:)
+      return nil if recap == false
+      # The TUI passes the config file's section; a worker passes nothing, so
+      # read it here too (a scalar `recap: false` is only seen this way).
+      return nil if recap.nil? && ConfigFile.recap_config == false
+      return nil if Samagotchi::Config.get("recap.enabled") == false
+
+      # Normalize kwarg (TerminalUI passes recap: recap_config hash or nil)
+      kwarg_config = recap.is_a?(Hash) ? recap : {}
+
+      base_url = string_config(kwarg_config, :base_url) || registry_string("recap.base_url")
+      host_ref = string_config(kwarg_config, :host_ref) || string_config(kwarg_config, :host) || registry_string("recap.host_ref")
+      model = string_config(kwarg_config, :model) || registry_string("recap.model")
+      label = model
+
+      target = nil
+      if base_url.nil? && host_ref.nil? && model.nil?
+        target = -> { session_target.call }
+      else
+        # If host_ref given, derive base_url (the host's OpenAI base) and its
+        # API key variable from the host_registry entry
+        api_key_env = nil
+        if host_ref && !host_ref.empty?
+          entry = host_registry.find_entry(host_ref)
+          if entry
+            base_url = entry.openai_base_url
+            api_key_env = entry.api_key_env
+            # If model is host-qualified, extract bare model for recap client
+            _, bare = host_registry.parse_qualified_model(model) if model
+            model = bare if bare && !bare.empty?
+          else
+            Log.warn(:recap, "host_ref_unknown", echo: "Warning: recap host_ref '#{host_ref}' not found in hosts:; recap disabled.", host_ref: host_ref)
+            return nil
+          end
+        end
+
+        if base_url.to_s.strip.empty? || model.to_s.strip.empty?
+          Log.warn(:recap, "recap_unconfigured",
+                   echo: "Warning: SAMAGOTCHI session recap is enabled but base_url/model are missing; recap disabled. " \
+                         "Set recap: {host_ref:, model:} or SAMAGOTCHI_RECAP_BASE_URL and SAMAGOTCHI_RECAP_MODEL (or pass recap: {base_url:, model:}), " \
+                         "or leave them all out to recap with the session's own model.")
+          return nil
+        end
+        fixed = { base_url: base_url.to_s.strip, api_key_env: api_key_env, model: model.to_s.strip, label: label.to_s.strip }
+        target = -> { fixed }
+      end
+
+      IdleRecap.new(
+        engine: engine,
+        target: target,
+        inactivity: recap_number_setting(kwarg_config, :inactivity, "recap.inactivity", IdleRecap::DEFAULT_INACTIVITY_SECONDS, :float),
+        min_user_turns: recap_number_setting(kwarg_config, :min_user_turns, "recap.min_user_turns", IdleRecap::DEFAULT_MIN_USER_TURNS, :int),
+        timeout: recap_number_setting(kwarg_config, :timeout, "recap.timeout", IdleRecap::DEFAULT_TIMEOUT_SECONDS, :float),
+        sentences: recap_sentences(string_config(kwarg_config, :sentences) || registry_string("recap.sentences")),
+        store: RecapStore.new(session_id_lookup: -> { session_id.call }, state_dir_lookup: -> { state_dir.call })
+      )
+    end
+
+    # recap.sentences as [min, max]; an invalid value warns and falls back to
+    # the default range (the recap stays on).
+    def self.recap_sentences(value)
+      range = IdleRecap::RecapPrompt.sentences_range(value)
+      return range if range
+
+      default = IdleRecap::RecapPrompt::DEFAULT_SENTENCES
+      Log.warn(:recap, "sentences_invalid", echo: "Warning: invalid value for recap.sentences: #{value.to_s.inspect} — using #{default.join('-')}",
+                                            value: value.to_s)
+      default
+    end
+    private_class_method :recap_sentences
+
+    # Read a scalar recap setting via the Config registry (ENV > file > default).
+    def self.registry_string(key)
+      value = Samagotchi::Config.get(key)
+      value = value.to_s.strip
+      value.empty? ? nil : value
+    rescue StandardError
+      nil
+    end
+    private_class_method :registry_string
+
+    # Resolve a numeric recap setting: kwarg > Config registry > built-in default.
+    def self.recap_number_setting(kwarg_config, kwarg_key, config_key, default, numeric_type)
+      value = kwarg_config[kwarg_key] || kwarg_config[kwarg_key.to_s]
+      value = Samagotchi::Config.get(config_key) if value.nil? || value.to_s.strip.empty?
+      value = default if value.nil? || value.to_s.strip.empty?
+      numeric_type == :float ? value.to_f : value.to_i
+    rescue StandardError
+      numeric_type == :float ? default.to_f : default.to_i
+    end
+    private_class_method :recap_number_setting
+
+    def self.string_config(config, key)
+      value = config[key]
+      value.to_s.strip.empty? ? nil : value.to_s
+    end
+    private_class_method :string_config
+  end
+end

data/lib/samagotchi/reply_wait.rb

@@ -103,6 +103,15 @@ module Samagotchi
       end
     end
 
+    # The session as it was before a message went in (call's baseline:):
+    # its messages, the question pending then, and when its last turn
+    # ended, so a turn that ends before the first look still ends the wait.
+    # @return [Hash]
+    def baseline_of(session, question_id: session.pending_question&.dig(:id))
+      last = session.last_turn.is_a?(Hash) ? session.last_turn["ended_at"] : nil
+      { messages: session.messages.size, question_id: question_id, last_turn: last }
+    end
+
     # An idle session whose turn ended after the baseline was taken: its
     # last_turn moved on, or its messages grew (a turn's note).
     def turn_ended_since?(session, baseline)

data/lib/samagotchi/send_command.rb

@@ -307,12 +307,9 @@ module Samagotchi
     end
 
     # The session as it was before the message went in (ReplyWait's
-    # baseline): its messages, the question pending then, and when its last
-    # turn ended, so a turn that ends before the first look still ends the
-    # wait.
-    def baseline_of(session, question_id: session.pending_question&.dig(:id))
-      last = session.last_turn.is_a?(Hash) ? session.last_turn["ended_at"] : nil
-      { messages: session.messages.size, question_id: question_id, last_turn: last }
+    # baseline).
+    def baseline_of(session, **options)
+      ReplyWait.baseline_of(session, **options)
     end
 
     # @return [Integer] the exit status

data/lib/samagotchi/session.rb

@@ -297,6 +297,9 @@ module Samagotchi
     # A scratch session nobody owns (its REPL was killed) goes whatever its
     # age, its status and the count; +test_only+ takes it too.
     #
+    # +max_count+ counts the sessions that stay: one deleted whatever its
+    # place (scratch, left empty, expired, +any_age+) takes no slot.
+    #
     # Archived sessions are not in .list, so they are neither deleted nor
     # counted. One unarchived is aged from when it was unarchived, if later.
     #
@@ -319,6 +322,7 @@ module Samagotchi
       deleted = []
       kept = []
       skipped = []
+      passed_over = 0
 
       all.each_with_index do |session, idx|
         path = File.join(state_dir, "#{session.id}#{FILE_EXT}")
@@ -365,7 +369,11 @@ module Samagotchi
           expired = updated < cutoff
         end
 
-        overflow = max.positive? && idx >= max
+        # A session deleted whatever its place (scratch, left empty,
+        # expired, any_age) takes no max_count slot: the count is of the
+        # sessions ahead that stay.
+        overflow = max.positive? && idx - passed_over >= max
+        passed_over += 1 if expired || left_empty || any_age || session.scratch
 
         # retain forever when both disabled
         if max.zero? && cutoff.nil? && !left_empty && !any_age && !session.scratch

data/lib/samagotchi/sessions_command.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "session"
+require_relative "session_manager"
+require_relative "project_scope"
+require_relative "session_metrics"
+require_relative "recap_store"
+require_relative "session_delete_command"
+require_relative "session_archive_command"
+
+module Samagotchi
+  # `chi sessions`: list, stop, archive/unarchive, delete, prune and clean
+  # sessions from the shell (bin/chi dispatches here before OptionParser;
+  # the subcommands have their own flags). Not SessionCommands, the REPL's
+  # slash commands for sessions (session_commands.rb).
+  class SessionsCommand
+    USAGE = <<~TEXT
+      Usage: chi sessions <list|stop|archive|unarchive|delete|prune|clean> [options]
+        list [--sort updated_at|created_at] [--order desc|asc] [--limit N]
+             [--live] [--cwd PATH] [--format text|json|tsv] [--archived]
+             --live: sessions a worker runs now (the ones chi note reaches), 10 unless --limit
+             --cwd PATH: sessions in PATH or below; json/tsv (id<TAB>description) are for scripts
+             [--scope=all]: every project's sessions; by default only this git project's (all outside a repo)
+             --archived: archived sessions too (marked [archived]; json: archived: true)
+        stop ID...   # stop each session's worker (IDs or unique prefixes); chi --resume ID then starts a fresh one
+        archive ID...   # hide sessions (and their delegates) from every list and keep them for good; unarchive ID... brings them back
+        delete [--force] ID...   # delete sessions for good (IDs or unique prefixes); --force stops a live worker first
+        prune [--dry-run] [--days N] [--keep N] [--keep-status running,...] [--test-only]
+        clean [--dry-run] [--days N]   # test sessions (SAMAGOTCHI_ENV=test, CI) and leftover chi scratch ones: all of them, or those older than N days
+      Defaults: days=14 keep=500 keep_status=none (config: session.retention_days, session.max_count, session.keep_status)
+    TEXT
+
+    # The value flags: "--flag V" or "--flag=V", converted with the method
+    # given (nil: the string as it is). Every argument is scanned, the values
+    # too (--cwd --live takes "--live" as the folder and turns --live on),
+    # a flag with nothing after it is ignored, and so is an unknown one.
+    VALUE_FLAGS = {
+      "--days" => [:days, :to_i], "--keep" => [:keep, :to_i], "--keep-status" => [:keep_status, nil],
+      "--sort" => [:sort, nil], "--order" => [:order, nil], "--limit" => [:limit, :to_i],
+      "--cwd" => [:cwd, nil], "--format" => [:format, nil], "--scope" => [:scope, nil]
+    }.freeze
+
+    # @param argv [Array<String>] the arguments after "sessions"
+    def initialize(argv, stdout: $stdout, stderr: $stderr)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    # @return [Integer] exit status
+    def run
+      sub = @argv[0]
+      if sub.nil? || %w[-h --help help].include?(sub)
+        @stdout.puts USAGE
+        return 0
+      end
+      @opts = parse_flags
+      case sub
+      when "delete"
+        Samagotchi::SessionDeleteCommand.new(@argv[1..], stdout: @stdout, stderr: @stderr).run
+      when "archive", "unarchive"
+        Samagotchi::SessionArchiveCommand.new(sub, @argv[1..], stdout: @stdout, stderr: @stderr).run
+      when "list" then list
+      when "stop" then stop
+      when "prune", "clean" then prune(sub)
+      else
+        @stderr.puts "Unknown sessions subcommand: #{sub}. Use: list, stop, archive, unarchive, delete, prune, clean"
+        1
+      end
+    end
+
+    private
+
+    def parse_flags
+      opts = {
+        dry_run: @argv.include?("--dry-run"),
+        test_only: @argv.include?("--test-only") || @argv.include?("--test"),
+        live: @argv.include?("--live"),
+        include_archived: @argv.include?("--archived")
+      }
+      @argv.each_with_index do |arg, i|
+        nxt = @argv[i + 1]
+        VALUE_FLAGS.each do |flag, (key, convert)|
+          value = if arg == flag && nxt then nxt
+                  elsif arg.start_with?("#{flag}=") then arg.split("=", 2).last
+                  end
+          next unless value
+
+          opts[key] = convert ? value.public_send(convert) : value
+          break
+        end
+      end
+      opts
+    end
+
+    def list
+      format, scope, cwd = @opts.values_at(:format, :scope, :cwd)
+      unless format.nil? || %w[text json tsv].include?(format)
+        @stderr.puts "Unknown format #{format.inspect}: use --format text|json|tsv"
+        return 1
+      end
+      unless scope.nil? || %w[project all].include?(scope)
+        @stderr.puts "Unknown scope #{scope.inspect}: use --scope=project|all"
+        return 1
+      end
+      # The current git project's sessions (Samagotchi::ProjectScope), like
+      # chi web's; --scope=all, a folder in no repo or an explicit --cwd: every
+      # project's.
+      project = scope == "all" || cwd ? nil : Samagotchi::ProjectScope.root_for(Dir.pwd)
+      scope_note = ->(count) { "#{count} session(s) in #{File.basename(project)} (--scope=all: every project)" }
+
+      # The picker (chi note from a script): filters apply before the limit,
+      # and test runs stay out, unless this is one (SAMAGOTCHI_ENV=test, CI):
+      # then its own sessions are what it looks for.
+      return list_summaries(project, scope_note) if @opts[:live] || cwd || (format && format != "text")
+
+      list_plain(project, scope_note)
+    end
+
+    def list_summaries(project, scope_note)
+      live, cwd, limit, include_archived, format = @opts.values_at(:live, :cwd, :limit, :include_archived, :format)
+      summaries = Samagotchi::SessionManager.session_summaries(
+        live: live, cwd: cwd, limit: limit || (live ? 10 : nil), include_tests: Samagotchi::Session.test_session_env?,
+        project_root: project,
+        include_archived: include_archived
+      )
+      case format
+      when "json"
+        # owner: "worker", "tui" (a chi REPL: it takes no notes or messages)
+        # or nil; recap: the saved recap's first sentence, or nil; project:
+        # its git project's root, or nil
+        # parent_id: the session that delegated it (the delegate tool), or nil
+        # archived: hidden from the lists (only with --archived can it be true)
+        # scratch: a `chi scratch` session (deleted when its REPL ends, a
+        # leftover one at the next sweep)
+        # ctx_pct: how full the context was after the last turn, or nil
+        keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id archived scratch ctx_pct]
+        @stdout.puts JSON.generate(summaries.map { |summary| summary.slice(*keys) })
+      when "tsv"
+        summaries.each { |summary| @stdout.puts "#{summary[:id]}\t#{summary[:desc]}" }
+      else
+        summaries.each do |summary|
+          state = summary[:busy] ? "running" : (summary[:live] ? "live" : summary[:status].to_s)
+          # The saved recap's first sentence says more than the last prompt
+          # (text only: tsv and json keep desc for pickers).
+          desc = summary[:desc]
+          if summary[:recap]
+            desc = [File.basename(summary[:cwd].to_s), summary[:recap]].reject(&:empty?).join(" · ")
+            desc = "#{desc[0, 59]}…" if desc.length > 60
+          end
+          # A delegated session points at its parent.
+          child = summary[:parent_short_id] ? "  ↳ #{summary[:parent_short_id]}" : ""
+          flag = summary[:scratch] ? " [scratch]" : (summary[:test_run] ? " [test]" : "")
+          flag += " [archived]" if summary[:archived]
+          ctx = Samagotchi::SessionMetrics.context_label(summary[:ctx_pct])
+          @stdout.puts "#{summary[:id]}  #{state.ljust(8)}  #{ctx.ljust(8)}  #{summary[:updated_at]}  #{desc}#{flag}#{child}"
+        end
+        if project
+          @stdout.puts "#{summaries.empty? ? "" : "\n"}#{scope_note.call(summaries.size)}"
+        else
+          @stdout.puts summaries.empty? ? "No sessions." : "\n#{summaries.size} session(s)"
+        end
+      end
+      0
+    end
+
+    def list_plain(project, scope_note)
+      sort, order, limit, include_archived = @opts.values_at(:sort, :order, :limit, :include_archived)
+      sort ||= "updated_at"
+      order ||= "desc"
+      sessions = Samagotchi::SessionManager.list_sessions(sort: sort, order: order, limit: limit, project_root: project,
+                                                          include_archived: include_archived)
+      # The saved recap's first sentence, else the last prompt, cut as before.
+      state_dir = Samagotchi::Session.default_state_dir
+      list_text = lambda do |s|
+        recap = Samagotchi::RecapStore.preview(Samagotchi::Session.session_dir(s.id, state_dir: state_dir))
+        (recap || Samagotchi::SessionManager.one_line(s.last_prompt))[0, 60]
+      end
+      # A delegated session points at its parent: ↳ <parent's short id>.
+      row = lambda do |s|
+        flag = s.scratch ? " [scratch]" : (s.test_run ? " [test]" : "")
+        flag += " [archived]" if s.archived
+        child = s.parent_id ? "  ↳ #{s.parent_id[0, 8]}" : ""
+        # How full the context was after the last turn: "ctx 12%", blank when unknown.
+        ctx = Samagotchi::SessionMetrics.context_label(
+          Samagotchi::SessionMetrics.saved_context_pct(Samagotchi::Session.session_dir(s.id, state_dir: state_dir))
+        )
+        "#{s.id}  #{s.status.ljust(8)}  #{ctx.ljust(8)}  #{s.updated_at}  #{list_text.call(s)}#{flag}#{child}"
+      end
+      if project
+        sessions.each { |s| @stdout.puts row.call(s) }
+        @stdout.puts "#{sessions.empty? ? "" : "\n"}#{scope_note.call(sessions.size)}"
+      elsif sessions.empty?
+        @stdout.puts "No sessions."
+      else
+        sessions.each { |s| @stdout.puts row.call(s) }
+        @stdout.puts "\n#{sessions.size} session(s) (sort=#{sort} order=#{order})"
+      end
+      0
+    end
+
+    def stop
+      ids = @argv[1..]
+      if ids.empty? || ids.any? { |arg| arg.start_with?("-") }
+        @stderr.puts "Usage: chi sessions stop ID..."
+        return 1
+      end
+      # Each id in turn, like chi sessions delete: stdout is flushed before an
+      # error line, so the output keeps the order of the ids given.
+      ok = ids.uniq.map do |given|
+        begin
+          id = Samagotchi::Session.resolve_id(given)
+          released = Samagotchi::SessionManager.stop_session(id, wait: 10)
+        rescue Samagotchi::SessionManager::OwnedByTUI
+          @stdout.flush
+          @stderr.puts "session #{id} is open in a chi REPL; close it there first"
+          next false
+        rescue ArgumentError => e
+          @stdout.flush
+          @stderr.puts e.message
+          next false
+        end
+        if released
+          @stdout.puts "Stopped session #{id}. chi --resume #{id} starts a fresh worker."
+        else
+          @stdout.flush
+          @stderr.puts "Stopped session #{id}, but its worker is still shutting down; try chi --resume #{id} in a moment."
+        end
+        true
+      end
+      ok.all? ? 0 : 1
+    end
+
+    def prune(sub)
+      days, keep, keep_status, dry_run, test_only = @opts.values_at(:days, :keep, :keep_status, :dry_run, :test_only)
+      test_only = true if sub == "clean" && !@argv.include?("--all")
+      # Test sessions are throwaway: clean takes them whatever their age,
+      # unless --days asks for the older ones only. Live workers and
+      # keep_status still protect a session.
+      any_age = sub == "clean" && test_only && days.nil?
+      result = Samagotchi::SessionManager.prune_sessions(days: days, max_count: keep, keep_status: keep_status, dry_run: dry_run,
+                                                         test_only: test_only, any_age: any_age)
+      mode = dry_run ? "Would delete" : "Deleted"
+      @stdout.puts "#{mode} #{result[:deleted].size} sessions (kept #{result[:kept].size}, skipped #{result[:skipped].size})"
+      if result[:deleted].any?
+        result[:deleted].each { |id| @stdout.puts "  #{id}" }
+      end
+      if dry_run && result[:deleted].any?
+        @stdout.puts "\nRun without --dry-run to delete."
+      end
+      0
+    end
+  end
+end

data/lib/samagotchi/steer.rb

@@ -7,17 +7,23 @@ module Samagotchi
   # lines merge into one user message as before; each steer follows it as its
   # own user message marked kind: "steer" and source: (the ContextNote keys,
   # which every message copy keeps). The model reads it as user text.
+  #
+  # The user's own lines merged into a running turn are marked kind:
+  # "input": they are part of that turn, not a turn of their own, so a
+  # reloaded history keeps the turn in one piece.
   module Steer
     KIND = "steer"
+    INPUT_KIND = "input"
 
     # What one drain brought: the merged user text (nil when none) and how
     # many lines made it, and the steers in order.
     Merge = Struct.new(:content, :count, :steers, keyword_init: true) do
       def empty? = content.nil? && steers.empty?
 
-      # The messages it appends: the user's first, then each steer.
+      # The messages it appends: the user's first (marked merged input),
+      # then each steer.
       def messages
-        list = content ? [{ role: "user", content: content }] : []
+        list = content ? [{ role: "user", kind: INPUT_KIND, content: content }] : []
         list + steers.map { |steer| Steer.message(**steer) }
       end
 
@@ -46,6 +52,17 @@ module Samagotchi
       message.is_a?(Hash) && (message[:role] || message["role"]).to_s == "user" && !steer?(message)
     end
 
+    # The user's lines merged into a running turn (Merge#messages).
+    def input?(message)
+      message.is_a?(Hash) && (message[:kind] || message["kind"]).to_s == INPUT_KIND
+    end
+
+    # A prompt that started a turn: not a steer, not input merged into a
+    # running turn. What the turns a page shows count.
+    def turn_prompt?(message)
+      prompt?(message) && !input?(message)
+    end
+
     # Call a loop's drain: +at_answer+ goes only to a drain that takes it
     # (the Engine's); a caller's own drain (a queue's #drain) is called bare.
     # A failing drain drains nothing (the loop keeps going).

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -945,15 +945,19 @@ module Samagotchi
       # The snapshot's cards and between-turns notices (Bridge CardStore):
       # on join the ones since the last turn (and the running turn's), as
       # the join header shows the last exchange; on a resync only cards not
-      # shown here yet. A turn's own notices are left out: the running
-      # turn's come with its parts, and the join shows no older turn's steps.
+      # shown here yet. A turn's own rows (notices, retries) are left out:
+      # the running turn's come with its parts, and the join shows no older
+      # turn's steps.
       def render_snapshot_cards(entries, joining:)
         entries.each do |entry|
-          if entry[:type].to_s == "hook_notice"
+          case entry[:type].to_s
+          when "hook_notice"
             next if entry[:in_turn]
 
             @screen.commit(EventRenderer.hook_notice_line(entry)) if joining && entry[:turns_since].to_i.zero?
-          elsif joining ? entry[:turns_since].to_i.zero? : !@renderer.card_shown?(entry[:id])
+          when "card"
+            next unless joining ? entry[:turns_since].to_i.zero? : !@renderer.card_shown?(entry[:id])
+
             @renderer.render_card(entry, updated: entry[:updated] == true)
           end
         end
@@ -986,13 +990,22 @@ module Samagotchi
           when "input" then @screen.commit("input> #{part[:text]}")
           when "steer" then @screen.commit(format_steer_line(source: part[:source], text: part[:text]))
           when "reminder" then @screen.commit(reminder_line(part[:reminders]))
-          when "hook_notice" then @screen.commit(EventRenderer.hook_notice_line(part))
+          when "notice" then replay_notice(part[:event])
           end
         end
         @view.resume(tail: tail, lane: lane, tool: running_tool, parts: turn[:parts])
         ask(turn[:pending_question]) if turn[:pending_question]
       end
 
+      # One of the running turn's rows (Bridge::TurnNotice), drawn as it was
+      # live: a hook's notice and a retry's line. Questions are left out:
+      # the pending one is asked after the replay, answered ones showed no
+      # line.
+      def replay_notice(event)
+        event = EventRenderer.symbolize(event || {})
+        @renderer.call(event) if %i[hook_notice empty_answer_retry].include?(event[:type])
+      end
+
       def show_enqueued(event)
         return if own?(event[:client_id])
 

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -37,9 +37,11 @@ module Samagotchi
         paint("#{source.to_s.empty? ? "plugin" : source}> nudged: #{first}", 90)
       end
 
-      # "↻ empty answer, asking again (1/1)": the loop retries an empty answer.
+      # "↻ empty answer, asking again (1/1)": the loop retries an empty answer;
+      # "↻ cut by loop-guard, asking again (1/1)" after a plugin cut it.
       def format_empty_retry_line(event)
-        paint("↻ empty answer, asking again (#{event[:attempt]}/#{event[:of]})", 90)
+        what = event[:stopped_by] ? "cut by #{event[:stopped_by]}" : "empty answer"
+        paint("↻ #{what}, asking again (#{event[:attempt]}/#{event[:of]})", 90)
       end
 
       # " → image 1280×800" after a tool line whose tool read an image.

data/lib/samagotchi/tool_declarations.rb

@@ -348,7 +348,7 @@ module Samagotchi
             },
             timeout: {
               type: "integer",
-              description: "Maximum seconds to wait (default: 600); a timed-out child keeps running"
+              description: "Maximum seconds to wait (default: 600; 0 checks once without waiting); a timed-out child keeps running"
             }
           },
           required: ["task"]
@@ -366,7 +366,7 @@ module Samagotchi
             },
             timeout: {
               type: "integer",
-              description: "Maximum seconds to wait (default: 600)"
+              description: "Maximum seconds to wait (default: 600; 0 checks once without waiting)"
             }
           }
         }

data/lib/samagotchi/tools/delegate.rb

@@ -83,6 +83,7 @@ module Samagotchi
         child = SessionManager.spawn_session(prompt: task, working_directory: parent.working_directory,
                                              model_name: child_model(model, parent), memories: CHILD_MEMORIES,
                                              parent_id: parent.id, state_dir: state_dir)
+        DelegateWait.mark_started(parent.id, child)
         child.id
       end
       private_class_method :start_child
@@ -100,7 +101,7 @@ module Samagotchi
         end
 
         # Only a reply after this delivery counts as the follow-up's.
-        DelegateWait.mark_seen(parent.id, id, state_dir: state_dir)
+        DelegateWait.mark_seen(parent.id, child, state_dir: state_dir)
         delivered = SessionManager.deliver_turn(id, prompt: task, client_id: "#{CLIENT_PREFIX}:#{parent.id[0, 8]}",
                                                     state_dir: state_dir)
         case delivered[:status]
@@ -158,9 +159,12 @@ module Samagotchi
         !%w[false 0 no off].include?(value.to_s.strip.downcase)
       end
 
+      # Seconds to wait: 0 (or less) looks once and returns at once; a
+      # missing or unreadable value is the default.
+      # @return [Integer]
       def self.parse_timeout(value)
         parsed = Integer(value.to_s.strip, exception: false)
-        parsed&.positive? ? parsed : DelegateWait::TIMEOUT_DEFAULT
+        parsed ? [parsed, 0].max : DelegateWait::TIMEOUT_DEFAULT
       end
     end
   end