samagotchi 0.153.0 → 0.154.0

data/lib/samagotchi/share_command.rb

@@ -8,12 +8,12 @@ require_relative "cli/flags"
 require_relative "session"
 require_relative "session_access"
 require_relative "session_access/local"
-require_relative "web/grants"
+require_relative "grants"
 require_relative "web/qr"
 
 module Samagotchi
   # `chi share`: invite a participant to review a session (the
-  # shared-sessions plan: a Web::Grants grant, one session, one person or
+  # shared-sessions plan: a Grants grant, one session, one person or
   # agent, 7 days unless --expires says otherwise), list the participants,
   # revoke them. Local or through chi --remote NAME (SessionAccess). The
   # token is printed once, in the link; chi keeps only its digest. See
@@ -95,9 +95,9 @@ module Samagotchi
       return parsed if parsed.is_a?(Integer)
 
       send(:"run_#{@sub || "invite"}", parsed.options, parsed.args)
-    rescue SessionAccess::BadRequest, Web::Grants::BadIdentity => e
+    rescue SessionAccess::BadRequest, Grants::BadIdentity => e
       usage_error(e.message)
-    rescue Web::Grants::Unwritable => e
+    rescue Grants::Unwritable => e
       error_line("#{command_name}: #{e.message}")
       CLI::Exit::FAILED
     rescue ArgumentError => e
@@ -114,13 +114,13 @@ module Samagotchi
       return usage_error("give one session ID") unless args.size == 1
       return usage_error("--name NAME: who the link is for") if options[:name].to_s.strip.empty?
 
-      ttl = Web::Grants.parse_ttl(options[:expires])
+      ttl = Grants.parse_ttl(options[:expires])
       return usage_error("--expires takes Nh or Nd, 1h to 30d (e.g. 3d)") if ttl == false
 
       cap = options[:cap] && dollars(options[:cap])
       return usage_error(CAP_USAGE) if cap == false
 
-      identity = options[:identity] && Web::Grants.clean_identity(options[:identity])
+      identity = options[:identity] && Grants.clean_identity(options[:identity])
 
       id = @access.resolve(args.first)
       invitation = @access.invite(id, name: options[:name], kind: options[:agent] ? "agent" : "human", ttl: ttl, cap: cap,
@@ -149,13 +149,13 @@ module Samagotchi
       0
     end
 
-    CAP_USAGE = "a cap is dollars, $0 to $#{Web::Grants::MAX_CAP.to_i} (e.g. --cap 5)".freeze
+    CAP_USAGE = "a cap is dollars, $0 to $#{Grants::MAX_CAP.to_i} (e.g. --cap 5)".freeze
 
     def run_cap(_options, args)
       return usage_error("give a session ID, a participant and dollars (chi share cap ID p_… 5)") unless args.size == 3
 
       participant = args[1]
-      return usage_error("not a participant: #{participant} (chi share ls lists them)") unless Web::Grants::ID_RE.match?(participant)
+      return usage_error("not a participant: #{participant} (chi share ls lists them)") unless Grants::ID_RE.match?(participant)
 
       cap = dollars(args[2])
       return usage_error(CAP_USAGE) if cap == false
@@ -172,7 +172,7 @@ module Samagotchi
       return false unless text.match?(/\A\d+(?:\.\d+)?\z/)
 
       value = text.to_f
-      Web::Grants.cap?(value) ? value : false
+      Grants.cap?(value) ? value : false
     end
 
     def money(value) = value.nil? ? "-" : format("$%.2f", value)
@@ -184,7 +184,7 @@ module Samagotchi
         return usage_error("give a session ID (and a participant), or --all")
       end
       participant = args[1]
-      return usage_error("not a participant: #{participant} (chi share ls lists them)") if participant && !Web::Grants::ID_RE.match?(participant)
+      return usage_error("not a participant: #{participant} (chi share ls lists them)") if participant && !Grants::ID_RE.match?(participant)
 
       id = args.first && @access.resolve(args.first)
       revoked = @access.revoke_participants(id, participant: participant)

data/lib/samagotchi/steer.rb

@@ -136,7 +136,7 @@ module Samagotchi
     PARTICIPANT_SOURCE = "participant"
     # The owner's author, when one is written out; absent means the same.
     OWNER_AUTHOR = "owner"
-    # A participant's author: this prefix, then its id (Web::Grants'
+    # A participant's author: this prefix, then its id (Grants'
     # grant id), "p:<id>" (#author_for, #participant_id).
     PARTICIPANT_PREFIX = "p:"
     # A participant's message's keys, which every message copy keeps.

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,11 +75,7 @@ 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) }
     end
 
@@ -386,11 +383,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 +402,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 +438,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 +470,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 +548,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 +565,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 +610,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 +655,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 +668,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 +694,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