samagotchi 0.153.0 → 0.154.0

data/lib/samagotchi/session_commands.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "config"
+require_relative "degrade"
 require_relative "model_profile"
 require_relative "served_model"
 require_relative "prompt_note"
@@ -31,7 +32,7 @@ module Samagotchi
   # load budget (spec/samagotchi/testing/sandbox_spec.rb).
   autoload :ObjectivesCommand, File.expand_path("objectives_command", __dir__)
 
-  # The session commands a REPL and a session worker both run: /model,
+  # The session commands a session worker runs (a -p one-shot too): /model,
   # /models, /llm-context, /guardrails, /context, !rollback, !cmd and the answer to a continue offer. They act on
   # the Engine and its TurnFlow; the host prints the result's output and
   # runs a continue turn when asked to (#run never runs a turn).
@@ -159,24 +160,24 @@ module Samagotchi
       registry.register("/quit", "leave, like /exit", id: :exit, local: true, match: exit_match("/quit"))
       registry.register("/archive", "leave and archive the session: hidden from the lists, kept for good", local: true,
                                                                                                           match: ->(text) { text.casecmp?("/archive") })
-      # The REPL owns its session: it answers /detach with a note, and doesn't offer it.
+      # The terminal's: the web has no worker to leave running.
       registry.register("/detach", "leave and keep the worker running", local: true, uis: [:attached],
                                                                         match: ->(text) { text.casecmp?("/detach") })
       # /cut TEXT and /queue TEXT while a turn runs: a delivery the UIs parse
       # themselves (ComposerRoute.steer_choice) before any command check; the
       # entries exist for Tab completion and /help. The web composer sends
-      # /cut too (its queue is Alt+Enter). Both terminals queue: the REPL in
-      # its own list, the attached TUI's worker in its input files.
+      # /cut too (its queue is Alt+Enter). The attached TUI queues in its
+      # worker's input files.
       registry.register("/cut", "cut the running generation and go in now (/cut TEXT)",
-                        local: true, uis: %i[repl attached web], match: ->(text) { text.casecmp?("/cut") || text.match?(%r{\A/cut\s+\S}) })
+                        local: true, uis: %i[attached web], match: ->(text) { text.casecmp?("/cut") || text.match?(%r{\A/cut\s+\S}) })
       registry.register("/queue", "run as the next turn after this one (/queue TEXT)",
-                        local: true, uis: %i[repl attached], match: ->(text) { text.casecmp?("/queue") || text.match?(%r{\A/queue\s+\S}) })
+                        local: true, uis: [:attached], match: ->(text) { text.casecmp?("/queue") || text.match?(%r{\A/queue\s+\S}) })
       # Takes back the newest message this attached TUI queued, before it
       # runs (the worker's POST turn/dequeue); the web has × on the bubble.
       registry.register("/unqueue", "remove your newest queued message before it runs", local: true, uis: [:attached],
                                                                                           match: ->(text) { text.casecmp?("/unqueue") })
       # chi share for the attached session (TerminalUI::ParticipantCommands):
-      # a participant's turns run on its worker, so the REPL points there.
+      # a participant's turns run on its worker.
       registry.register("/share", "invite someone to review this session (/share NAME [--agent] [--expires 3d] [--cap 2])",
                         local: true, uis: [:attached], match: ->(text) { text.match?(%r{\A/share(?:\s.*)?\z}i) })
       registry.register("/participants", "list this session's participants (revoke [P], cap P DOLLARS)",
@@ -286,15 +287,15 @@ module Samagotchi
       "commands:\n#{lines.join("\n")}"
     end
 
-    # Where a UI's own entry runs, for /help: both terminals are
-    # "terminal" (also for no uis: every terminal), then "web".
+    # Where a UI's own entry runs, for /help: the attached TUI is
+    # "terminal" (also for no uis: the terminal), then "web". An older
+    # worker's :repl is no UI any more.
     # @param uis [Array<Symbol>, nil]
-    # @return [String] "terminal", "repl", "terminal and web" …
+    # @return [String] "terminal", "web", "terminal and web"
     def ui_words(uis)
       return "terminal" if uis.nil?
 
-      terminals = uis & %i[repl attached]
-      words = terminals.size == 2 ? ["terminal"] : terminals.map(&:to_s)
+      words = uis.include?(:attached) ? ["terminal"] : []
       words << "web" if uis.include?(:web)
       words.join(" and ")
     end
@@ -309,8 +310,8 @@ module Samagotchi
     # @param as_parent [Boolean] a parent agent sent it (client cli:answer):
     #   a /continue yes is held to guardrails.parent_answers, as chi
     #   answer --option Continue is (Guardrails::ParentPolicy)
-    # @param user_ui [Boolean] a user at a UI sent it (the REPL, an attached
-    #   TUI, the web; not a piped or marked one): only such a line loosens
+    # @param user_ui [Boolean] a user at a UI sent it (an attached TUI, the
+    #   web; not a piped or marked one): only such a line loosens
     #   /parent-answers
     # @return [Result, nil] nil when +line+ is not one of these commands
     def run(line, confirm: true, as_parent: false, user_ui: false)
@@ -427,7 +428,7 @@ module Samagotchi
     end
 
     # The output goes into the conversation for the next turn. Not saved
-    # here (as in the REPL, the next turn saves it). No parent-session
+    # here (the next turn saves it). No parent-session
     # marker: the user runs this, not the model. A worker's `chi --model X`
     # default is unset, though: it was that run's, not the default of a chi
     # run here (Tools::Builtins.cli_model_unset). It runs in the session's
@@ -726,7 +727,7 @@ module Samagotchi
 
     # /recap on|off|default (RecapCommand); :recap in changed when this
     # session's own recap.enabled moved. It doesn't save: its host does on
-    # a changed result (Worker#run_command, the REPL).
+    # a changed result (Worker#run_command).
     def recap_setting(text)
       output, changed, status = RecapCommand.new(engine: @engine).run(text.delete_prefix(RECAP_COMMAND))
       reply(output, status: status, changed: changed ? [:recap] : [])
@@ -884,65 +885,61 @@ module Samagotchi
       return unless session
 
       @engine.store_model!(session)
-      begin
-        @save.call(session)
-      rescue StandardError
-        nil
-      end
+      Degrade.call(:model, "model_switch_save_failed") { @save.call(session) }
     end
 
     # "; served: <name>" when the server serves another model than asked
     # and its host's served: doesn't expect it.
     def served_note
-      served, asked = @engine.served_model
-      ServedModel.differs?(asked, served) && !@engine.served_expected?(served) ? "; served: #{served}" : ""
-    rescue StandardError
-      ""
+      Degrade.call(:model, "served_note_failed", fallback: "") do
+        served, asked = @engine.served_model
+        ServedModel.differs?(asked, served) && !@engine.served_expected?(served) ? "; served: #{served}" : ""
+      end
     end
 
     # "; sampling: temperature=0.6 (hosts.work)" when the model has any.
     def sampling_note
-      summary = @engine.sampling_summary
-      summary ? "; sampling: #{summary}" : ""
-    rescue StandardError
-      ""
+      Degrade.call(:model, "sampling_note_failed", fallback: "") do
+        summary = @engine.sampling_summary
+        summary ? "; sampling: #{summary}" : ""
+      end
     end
 
     # "; steer cut: after 60 s (models: qwen)", or "; steer cut: never
     # (hosts.splash)" for 0 or less, when the model has one configured;
     # "" for the default.
     def steer_cut_after_note
-      summary = @engine.steer_cut_summary
-      summary ? "; steer cut: #{summary}" : ""
-    rescue StandardError
-      ""
+      Degrade.call(:model, "steer_cut_note_failed", fallback: "") do
+        summary = @engine.steer_cut_summary
+        summary ? "; steer cut: #{summary}" : ""
+      end
     end
 
     # "; notes: model_notes_deepseek (system, 612 chars)": the model notes
     # the session's prompt carries (after a switch, the ones the new
     # model's prompt loads); "" without any.
     def notes_note
-      text = PromptNote.text(@engine.prompt_notes)
-      text.empty? ? "" : "; notes: #{text}"
-    rescue StandardError
-      ""
+      Degrade.call(:model, "notes_note_failed", fallback: "") do
+        text = PromptNote.text(@engine.prompt_notes)
+        text.empty? ? "" : "; notes: #{text}"
+      end
     end
 
     # "; thinking: off (models: qwen)" when the model has a level set.
     def thinking_note
-      summary = @engine.thinking_summary
-      summary ? "; thinking: #{summary}" : ""
-    rescue StandardError
-      ""
+      Degrade.call(:model, "thinking_note_failed", fallback: "") do
+        summary = @engine.thinking_summary
+        summary ? "; thinking: #{summary}" : ""
+      end
     end
 
     # "; reasoning history: drop (models: qwen)" when the chat model has a
     # level set.
     def reasoning_history_note
-      summary = @engine.reasoning_history_summary
-      summary ? "; reasoning history: #{summary}" : ""
-    rescue StandardError
-      ""
+      Degrade.call(:model, "reasoning_history_note_failed", fallback: "") do
+        summary = @engine.reasoning_history_summary
+        summary ? "; reasoning history: #{summary}" : ""
+      end
     end
 
     # " (default: x, profile=qwen36, name)": +extra+ and the prompt profile,
@@ -954,9 +951,9 @@ module Samagotchi
     end
 
     def chat_model?
-      @engine.chat_model?
-    rescue StandardError
-      false
+      Degrade.call(:model, "chat_model_unresolved", fallback: false) do
+        @engine.chat_model?
+      end
     end
 
     # "profile=qwen36, server (chat_template)": the profile and where it came from.

data/lib/samagotchi/session_continue.rb

@@ -24,7 +24,7 @@ module Samagotchi
     # A continue that can't happen (#run). reason: :continued
     # (another session continues it already: +ids+ names it), :open_children
     # (open children it can't move to the new link: on an older chi's
-    # worker or open in a chi REPL; +ids+ names them) or :folder_gone (its
+    # worker or open in a one-turn chi run; +ids+ names them) or :folder_gone (its
     # folder isn't there).
     class Refused < StandardError
       attr_reader :session_id, :reason, :ids

data/lib/samagotchi/session_delete_command.rb

@@ -9,7 +9,7 @@ require_relative "session_access/local"
 module Samagotchi
   # `chi sessions delete`: remove sessions for good (SessionManager.delete_session),
   # one line per id. A live worker's session is refused unless --force stops
-  # the worker first; a chi REPL's never is.
+  # the worker first; a one-turn chi run's never is.
   class SessionDeleteCommand
     include CLI::Command
 
@@ -18,8 +18,8 @@ module Samagotchi
         Deletes each session: its history, notes, images and queued input.
         This can't be undone.
         -f, --force   stop a session's running worker first (without it,
-                      a live session is refused); a session open in a
-                      chi REPL is always refused
+                      a live session is refused); a session in a one-turn
+                      chi run (chi --non-interactive) is always refused
     TEXT
     PREVIEW_LIMIT = 60
     FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) { |f| f.switch "-f", "--force" }
@@ -67,7 +67,7 @@ module Samagotchi
       @stdout.puts(["#{short}  deleted#{" (stopped its worker)" if result[:stopped]}", preview].compact.join("  "))
       true
     rescue SessionManager::OwnedByTUI
-      @stdout.puts("#{short}  refused: it is open in a chi REPL; close it there first")
+      @stdout.puts("#{short}  refused: it is #{OwnerLock::TUI_BUSY}; let it finish first")
       false
     rescue SessionManager::DeleteRefused => e
       line = if e.reason == :still_stopping then "its worker is still shutting down; try again in a moment"

data/lib/samagotchi/session_manager.rb

@@ -81,23 +81,32 @@ module Samagotchi
   autoload :SessionRetention, File.expand_path("session_retention", __dir__)
   # session_continue requires this file.
   autoload :SessionContinue, File.expand_path("session_continue", __dir__)
-  # Needed only on an archive or a delete (it loads Web::Grants).
+  # Needed only on an archive or a delete (it loads Grants).
   autoload :Participants, File.expand_path("participants", __dir__)
 
   class SessionManager
-    # Raised when the interactive TUI owns the session: it runs its own Engine
-    # and reads no input files, so a worker must not be spawned or signalled.
+    # Raised when a terminal's own chi owns the session (OwnerLock kind
+    # "tui": a -p --non-interactive one-shot, TerminalUI): it runs its own
+    # Engine and reads no input files, so a worker must not be spawned or
+    # signalled.
     class OwnedByTUI < StandardError
-      # @return [String] the session the REPL owns (a delegate's, when an
-      #   archive met one)
+      # @return [String] the session it owns (a delegate's, when an archive
+      #   met one)
       attr_reader :session_id
 
-      def initialize(session_id)
+      def initialize(session_id, words = nil)
         @session_id = session_id
-        super("session #{session_id} is open in a chi REPL; close it there first")
+        super(words || "session #{session_id} is #{OwnerLock::TUI_BUSY}; let it finish first")
       end
     end
 
+    # A `chi scratch` session: its terminal's alone (Session::SCRATCH_REFUSED).
+    # An OwnedByTUI, so every caller that refuses a terminal's session
+    # (chi send, chi web's 409 owned_by_tui) refuses it the same way.
+    class ScratchSession < OwnedByTUI
+      def initialize(session_id) = super(session_id, Session::SCRATCH_REFUSED)
+    end
+
     # A delete that would pull the session from under its live worker.
     # reason: :worker_running (not asked to stop it) or :still_stopping
     # (stopped, but the worker outlived the wait).
@@ -173,12 +182,15 @@ module Samagotchi
     #   requester, rules and claim (VerifyFresh.start)
     # @param before_spawn [#call, nil] (session) runs once the session and
     #   its note are saved, before its worker spawns
+    # @param scratch [Boolean] a `chi scratch` session (its terminal's
+    #   AttachLauncher): its worker runs a scratch Engine and deletes it
+    #   once its last client is gone
     # @return [Session] with #seed_images_dropped: refs whose file was gone,
     #   and #model_warning: an id its host's saved list doesn't have
     def self.spawn_session(prompt:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
                            memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
                            preview: nil, title: nil, delegate: false, setup: SessionSetup.new, continues: nil, note: nil,
-                           note_source: "chi", before_spawn: nil, review: nil, verify_fresh: nil)
+                           note_source: "chi", before_spawn: nil, review: nil, verify_fresh: nil, scratch: false)
       sd = state_dir || Session.default_state_dir
       # The resolved ref is stored (a resumed session keeps its model when an
       # alias is retargeted), with the name as typed beside it. A wrong host
@@ -201,7 +213,8 @@ module Samagotchi
         delegate: delegate,
         setup: setup,
         continues: continues,
-        review: review
+        review: review,
+        scratch: scratch
       )
       session.toolkit = Toolkit.configured(delegate: delegate) if session.toolkit.nil?
       session.toolkit_origin = setup.toolkit_origin || "default"
@@ -316,7 +329,8 @@ module Samagotchi
     # +project_root+ unless asked for every project.
     # @param live [Boolean] only sessions a worker owns now (the owner lock,
     #   not the saved status, which a dead worker leaves at "running"); a
-    #   REPL-owned session is left out: it can't take notes
+    #   session a one-shot (or an older chi's REPL) owns is left out: it
+    #   can't take notes
     # @param cwd [String, nil] only sessions in this folder or below it
     # @param project_root [String, nil] only this project's sessions
     #   (Session#project_root)
@@ -405,7 +419,7 @@ module Samagotchi
     # stopped first; the marker is written even while it shuts down.
     # @return [ArchiveResult]
     # @raise [ArgumentError] unknown id (Session::AmbiguousId for a prefix of several)
-    # @raise [OwnedByTUI] a chi REPL owns it or one of its children
+    # @raise [OwnedByTUI] a one-turn chi run owns it or one of its children
     # @raise [ArchiveRefused] a turn runs in it or in a child, a prompt is
     #   queued in one (a later resume would run it), a live one offers to
     #   continue past the step limit, or it is a scratch session
@@ -447,7 +461,7 @@ module Samagotchi
     # turn runs), :queued (input/ holds a prompt, which outlives the stop and
     # runs on a resume, live worker or not), :offer (a live worker's continue
     # offer, which the stop would drop), or nil.
-    # @raise [OwnedByTUI] a chi REPL owns it
+    # @raise [OwnedByTUI] a one-turn chi run owns it
     def self.archive_refusal(sid, owner, state_dir)
       raise OwnedByTUI, sid if owner&.tui?
 
@@ -555,6 +569,8 @@ module Samagotchi
     def self.resume_session(session_id, state_dir: nil)
       sd = state_dir || Session.default_state_dir
       session = Session.load(session_id, state_dir: sd)
+      # Its terminal's worker came from spawn_session; nothing wakes another.
+      raise ScratchSession, session.id if session.scratch
       return session if refuse_tui!(session.id, state_dir: sd)
 
       # status is turn state, not liveness: a new worker runs no turn yet,
@@ -576,7 +592,7 @@ module Samagotchi
 
     # A delegate child rang a parent that has no worker (ChildRing): start
     # one, which runs a turn for the report. Not for a parent that is gone,
-    # stopped, archived, a scratch session, open in a chi REPL, or a
+    # stopped, archived, a scratch session, a one-turn run's, or a
     # continue's new link still taking its delegates (its own spawn comes):
     # the ring waits on disk for whoever runs it next (#resume_session
     # itself would clear the stop). A stop landing between the check and
@@ -686,7 +702,8 @@ module Samagotchi
         reminders: "it has reminders, which its worker's older chi can't carry over a restart",
         command_running: "a /btw (or another command) is still running",
         relays_open: "a delegate's approval relayed here is open or just answered",
-        background_tasks: "background tasks it started are still running"
+        background_tasks: "background tasks it started are still running",
+        scratch: "a chi scratch session's worker ends with its terminal"
       }.merge(WorkerIdleExit::LEAVING_WORDS).freeze
 
       # What the CLI and the web say.
@@ -726,7 +743,7 @@ module Samagotchi
     # be lost and starts its successor. If the worker cannot be asked, stop
     # it without a stop marker and resume only when disk shows no work to lose.
     # @return [Restarted]
-    # @raise [OwnedByTUI] a chi REPL owns the session
+    # @raise [OwnedByTUI] a one-turn chi run owns the session
     # @raise [RestartRefused]
     # @raise [ArgumentError] no such session
     def self.restart_session(session_id, state_dir: nil, wait: RESTART_WAIT, client_id: ClientId::CLI_RESTART)
@@ -917,7 +934,7 @@ module Samagotchi
     EMPTY_SKELETON_DIRS = (EMPTY_DIRS + [SessionInbox::OUTPUT_DIR]).freeze
 
     # session.keep_empty off: sessions left with nothing in them are deleted
-    # (the worker as it exits, the TUI at /exit, the retention sweep).
+    # (the worker as it exits, the retention sweep).
     def self.discard_empty?
       Samagotchi::Config.get("session.keep_empty") != true
     rescue StandardError
@@ -926,25 +943,14 @@ module Samagotchi
 
     # Whether a session being left (or found left) is deleted: session.keep_empty
     # is off and nothing happened in it (#empty_session?). The worker as it
-    # leaves, the REPL at /exit and the retention sweep all ask this.
+    # leaves and the retention sweep both ask this.
     # @param default_model [String, nil] what a new session starts on
-    # @param model_name [String, nil] the model its owner runs now (the REPL
-    #   keeps /model in its Engine); the saved one is checked either way
     # @param used_memory_names [Array<String>] memory its owner's Engine used
     #   before any save
-    # @param unsaved [Session, nil] the REPL's working copy, judged instead
-    #   when the session was never saved
-    def self.discardable?(session_id, default_model:, state_dir: nil, model_name: default_model, used_memory_names: [],
-                          unsaved: nil)
-      return false unless discard_empty? && same_model?(model_name, default_model) && Array(used_memory_names).empty?
-
-      sd = state_dir || Session.default_state_dir
-      if unsaved && !File.exist?(Session.session_file(session_id, state_dir: sd))
-        return no_conversation?(unsaved.messages) && unsaved.last_prompt.to_s.strip.empty? &&
-               empty_session_dir?(Session.session_dir(session_id, state_dir: sd))
-      end
+    def self.discardable?(session_id, default_model:, state_dir: nil, used_memory_names: [])
+      return false unless discard_empty? && Array(used_memory_names).empty?
 
-      empty_session?(session_id, state_dir: sd, default_model: default_model)
+      empty_session?(session_id, state_dir: state_dir || Session.default_state_dir, default_model: default_model)
     end
 
     # A session nothing happened in: no conversation, no turn tried (a failed
@@ -976,7 +982,7 @@ module Samagotchi
       false
     end
 
-    # Only the system prompt (the REPL seeds one, a saved session keeps
+    # Only the system prompt (an Engine seeds one, a saved session keeps
     # it); a context note is a system message too, but with its kind.
     # A turn note (the tail system message after a failed, cancelled or empty
     # turn) is not a conversation either: a session whose only turn failed
@@ -1049,7 +1055,7 @@ module Samagotchi
     # @param stop [Boolean] stop a live worker first (waits +wait+ seconds)
     # @return [Hash] {id:, removed: [paths], stopped: whether a worker was stopped}
     # @raise [ArgumentError] unknown id (Session::AmbiguousId for a prefix of several)
-    # @raise [OwnedByTUI] a chi REPL owns it (never stopped from here)
+    # @raise [OwnedByTUI] a one-turn chi run owns it (never stopped from here)
     # @raise [DeleteRefused] a worker owns it and +stop+ is false, or it
     #   outlived the wait
     # @param purge_runs [Boolean] also delete System 1's saved runs of it and
@@ -1130,7 +1136,7 @@ module Samagotchi
     #   ticks (nil: Worker::FALLBACK_TICK_SECONDS); queued turns wake it at once
     # A stopped session's worker exits 0 (a signalled one too) and a
     # crashed one 1, there.
-    # @return [Symbol] :idle_exit, :exit_requested or :restart
+    # @return [Symbol] :idle_exit, :exit_requested, :restart or :scratch_left
     def self.run_session_loop(session_id, state_dir: nil, owner_wait: OwnerLock::DEFAULT_WAIT,
                               idle_exit_minutes: nil, poll_interval: nil)
       # A worker inherits chi's locale (LC_ALL=C too): read files as UTF-8.
@@ -1175,6 +1181,13 @@ module Samagotchi
         signals.restore!
       end
       Log.info(:worker, "stop", reason: result)
+      # A scratch session goes with its worker however it leaves (its
+      # terminal deletes it too, whichever comes first); nothing resumes it.
+      if worker.scratch?
+        delete_left_scratch(session_id, state_dir: sd)
+        exit(result == :crashed ? 1 : 0) if %i[stopped signal crashed].include?(result)
+        return result
+      end
       # A stopped session is left as it is: no resume for input that came
       # in, no discard. One whose worker a signal stopped isn't discarded
       # either; input that came in (queued behind the turn it stopped)
@@ -1231,6 +1244,16 @@ module Samagotchi
       Process.exit!(0)
     end
 
+    # Delete a scratch session its worker left (its terminal gone:
+    # Worker#leave_scratch, or any other way out), now the lock is free.
+    # Its terminal may have deleted it first.
+    private_class_method def self.delete_left_scratch(session_id, state_dir:)
+      delete_session(session_id, state_dir: state_dir)
+      Log.info(:worker, "scratch_deleted", sid: session_id)
+    rescue DeleteRefused, ArgumentError, SystemCallError => e
+      Log.info(:worker, "scratch_kept", sid: session_id, error: e.class.name, msg: e.message)
+    end
+
     # Delete a session its worker left empty. Checked again now the lock is
     # free: a note or input may have come in since the worker looked, and a
     # worker woken meanwhile owns it (delete_session refuses). A `chi send`
@@ -1477,7 +1500,7 @@ module Samagotchi
     #   a worker that doesn't queue (no file then: it would steer), :timeout
     #   when it took the request but never answered (no file then), or
     #   :failed when the input file couldn't be written
-    # @raise [OwnedByTUI] a chi REPL owns the session
+    # @raise [OwnedByTUI] a one-turn chi run owns the session
     # @raise [ArgumentError] no such session
     def self.deliver_turn(session_id, prompt:, client_id: nil, images: [], delivery: nil, no_interrupt: false,
                           author: nil, pending_limit: nil, anchors: nil, state_dir: nil, manager: self, bridge: nil)
@@ -1532,7 +1555,7 @@ module Samagotchi
       # A participant's file only for a worker started after it: a worker
       # still holding the session with its Bridge gone (exiting) may be an
       # older one, which would run it without the review boundary.
-      # (A chi REPL holding it is refused as for anyone, below.)
+      # (A one-turn chi run holding it is refused as for anyone, below.)
       if Steer.participant_author?(author) && (holder = delivery_owner(manager, session_id, state_dir)) && !holder.tui?
         return DeliverResult.new(status: :timeout, via: :file,
                                  ack: { "error" => "worker_timeout",

data/lib/samagotchi/session_metrics.rb

@@ -25,8 +25,8 @@ module Samagotchi
   # SessionMetrics is a persistent, error-isolated collector of per-session
   # analytics. It implements the same #call(event) sink contract as
   # SessionObserver subscribers, so Engine#run_turn feeds it (it forwards every
-  # event to its SessionObserver): the REPL, the -p/--non-interactive/--resume
-  # paths and SessionManager background workers.
+  # event to its SessionObserver): a --non-interactive one-shot and the
+  # session workers.
   #
   # Each finished turn leaves a record (status, timings, model, prompt and
   # completion tokens, tool calls, iterations, retries, cuts); session totals are

data/lib/samagotchi/session_model_settings.rb

@@ -7,6 +7,7 @@ require_relative "session_setting"
 require_relative "steer_cut"
 require_relative "steer_cut_after"
 require_relative "thinking"
+require_relative "session"
 
 module Samagotchi
   # The session's settings on its effective model, as the Engine reads them:
@@ -163,7 +164,7 @@ module Samagotchi
     # @raise [ArgumentError] with no session yet
     def reasoning_history_override=(level)
       session = @session.call
-      raise ArgumentError, "no session yet" unless session
+      raise ArgumentError, Session::NONE_YET unless session
 
       SessionSetting::REASONING_HISTORY.set(session, level)
     end
@@ -178,7 +179,7 @@ module Samagotchi
     # @raise [ArgumentError] with no session yet
     def thinking_override=(level)
       session = @session.call
-      raise ArgumentError, "no session yet" unless session
+      raise ArgumentError, Session::NONE_YET unless session
 
       SessionSetting::THINKING.set(session, level)
     end

data/lib/samagotchi/session_participants.rb

@@ -4,7 +4,7 @@ require_relative "steer"
 require_relative "participant_mode"
 
 module Samagotchi
-  # Loaded only when a session is read: it brings Web::Grants (and Rack).
+  # Loaded only when a session is read: it brings Grants.
   autoload :Participants, File.expand_path("participants", __dir__)
 
   # What a session's Engine knows of its participants: participants.json

data/lib/samagotchi/session_retention.rb

@@ -30,7 +30,7 @@ module Samagotchi
     DEFAULT_KEEP_STATUS = [].freeze
 
     # How long a session may sit empty before the sweep takes it: its
-    # worker (or a REPL) deletes it as it leaves, so the sweep only catches
+    # worker deletes it as it leaves, so the sweep only catches
     # those killed first (a reboot, kill -9).
     EMPTY_GRACE_SECONDS = 3600
 
@@ -69,7 +69,7 @@ module Samagotchi
     end
 
     # Directories with no session file and nothing but the skeleton, nobody
-    # owning them: a REPL killed before its first save, or a worker woken
+    # owning them: a one-shot killed before its first save, or a worker woken
     # just as its session was discarded.
     # @return [Array<String>] their ids
     private_class_method def self.prune_orphan_dirs(state_dir, dry_run:)
@@ -161,7 +161,7 @@ module Samagotchi
     # +any_age+ makes every session eligible, whatever its age and the
     # count (`chi sessions clean` with no --days: test runs are throwaway).
     #
-    # A scratch session nobody owns (its REPL was killed) goes whatever its
+    # A scratch session nobody owns (its terminal and worker were 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

data/lib/samagotchi/sessions_command.rb

@@ -21,7 +21,7 @@ module Samagotchi
   # `chi sessions`: list, stop, restart, archive/unarchive, delete, prune,
   # clean and stats 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).
+  # the slash commands a session's worker runs (session_commands.rb).
   class SessionsCommand
     include CLI::Command
 
@@ -207,15 +207,15 @@ module Samagotchi
       )
       case format
       when "json"
-        # owner: "worker", "tui" (a chi REPL: it takes no notes or messages)
+        # owner: "worker", "tui" (a one-turn chi run: 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
         # delegate: started by the delegate tool (a fork has a parent_id too)
         # continues: the session it continues (its chain's previous link), 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)
+        # scratch: a `chi scratch` session (deleted when its terminal leaves,
+        # a leftover one at the next sweep)
         # ctx_pct: how full the context was after the last turn, or nil
         # title: the session's own name (/title; desc shows it too), or nil;
         # auto_title: the one its recap gave it (RecapTitle), or nil