samagotchi 0.153.0 → 0.154.1

data/lib/samagotchi/system_prompt.rb

@@ -2,6 +2,7 @@
 
 require_relative "config"
 require_relative "log"
+require_relative "degrade"
 require_relative "log_path"
 require_relative "memory_paths"
 require_relative "paths"
@@ -74,12 +75,12 @@ module Samagotchi
       @requested_memories = effective_preload_list(preload_memory_list(memories))
       # Read once, as the memories: list is: a config edit is picked up by
       # a new process. The files' text is read at each build.
-      @config_appended = begin
-        ConfigFile.appended_prompt_files
-      rescue StandardError
-        []
-      end
+      @config_appended = Degrade.call(:prompt, "appended_list_unreadable", fallback: []) { ConfigFile.appended_prompt_files }
       @cli_appended = Array(appended_files).map { |path| File.expand_path(path.to_s) }
+      # { [chat, thinking, layers] => Built }, swapped for a new one by #reset!
+      @cache = {}
+      # The Built #build returned last; nil before a build and after #reset!.
+      @last = nil
     end
 
     # @return [Array<String>] the names the session preloads, known before
@@ -88,37 +89,35 @@ module Samagotchi
       @requested_memories.map { |raw| split_memory_scope(raw).last }.uniq
     end
 
+    # A prompt #build made, with what it read while it did: the memory
+    # index sizes (#memory_index), the model notes, the files and the
+    # plugins' sections it holds, and its stable part's length (chat).
+    Built = Data.define(:prompt, :memory_index, :notes, :files, :sections, :stable_length)
+
     # The full prompt: #base wrapped with the index and the rest. Built once
     # per loop and level (until #reset!) so the prompt prefix, and the
     # server's KV cache for it, stay stable.
+    #
+    # #reset! runs on other threads (a plugin's tools_changed! /
+    # prompt_changed!, a /stats re-resolving the profile) and, through the
+    # profile lookup, inside a build on this one. So a build reads @cache
+    # once and computes into locals: a reset meanwhile swaps in a new cache
+    # and this build's result goes into the dropped one, so it is returned
+    # (the same bytes as without the reset) but not kept, and the next
+    # build reads the sources again. No lock: the build reads memory files
+    # and calls the lookups, one of which takes ModelBinding's mutex, whose
+    # holder (a /stats thread) may itself call #reset!.
     # @param chat [Boolean] for the chat loop
     # @param thinking [Symbol, nil] the level (Thinking); nil: the effective model's
     # @param layers [Array<Symbol>] the turn's LLM context layers: the
     #   native prompt declares the tools they add (Tools::Registry#entries)
     def build(chat: false, thinking: nil, layers: [])
       key = [chat, thinking, layers]
-      @built ||= {}
-      @index_sizes ||= {}
-      @notes_loaded ||= {}
-      @files_loaded ||= {}
-      @sections_loaded ||= {}
-      unless @built.key?(key)
-        @section_notes = nil
-        @section_files = []
-        @section_plugins = []
-        @built[key] = system_prompt_with_index(
-          assist_system_prompt(chat: chat, layers: layers), chat: chat, thinking: thinking, layers: layers
-        )
-        @index_sizes[key] = @measured_index
-        @notes_loaded[key] = @section_notes || []
-        @files_loaded[key] = @section_files.freeze
-        @sections_loaded[key] = @section_plugins.freeze
-      end
-      @memory_index = @index_sizes[key]
-      @prompt_notes = @notes_loaded[key]
-      @prompt_files = @files_loaded[key]
-      @prompt_sections = @sections_loaded[key]
-      @built[key]
+      cache = @cache
+      built = cache[key] || (cache[key] = build_prompt(chat: chat, thinking: thinking, layers: layers))
+      @memory_index = built.memory_index
+      @last = built
+      built.prompt
     end
 
     # The memory indexes the prompt #build returned last holds, per scope
@@ -133,7 +132,7 @@ module Samagotchi
     # (Array<ModelNotes::Note>, [] with none), nil before a build and after
     # #reset!. Read when the prompt is built, as the section is.
     # @return [Array<ModelNotes::Note>, nil]
-    attr_reader :prompt_notes
+    def prompt_notes = @last&.notes
 
     # The files whose text the prompt #build returned last holds, as
     # absolute paths in prompt order: the AGENTS.md chain, then the
@@ -141,26 +140,21 @@ module Samagotchi
     # build and after #reset!. Read when the prompt is built, as the
     # sections are.
     # @return [Array<String>]
-    def prompt_files = @prompt_files || []
+    def prompt_files = @last&.files || []
 
     # The plugins' prompt sections the prompt #build returned last holds
     # (Plugin::PromptSections::Built, prompt order), [] before a build and
     # after #reset!.
     # @return [Array<Plugin::PromptSections::Built>]
-    def prompt_sections = @prompt_sections || []
+    def prompt_sections = @last&.sections || []
 
     # Drops the built prompts: the next #build reads the profile, tools,
     # indexes and memories again (a model or profile switch, changed tools).
     def reset!
-      @built = nil
-      @index_sizes = nil
-      @notes_loaded = nil
-      @prompt_notes = nil
-      @files_loaded = nil
-      @prompt_files = nil
-      @sections_loaded = nil
-      @prompt_sections = nil
-      @stable_lengths = nil
+      # Single assignments: a build in flight keeps the cache it read
+      # (#build), so it neither fails nor is kept.
+      @cache = {}
+      @last = nil
     end
 
     # The length of +prompt+'s stable part when it is a chat prompt #build
@@ -168,7 +162,12 @@ module Samagotchi
     # a remote prompt cache can keep for every session (PromptCache). nil
     # for any other text, or a prompt without those lines.
     # @return [Integer, nil]
-    def stable_length(prompt) = @stable_lengths&.[](prompt)
+    def stable_length(prompt)
+      last = @last
+      return last.stable_length if last&.prompt == prompt
+
+      @cache.each_value.find { |built| built.prompt == prompt }&.stable_length
+    end
 
     # The base prompt (specs, plugins' declarations), with Gemma's tool
     # declarations at its end as #build has them.
@@ -185,6 +184,20 @@ module Samagotchi
 
     private
 
+    # One #build's work: the prompt and what it read, in a Built. The
+    # @section_* and @measured_* scratch is this build's (the turn thread's)
+    # alone: #reset! never touches it.
+    def build_prompt(chat:, thinking:, layers:)
+      @section_notes = nil
+      @section_files = []
+      @section_plugins = []
+      @measured_stable_length = nil
+      prompt = system_prompt_with_index(assist_system_prompt(chat: chat, layers: layers),
+                                        chat: chat, thinking: thinking, layers: layers)
+      Built.new(prompt: prompt, memory_index: @measured_index, notes: @section_notes || [],
+                files: @section_files.freeze, sections: @section_plugins.freeze, stable_length: @measured_stable_length)
+    end
+
     def profile = @profile_lookup.call
 
     def turn_thinking = @thinking_lookup.call
@@ -334,7 +347,7 @@ module Samagotchi
       return with_tail_declarations(stable_text, chat: chat, layers: layers) if volatile.empty?
 
       prompt = "#{stable_text}\n#{volatile.join("\n")}"
-      (@stable_lengths ||= {})[prompt] = stable_text.length + 1 if chat
+      @measured_stable_length = stable_text.length + 1 if chat
       with_tail_declarations(prompt, chat: chat, layers: layers)
     end
 
@@ -386,11 +399,11 @@ module Samagotchi
     # (Plugin::PromptSections). nil with none: the prompt is what it was
     # before prompt sections.
     def plugin_prompt_section
-      built = Array(@sections_lookup.call)
-      @section_plugins = built
-      Plugin::PromptSections.text(built)
-    rescue StandardError
-      nil
+      Degrade.call(:prompt, "plugin_section_failed") do
+        built = Array(@sections_lookup.call)
+        @section_plugins = built
+        Plugin::PromptSections.text(built)
+      end
     end
 
     def with_tail_declarations(prompt, chat:, layers:)
@@ -405,35 +418,35 @@ module Samagotchi
     # Identity is not tracked as an "activated" memory for the sticky status line
     # to avoid always showing `mem: identity`.
     def system_identity_section
-      DEFAULT_SYSTEM_MEMORIES.each do |name|
-        next if memory_muted?(name)
+      Degrade.call(:prompt, "identity_unreadable") do
+        DEFAULT_SYSTEM_MEMORIES.each do |name|
+          next if memory_muted?(name)
 
-        body = Tools::MemoryRead.call(name, scope: "system", **overlay_keys)
-        next if body.start_with?("Error:")
-        next if body.strip.empty?
+          body = Tools::MemoryRead.call(name, scope: "system", **overlay_keys)
+          next if body.start_with?("Error:")
+          next if body.strip.empty?
 
-        return "System identity (auto-loaded, scope=system):\n#{body}"
+          return "System identity (auto-loaded, scope=system):\n#{body}"
+        end
+        nil
       end
-      nil
-    rescue StandardError
-      nil
     end
 
     # The model notes for the session's model (ModelNotes), right after
     # identity: a heading per scope, each note under its name, the models:
     # line left out. nil without any, so the prompt stays as it was.
     def model_notes_section
-      @section_notes = []
-      notes = Array(@model_notes_lookup.call)
-      return nil if notes.empty?
-
-      ref = @model_lookup.call&.ref
-      notes.group_by(&:scope).map do |scope, list|
-        heading = ref.to_s.empty? ? "Model notes (scope=#{scope}):" : "Model notes (for #{ref}, scope=#{scope}):"
-        [heading, *list.map { |note| "## #{note.name}\n#{note.body}" }].join("\n\n")
-      end.join("\n\n").tap { @section_notes = notes }
-    rescue StandardError
-      nil
+      Degrade.call(:prompt, "model_notes_failed") do
+        @section_notes = []
+        notes = Array(@model_notes_lookup.call)
+        return nil if notes.empty?
+
+        ref = @model_lookup.call&.ref
+        notes.group_by(&:scope).map do |scope, list|
+          heading = ref.to_s.empty? ? "Model notes (scope=#{scope}):" : "Model notes (for #{ref}, scope=#{scope}):"
+          [heading, *list.map { |note| "## #{note.name}\n#{note.body}" }].join("\n\n")
+        end.join("\n\n").tap { @section_notes = notes }
+      end
     end
 
     # ── Memory helpers ─────────────────────────────────────────────────────────
@@ -441,23 +454,23 @@ module Samagotchi
     # The session model's overlay keys, so the prompt's own memory bodies
     # (identity, preloads) get `<name>.<key>.md` as memory_read gives it.
     def overlay_keys
-      model = @model_lookup.call
-      return {} unless model&.key
+      Degrade.call(:prompt, "overlay_keys_failed", fallback: {}) do
+        model = @model_lookup.call
+        return {} unless model&.key
 
-      { model_key: model.key, fallback_model_key: model.fallback_key }
-    rescue StandardError
-      {}
+        { model_key: model.key, fallback_model_key: model.fallback_key }
+      end
     end
 
     # { system: { tokens:, lines: }, project: { … } } of the index texts
     # the prompt holds; nil when they can't be measured.
     def measure_indexes(indexes)
-      chars_per_token = MemoryBundle::IndexSize.chars_per_token
-      %i[system project].to_h do |scope|
-        [scope, MemoryBundle::IndexSize.of_text(scope, indexes[scope], chars_per_token: chars_per_token).figures]
+      Degrade.call(:prompt, "index_size_failed") do
+        chars_per_token = MemoryBundle::IndexSize.chars_per_token
+        %i[system project].to_h do |scope|
+          [scope, MemoryBundle::IndexSize.of_text(scope, indexes[scope], chars_per_token: chars_per_token).figures]
+        end
       end
-    rescue StandardError
-      nil
     end
 
     # The scope's index text without the muted memories' lines, nor the
@@ -473,11 +486,7 @@ module Samagotchi
     # comma-split and appended without duplicates (same ref shape as --memory:
     # bare name or scope/name).
     def preload_memory_list(cli_memories)
-      baseline = begin
-        ConfigFile.preloaded_memories
-      rescue StandardError
-        []
-      end
+      baseline = Degrade.call(:prompt, "preload_list_unreadable", fallback: []) { ConfigFile.preloaded_memories }
 
       merged = Array(baseline).dup
       # For the warning when one can't be loaded: it names where it came from.
@@ -555,15 +564,15 @@ module Samagotchi
     # The AGENTS.md chain from the top of the git work tree down to the cwd
     # (PromptFiles.agents_sections), one section per file with text.
     def project_specific_description
-      return nil if skip_agent_description?
+      Degrade.call(:prompt, "agents_md_unreadable") do
+        return nil if skip_agent_description?
 
-      sections = PromptFiles.agents_sections(Dir.pwd)
-      return nil if sections.empty?
+        sections = PromptFiles.agents_sections(Dir.pwd)
+        return nil if sections.empty?
 
-      @section_files&.concat(sections.map(&:path))
-      sections.map(&:text).join("\n\n")
-    rescue StandardError
-      nil
+        @section_files&.concat(sections.map(&:path))
+        sections.map(&:text).join("\n\n")
+      end
     end
 
     # The appended files' text, right after AGENTS.md (the stable, cached
@@ -572,26 +581,26 @@ module Samagotchi
     # then --append-system-prompt's. A file the AGENTS.md chain holds, a
     # repeat and an empty or vanished file are left out.
     def appended_section
-      cwd = Dir.pwd
-      top = MemoryPaths.work_tree_root(cwd)
-      seen = Set.new((skip_agent_description? ? [] : PromptFiles.agents_paths(cwd)).map { |path| canonical_path(path) })
-      sections = []
-      appended_candidates(cwd).each do |path, source|
-        next unless seen.add?(canonical_path(path))
-
-        unless File.file?(path)
-          Log.debug(:config, "appended_prompt_file_missing", path: path, source: source)
-          next
-        end
-        text = PromptFiles.section(path, "Appended from #{PromptFiles.display_path(path, top: top)}:")
-        next unless text
+      Degrade.call(:prompt, "appended_files_failed") do
+        cwd = Dir.pwd
+        top = MemoryPaths.work_tree_root(cwd)
+        seen = Set.new((skip_agent_description? ? [] : PromptFiles.agents_paths(cwd)).map { |path| canonical_path(path) })
+        sections = []
+        appended_candidates(cwd).each do |path, source|
+          next unless seen.add?(canonical_path(path))
+
+          unless File.file?(path)
+            Log.debug(:config, "appended_prompt_file_missing", path: path, source: source)
+            next
+          end
+          text = PromptFiles.section(path, "Appended from #{PromptFiles.display_path(path, top: top)}:")
+          next unless text
 
-        @section_files&.push(path)
-        sections << text
+          @section_files&.push(path)
+          sections << text
+        end
+        sections.empty? ? nil : sections.join("\n\n")
       end
-      sections.empty? ? nil : sections.join("\n\n")
-    rescue StandardError
-      nil
     end
 
     # [absolute path, "config" | "cli"], in prompt order.
@@ -617,27 +626,27 @@ module Samagotchi
     # The home directory is spelled out once so the model copies the right
     # sequence, with the advice to write it as ~ or $HOME instead.
     def project_location
-      cwd = Dir.pwd
-      top = MemoryPaths.work_tree_root(cwd)
-      lines = ["Current working directory:", cwd]
-      if top && top != cwd
-        lines << "Top of this checkout (where the project's commands run from; stay inside it):"
-        lines << top
-      elsif top
-        lines << "This checkout (the project's files; its commands run here):"
-        lines << top
-      end
-      if top && MemoryPaths.project_root(cwd) != top
-        lines << "This checkout is a linked git worktree: read, edit, run and commit only in it, never in the " \
-                 "repository's other checkouts."
+      Degrade.call(:prompt, "location_failed") do
+        cwd = Dir.pwd
+        top = MemoryPaths.work_tree_root(cwd)
+        lines = ["Current working directory:", cwd]
+        if top && top != cwd
+          lines << "Top of this checkout (where the project's commands run from; stay inside it):"
+          lines << top
+        elsif top
+          lines << "This checkout (the project's files; its commands run here):"
+          lines << top
+        end
+        if top && MemoryPaths.project_root(cwd) != top
+          lines << "This checkout is a linked git worktree: read, edit, run and commit only in it, never in the " \
+                   "repository's other checkouts."
+        end
+        home = Dir.home
+        lines << "Home directory: #{home} (write it as ~ or $HOME in commands and paths)" unless home.to_s.empty?
+        lines << "Project memories folder (your notes about the project, not its files; never work or run commands there):"
+        lines << Paths.tilde(Tools::MemoryRead.memories_dir("project"))
+        lines.join("\n")
       end
-      home = Dir.home
-      lines << "Home directory: #{home} (write it as ~ or $HOME in commands and paths)" unless home.to_s.empty?
-      lines << "Project memories folder (your notes about the project, not its files; never work or run commands there):"
-      lines << Paths.tilde(Tools::MemoryRead.memories_dir("project"))
-      lines.join("\n")
-    rescue StandardError
-      nil
     end
 
     # Only while the session has participants (people its owner invited to
@@ -662,12 +671,12 @@ module Samagotchi
     # once a participant invited to act is in a working session, the review
     # line for review participants; nothing with none (nil, false).
     def participants_section
-      mode = @participants_lookup.call
-      return nil unless mode
+      Degrade.call(:prompt, "participants_line_failed") do
+        mode = @participants_lookup.call
+        return nil unless mode
 
-      mode == ParticipantMode::PAIR ? PAIR_PARTICIPANTS_LINE : PARTICIPANTS_LINE
-    rescue StandardError
-      nil
+        mode == ParticipantMode::PAIR ? PAIR_PARTICIPANTS_LINE : PARTICIPANTS_LINE
+      end
     end
 
     # The model this session runs on. A model guesses its name from
@@ -675,19 +684,19 @@ module Samagotchi
     # says to answer from here. It depends only on the effective model, and
     # the prompt is rebuilt only on a switch (#reset!): no per-turn churn.
     def current_model
-      model = @model_lookup.call
-      return nil unless model && !model.ref.to_s.empty?
-
-      details = [model.host, model.key && "model key #{model.key}", model.served && "the server says it serves #{model.served}"]
-      details = details.compact.reject(&:empty?)
-      where = details.empty? ? "" : " (#{details.join("; ")})"
-      "Model: this session runs on #{model.ref}#{where}.\n" \
-        "Asked which model you are, answer with this line, not from training: a fine-tuned model often knows only " \
-        "its base model's name, but this session runs what is named here; it changes only with /model. " \
-        "Guidance for this model only goes in a model note: a memory named model_notes_<name> whose first line is " \
-        "`models: <glob on this model's id or key>`."
-    rescue StandardError
-      nil
+      Degrade.call(:prompt, "model_line_failed") do
+        model = @model_lookup.call
+        return nil unless model && !model.ref.to_s.empty?
+
+        details = [model.host, model.key && "model key #{model.key}", model.served && "the server says it serves #{model.served}"]
+        details = details.compact.reject(&:empty?)
+        where = details.empty? ? "" : " (#{details.join("; ")})"
+        "Model: this session runs on #{model.ref}#{where}.\n" \
+          "Asked which model you are, answer with this line, not from training: a fine-tuned model often knows only " \
+          "its base model's name, but this session runs what is named here; it changes only with /model. " \
+          "Guidance for this model only goes in a model note: a memory named model_notes_<name> whose first line is " \
+          "`models: <glob on this model's id or key>`."
+      end
     end
 
     # Fixed for the session's lifetime, so it doesn't churn the prompt cache.
@@ -701,7 +710,7 @@ module Samagotchi
       line = "Current session id: #{id} (resume later with `chi --resume #{id}`)"
       # The log path too: asked what went wrong, a model that has to look
       # it up guesses ~/.local/state first (the self-awareness probes).
-      log = begin; LogPath.resolve; rescue StandardError; nil; end
+      log = Degrade.call(:prompt, "log_path_failed") { LogPath.resolve }
       line = "#{line}\nMy debug log: #{log} (one record per line; this session's carry sid=#{id[0, Log::SID_LENGTH]})" if log
       parent = session.parent_id.to_s
       return line if parent.empty?

data/lib/samagotchi/task_watch.rb

@@ -9,7 +9,7 @@ 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
+  # the Worker (a --non-interactive one-shot 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

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -13,14 +13,19 @@ require_relative "../launch_mode"
 require_relative "live_region"
 require_relative "plain_surface"
 require_relative "attached_loop"
+require_relative "log_tail"
+require_relative "formatting"
 
 module Samagotchi
   class TerminalUI
-    # `chi --attach ID` and `chi --shared [--resume ID]`: find or start the
+    # `chi`, `chi --attach ID` and `chi --resume ID`: find or start the
     # session's worker, then run the TUI as a client of its Bridge
     # (AttachedLoop). It takes no OwnerLock and builds no Engine: the worker
     # owns the session, and any number of UIs can attach to it.
     module AttachLauncher
+      # #paint, for the -v records.
+      extend Formatting
+
       # Why attaching failed, worded for the terminal.
       class Error < StandardError; end
 
@@ -28,6 +33,13 @@ module Samagotchi
       # A connector that answered no session (its own failures raise Error
       # with their words).
       NOTHING_CONNECTED = "could not attach: no session was found or started"
+      # `chi scratch`'s first line, and its last once the session is gone.
+      SCRATCH_BANNER = "Scratch session: nothing is kept, it is deleted when you leave."
+      SCRATCH_DELETED = "Scratch session deleted."
+      # chi -v on a worker that was running before this launch (%s: the
+      # debug log): its level is its own.
+      VERBOSE_RUNNING = "(--verbose: this worker was already running and logs at the level it started with; " \
+                        "its records show here only if it writes to %s: one chi web started may log elsewhere)"
 
       module_function
 
@@ -62,6 +74,13 @@ module Samagotchi
       #   own guardrails.parent_answers; an existing session keeps its own
       #   (never sent as a /parent-answers command: that would be a
       #   loosening route from a command line)
+      # @param scratch [Boolean] `chi scratch`: a new scratch session (its
+      #   worker's Engine saves nothing), stopped and deleted however the
+      #   attach ends; its worker deletes it too once no client is left
+      # @param verbose [Boolean] -v: the session's debug records in the
+      #   debug log (Log.path), shown above the live region as they come
+      #   (LogTail); a worker this launch spawns logs at debug (bin/chi's
+      #   log.level override reaches it through Config.cli_env)
       # @param state_dir [String, nil] where the sessions are (the default
       #   state dir by default): the worker's, for the attached loop too
       # @param connector [#connect, nil] finds or starts the session
@@ -73,19 +92,23 @@ module Samagotchi
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :removed / :unanswered
       #   (AttachedLoop#run)
-      def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
+      def run(attach: nil, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
               memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
-              toolkit_flags: [], settings: nil, parent_answers: nil, state_dir: nil, connector: nil)
+              toolkit_flags: [], settings: nil, parent_answers: nil, scratch: false, verbose: false, state_dir: nil,
+              connector: nil)
         state_dir ||= Session.default_state_dir
+        running_before = verbose && !connector && worker_running?(attach || resume, state_dir)
         link = connector && (connector.connect || raise(Error, NOTHING_CONNECTED))
         client = if connector
                    link.client
                  else
-                   connect(attach: attach, shared: shared, resume: resume, model: model, state_dir: state_dir,
+                   connect(attach: attach, resume: resume, model: model, state_dir: state_dir,
                            memories: memories, muted_memories: muted_memories, llm_context: llm_context,
                            thinking: thinking, appended_prompt_files: appended_prompt_files, toolkit: toolkit,
-                           toolkit_flags: toolkit_flags, settings: settings, parent_answers: parent_answers)
+                           toolkit_flags: toolkit_flags, settings: settings, parent_answers: parent_answers,
+                           scratch: scratch)
                  end
+        $stdout.puts(SCRATCH_BANNER) if scratch
         commands = []
         # --yes on /model and /thinking: typing the flag is the choice (no
         # confirm step); its applied reply ends the launch's command.
@@ -93,11 +116,13 @@ module Samagotchi
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
         commands << "#{ThinkingCommand::NAME} #{thinking} --yes" if (attach || resume) && thinking
         first_command = commands.size > 1 ? commands : commands.first
+        $stderr.puts(format(VERBOSE_RUNNING, Log.path)) if running_before
         surface = open_surface
+        tail = (start_log_tail(surface, client.session_id) if verbose && Log.path)
         options = { screen: surface, client_id: client_id(connector), first_prompt: prompt,
                     first_command: first_command, no_interrupt: no_interrupt,
                     default_input: default_input && !prompt && !attach && !resume,
-                    wait_at_eof: !$stdin.tty?,
+                    wait_at_eof: !$stdin.tty?, scratch: scratch,
                     as_parent: Guardrails::ParentApprovals.parent_process? }
         attached = if connector
                      AttachedLoop.new(link: link, **options)
@@ -107,6 +132,7 @@ module Samagotchi
         ended = begin
           attached.run
         ensure
+          tail&.stop
           close_surface(surface)
         end
         if ended == :unanswered && attached.unanswered
@@ -119,6 +145,34 @@ module Samagotchi
         ended
       ensure
         link&.close
+        # Every way out (Ctrl-D, /exit, the worker gone, an error, Ctrl-C or
+        # a signal): only kill -9 leaves it to its worker (and the sweep).
+        end_scratch(client.session_id, state_dir: state_dir, quiet: !$!.nil?) if scratch && client
+      end
+
+      # Whether +session_id+'s worker runs now (nil: a new session).
+      def worker_running?(session_id, state_dir)
+        return false unless session_id && Session.valid_id?(session_id)
+
+        WorkerLink.resolve(Session.session_dir(session_id, state_dir: state_dir), unlink: false).live?
+      end
+
+      # The session's debug records, dim, above the live region.
+      def start_log_tail(surface, session_id)
+        LogTail.new(path: Log.path, session_id: session_id, on_record: lambda { |record|
+          surface.commit(paint(LogLine.format(record).chomp, 2))
+        }).start
+      end
+
+      # Stop the scratch session's worker and delete the session; its worker
+      # may have deleted it first (it found no client left).
+      def end_scratch(session_id, state_dir:, quiet: false, out: $stdout, err: $stderr)
+        SessionManager.delete_session(session_id, state_dir: state_dir, stop: true, wait: LocalLink::DELETE_WAIT)
+        out.puts(SCRATCH_DELETED) unless quiet
+      rescue ArgumentError
+        out.puts(SCRATCH_DELETED) unless quiet
+      rescue SessionManager::DeleteRefused, SystemCallError => e
+        err.puts("Scratch session #{session_id} was not deleted (#{e.message}): chi sessions delete #{session_id}")
       end
 
       # This TUI's client id: tui:PID, or the connector's own (a remote one
@@ -185,10 +239,11 @@ module Samagotchi
 
       # @return [BridgeClient] a client for the live Bridge of the session
       # @raise [Error]
-      def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
+      def connect(attach: nil, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
                   memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
-                  toolkit_flags: [], settings: nil, parent_answers: nil, err: $stderr)
+                  toolkit_flags: [], settings: nil, parent_answers: nil, scratch: false, err: $stderr)
         sd = state_dir || Session.default_state_dir
+        connected = false
         if attach || resume
           warn_memory_flags_ignored(attach || resume, memories, muted_memories, err, appended_prompt_files: appended_prompt_files,
                                                                                      toolkit_flags: toolkit_flags)
@@ -211,14 +266,21 @@ module Samagotchi
                                                                          thinking: Thinking.session_level(thinking),
                                                                          appended_prompt_files: appended_prompt_files,
                                                                          toolkit: toolkit, settings: settings,
-                                                                         parent_answers: parent_answers))
+                                                                         parent_answers: parent_answers),
+                                                 scratch: scratch)
                   end
         link = WorkerLink.await(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
-        link.live? ? link.client(session.id) : raise(Error, format(LaunchMode::BRIDGE_LATE, session.id))
+        raise(Error, format(LaunchMode::BRIDGE_LATE, session.id)) unless link.live?
+
+        connected = true
+        link.client(session.id)
       rescue SessionManager::OwnedByTUI => e
         raise Error, e.message
       rescue ArgumentError => e
         raise Error, e.message
+      ensure
+        # A scratch session whose Bridge never came (or Ctrl-C meanwhile).
+        end_scratch(session.id, state_dir: sd, quiet: true, err: err) if scratch && session && !connected
       end
 
       # The session's previous worker may still be leaving: its Bridge