samagotchi 0.153.0 → 0.154.1

data/lib/samagotchi/project_env.rb

@@ -22,7 +22,7 @@ module Samagotchi
   # chi's own settings, keys, proxies or dirs (LLM calls, HostKeys, Config,
   # Paths, hooks, plugins). A pair turn's tools don't get it either. A
   # mise.toml edit reaches a session at its next worker (`chi sessions
-  # restart`). The REPL modes run no worker and keep the shell's env.
+  # restart`). A --non-interactive one-shot runs no worker and keeps the shell's env.
   # docs/sessions.md (Project env).
   #
   # And `chi` inside those tools stays the chi home's (ChiShim): the project's
@@ -75,7 +75,7 @@ module Samagotchi
     Overlay = Data.define(:env, :applied, :reason, :ruby) do
       def marker = applied ? "mise:#{ruby || "no ruby"}" : "none:#{reason}"
     end
-    # No project env: specs, the REPL modes, a worker before #install!.
+    # No project env: specs, a one-shot, a worker before #install!.
     NONE = Overlay.new(env: {}.freeze, applied: false, reason: "none", ruby: nil)
 
     class Failed < StandardError; end

data/lib/samagotchi/question_desk.rb

@@ -17,7 +17,8 @@ module Samagotchi
   # An Engine's question flow: the one open question (ask_user_question, a
   # hook's ask_user, a guardrail approval), its answer and its cancel, shared
   # by every UI. The turn thread blocks in #open_question; the UIs answer or
-  # cancel from theirs (a REPL answers inline through the sync handler).
+  # cancel from theirs (a --non-interactive run dismisses it inline through
+  # the sync handler).
   #
   # A standing question (#post: a worker's step-limit question, kind
   # "continue") blocks nobody: it waits between turns, its answer goes to
@@ -52,7 +53,7 @@ module Samagotchi
       end
 
       # The line for the parent (ParentPolicy.message).
-      # @param typed [Boolean] typed at a ? prompt (the REPL)
+      # @param typed [Boolean] typed at a terminal's ? prompt
       def detail(typed: false)
         Guardrails::ParentPolicy.message(reason, pending: @pending, strategy: @strategy, typed: typed)
       end
@@ -212,8 +213,8 @@ module Samagotchi
       id = pending.id
 
       # If a synchronous UI handler is registered (TUI), invoke it inline on the
-      # SAME thread that called request_question (TerminalUI's REPL thread is the
-      # turn thread — no second thread exists to answer). This avoids deadlock.
+      # SAME thread that called request_question (a --non-interactive run's
+      # TerminalUI thread is the turn thread — no second thread exists to answer). This avoids deadlock.
       # This path is TUI-specific but the surrounding emit/clear is generic, so
       # any future UI that registers a sync handler gets the same guarantee.
       if @sync_handler
@@ -369,7 +370,7 @@ module Samagotchi
 
     attr_writer :sync_handler
 
-    # @return [Boolean] a REPL answers inline (no wait loop)
+    # @return [Boolean] a sync handler answers inline (a --non-interactive run: no wait loop)
     def sync_handler? = !@sync_handler.nil?
 
     # Cancel the pending question (e.g. /cancel, a dismiss). Announces which
@@ -402,8 +403,8 @@ module Samagotchi
       true
     end
 
-    # A question through the question flow (REPL sync handler, attached TUI,
-    # web), single-select, kind "hook". A --non-interactive run has no one
+    # A question through the question flow (the one-shot's sync handler,
+    # attached TUI, web), single-select, kind "hook". A --non-interactive run has no one
     # to ask: nil at once. Anything but an answer (a sync handler's text, no
     # answer, cancelled) is nil too.
     # @param asked [HookQuestion] its effects (label => effect for a parent

data/lib/samagotchi/recap_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "config"
+require_relative "session"
 
 module Samagotchi
   # /recap on|off|default, the setting form of /recap (the bare /recap,
@@ -27,7 +28,7 @@ module Samagotchi
     def run(args)
       word = args.to_s.strip.downcase
       return [USAGE, false, :error] unless CHOICES.key?(word)
-      return ["no session yet", false, :error] unless @engine.session
+      return [Session::NONE_YET, false, :error] unless @engine.session
 
       value = CHOICES.fetch(word)
       changed = @engine.recap_override != value

data/lib/samagotchi/recap_setup.rb

@@ -42,7 +42,7 @@ module Samagotchi
       if session.key?("recap.enabled")
         return nil unless session["recap.enabled"]
       else
-        # The REPL and a worker pass nothing: the config is read here alone
+        # A worker passes nothing: the config is read here alone
         # (a scalar `recap: false` is only seen this way).
         return nil if recap.nil? && ConfigFile.recap_config == false
         return nil if Samagotchi::Config.get("recap.enabled") == false

data/lib/samagotchi/recap_store.rb

@@ -12,7 +12,7 @@ module Samagotchi
   # (title: the auto title the recap reply led with, RecapTitle; absent in
   # a recap saved before it, or when no reply gave one).
   # A separate file, so it never races the session-file save at the end of a
-  # turn. Follows the Engine's current session (the REPL can switch).
+  # turn. Follows the Engine's current session.
   class RecapStore
     FILE = "recap.json"
     # A session card's or the picker's recap line.

data/lib/samagotchi/redact.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Secret shapes and host paths out of what a participant gets (the
+  # session's folder as relative paths, home as ~). Defence in depth: the
+  # allowlist (Web::ParticipantView) is the control; this catches a key the
+  # model quoted in a reply, or one in a prompt. Also how the Engine reads a
+  # Verify quote and ObjectivesCheck a text: as a participant's page shows it.
+  # Pure, stdlib only: core files use it without loading chi web.
+  module Redact
+    # Who is looking: +author+ the participant's ("p:<id>"; nil for the
+    # owner through the participant view: nothing is theirs), +cwd+ the
+    # session's folder (tool paths are shown relative to it, only inside
+    # it), +home+ the folder shown as ~, +secrets+ literal strings never
+    # shown (the owner's token).
+    Viewer = Data.define(:author, :cwd, :home, :secrets) do
+      def initialize(author: nil, cwd: nil, home: Dir.home, secrets: [])
+        super(author: author, cwd: cwd, home: home, secrets: Array(secrets).map(&:to_s).reject(&:empty?))
+      end
+
+      def own?(author) = !self.author.nil? && author.to_s == self.author
+    end
+
+    MARK = "[redacted]"
+    PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----.*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|\z)/m
+    PATTERNS = [
+      PRIVATE_KEY,
+      /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{16,}/,
+      /\bgh[pousr]_[A-Za-z0-9]{20,}/,
+      /\bgithub_pat_[A-Za-z0-9_]{20,}/,
+      /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/,
+      /\bxox[abprs]-[A-Za-z0-9-]{10,}/,
+      /\bchp_[A-Za-z0-9_-]{20,}/,
+      # A one-time link code (LinkCodes::CODE_RE): a bearer credential
+      # until its grant expires (an owner's, 10 minutes).
+      /\bchc_[A-Za-z0-9_-]{43}/,
+      /\bAIza[0-9A-Za-z_-]{30,}/,
+      /\b[rs]k_(?:live|test)_[A-Za-z0-9]{16,}/,
+      /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/,
+      %r{https://hooks\.slack\.com/services/[A-Za-z0-9/_-]+}
+    ].freeze
+    # The value after an Authorization (or a Bridge's secret,
+    # BridgeSecret::HEADER) header or a token=/key= pair.
+    VALUES = [
+      /(\b(?:Authorization|X-Chi-Bridge):\s*(?:Bearer\s+|Basic\s+|Token\s+)?)[^\s"'`]+/i,
+      /((?<![A-Za-z0-9])[A-Za-z0-9_-]*?(?:token|api[_-]?key|access[_-]?key|secret|password|passwd)["']?\s*[=:]\s*["']?)[^\s"'&`,;}]+/i,
+      # A URL's password: scheme://user:PASSWORD@host.
+      %r{(\b[a-z][a-z0-9+.-]*://[^/\s:@]+:)[^@\s/]+(?=@)}i
+    ].freeze
+    # A text that ends where one of VALUES' values (or a private key's
+    # BEGIN line) would go on: a stream cut there would send the value
+    # on its own, unredacted (ParticipantStreamFilter never cuts there).
+    OPEN_VALUE = /(?:\b(?:Authorization|X-Chi-Bridge):\s*(?:(?:Bearer|Basic|Token)\s*)?|[A-Za-z0-9_-]*?(?:token|api[_-]?key|access[_-]?key|secret|password|passwd)["']?\s*(?:[=:]\s*["']?)?|-----BEGIN [A-Z0-9 ]*)\z/i
+
+    module_function
+
+    # +value+ with every string in it redacted (hash values, array items).
+    def deep(value, viewer)
+      case value
+      when String then text(value, viewer)
+      when Hash then value.transform_values { |item| deep(item, viewer) }
+      when Array then value.map { |item| deep(item, viewer) }
+      else value
+      end
+    end
+
+    def text(value, viewer)
+      out = value.dup
+      viewer.secrets.each { |secret| out = out.gsub(secret, MARK) }
+      PATTERNS.each { |pattern| out = out.gsub(pattern, MARK) }
+      VALUES.each { |pattern| out = out.gsub(pattern) { "#{Regexp.last_match(1)}#{MARK}" } }
+      out = within(out, viewer.cwd.to_s)
+      home = viewer.home.to_s
+      out = out.gsub(%r{#{Regexp.escape(home)}(?=/|\b|\z)}, "~") if home.length > 1
+      out
+    end
+
+    # +text+ with +dir+ (the session's folder) shown relative: "dir/x"
+    # as "x", "dir" alone as ".".
+    def within(text, dir)
+      return text if dir.length < 2
+
+      text.gsub(%r{#{Regexp.escape(dir)}(/|(?=\b|\z))}) { Regexp.last_match(1) == "/" ? "" : "." }
+    end
+  end
+end

data/lib/samagotchi/reminder_queue.rb

@@ -8,8 +8,8 @@ module Samagotchi
   #
   # The ReminderStore is the truth (a reminder is due once its interval
   # passed). This adds the names the idle tick found due and handed to the
-  # UI's callback (#note_pending): the worker and the REPL run a reminder
-  # turn while they are pending. A turn injects whatever is due then
+  # UI's callback (#note_pending): the worker runs a reminder turn while
+  # they are pending. A turn injects whatever is due then
   # (#inject!), which marks it fired and clears the pending names.
   class ReminderQueue
     # The reminders message's first line at +time+ (a Time in the zone to

data/lib/samagotchi/remote_attach_command.rb

@@ -15,7 +15,7 @@ module Samagotchi
   # attached TUI on a session of another machine, through its chi web
   # (bin/chi branches here after RunOptions.parse, before its own checks,
   # which are this machine's). The run flags come parsed; the ones that
-  # run this machine's REPL or read its files were refused already
+  # run this machine's Engine or read its files were refused already
   # (SessionAccess::Contract::RUN). The setup flags go as typed: that
   # machine checks them against its own config and bundles.
   class RemoteAttachCommand

data/lib/samagotchi/reply_wait/poll.rb

@@ -160,7 +160,7 @@ module Samagotchi
       end
 
       # Only a question a live worker holds waits for an answer (the lists'
-      # rule): one a dead worker left waits for no one, and a chi REPL's is
+      # rule): one a dead worker left waits for no one, and a one-turn chi run's is
       # answered there.
       def question(session)
         pending = session.pending_question
@@ -171,7 +171,7 @@ module Samagotchi
         Result.new(status: :waiting_for_answer, question: pending, session: session)
       end
 
-      # A worker holds the session's lock (a chi REPL's question is its own).
+      # A worker holds the session's lock (a one-turn chi run's question is its own).
       def worker_owned?
         WorkerLink.resolve(Session.session_dir(@id, state_dir: @state_dir), unlink: false).worker_owned?
       end

data/lib/samagotchi/review_start.rb

@@ -143,7 +143,7 @@ module Samagotchi
     end
 
     # What inviting a participant to +session+ now means: the grant's mode
-    # (Web::Grants::PAIR_MODE only when the owner is shown PAIR_WARNING: a
+    # (Grants::PAIR_MODE only when the owner is shown PAIR_WARNING: a
     # working session whose live worker runs pair turns; nil otherwise, a
     # review participant), the mode their turns get (:pair or :review) and
     # the warning shown for it (nil for a review session). One read of the

data/lib/samagotchi/run_options.rb

@@ -14,7 +14,7 @@ module Samagotchi
   module RunOptions
     # The flags an underscored spelling is refused for (--recap_base_url),
     # with the config registry's.
-    KNOWN = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --dir --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token --tunnel --start-dir].freeze
+    KNOWN = %w[--prompt --resume --attach --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --dir --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token --tunnel --start-dir].freeze
 
     # An OptionParser that also records each switch it took, as the
     # normalized [flag] or [flag, value] (a --[no-]x as --x or --no-x; an
@@ -221,12 +221,11 @@ module Samagotchi
           (each subcommand takes --help)
 
         BANNER
-        opts.on("-p", "--prompt PROMPT", "Run PROMPT as the first turn, then stay in the session (attached; the REPL with --no-shared)") { |p| options[:prompt] = p }
+        opts.on("-p", "--prompt PROMPT", "Run PROMPT as the first turn, then stay in the session (attached; one turn and out with --non-interactive)") { |p| options[:prompt] = p }
         opts.on("--resume SESSION_ID", "Resume a previous session by its ID (or a unique prefix of it)") { |s| options[:resume] = s }
         opts.on("--attach SESSION_ID", "Attach to a session's worker, waking one if it has exited; ID or a unique prefix") { |s| options[:attach] = s }
         opts.on("--dir DIR", "With --remote: a new session's folder on that machine, its absolute path (required there; " \
                              "here cd instead)") { |d| options[:dir] = d }
-        opts.on("--[no-]shared", "Run the session in a background worker and attach to it, so `chi web` can share it (the default, config session.shared; with --resume: that session); --no-shared runs a plain in-process REPL") { |v| options[:shared] = v }
         opts.on("--model NAME", "Model for this run, not saved (overrides --resume's; config default.model) [env SAMAGOTCHI_DEFAULT_MODEL]") { |m| options[:model] = m; cli_overrides["default.model"] = m }
         opts.on("--profile NAME", Samagotchi::ModelProfile::NAMES,
                 "Prompt profile for every model in this run (#{Samagotchi::ModelProfile::NAMES.join("|")}) [alias for --model-profile]") { |p| cli_overrides["model.profile"] = p }
@@ -260,9 +259,10 @@ module Samagotchi
         opts.on("--llm-context-apply RULE", "This session's own apply rule for it: payoff|next_request|turn_end") { |v| (options[:llm_context] ||= {})[:apply] = v }
         opts.on("--llm-context-budget TOKENS", "This session's own context budget: tokens (64000, 64k) or off") { |v| (options[:llm_context] ||= {})[:budget_tokens] = v }
         opts.on("--no-interrupt", "Raise the tool call limit to 1000 iterations (useful for long tasks)") { options[:no_interrupt] = true; cli_overrides["no_interrupt"] = true }
-        opts.on("--non-interactive", "Run a single prompt and exit (no REPL, implies --no-interrupt)") { options[:non_interactive] = true }
-        opts.on("-v", "--verbose", "Print raw LLM responses and tool calls/results (runs a plain REPL, not attached)") { options[:verbose] = true }
-        opts.on("--no-default-input", "Skip default REPL input prefill") { options[:no_default_input] = true; cli_overrides["no_default_input"] = true }
+        opts.on("--non-interactive", "Run the -p prompt in this process, one turn, and exit (implies --no-interrupt)") { options[:non_interactive] = true }
+        opts.on("-v", "--verbose", "Show the session's debug records (raw LLM responses, tool calls/results) as they come; " \
+                                 "a worker this chi starts logs at debug (with --non-interactive: on stderr)") { options[:verbose] = true }
+        opts.on("--no-default-input", "Skip the default input typed into a new session's first read (SAMAGOTCHI_DEFAULT_INPUT)") { options[:no_default_input] = true; cli_overrides["no_default_input"] = true }
         opts.on("--port PORT", "Port for `chi web` (default: 4567, env SAMAGOTCHI_WEB_PORT)") { |p| options[:web_port] = p.to_i; cli_overrides["web.port"] = p.to_s }
         opts.on("--open", "Open browser for `chi web`") { options[:web_open] = true }
         opts.on("--new-token", "`chi web`: replace the LAN access token (web.host: lan); links and QR codes made with the old one stop working") { options[:new_token] = true }

data/lib/samagotchi/self_report.rb

@@ -3,6 +3,7 @@
 require_relative "version"
 require_relative "config"
 require_relative "context_window"
+require_relative "degrade"
 require_relative "session"
 require_relative "log_path"
 require_relative "model_profile"
@@ -177,19 +178,19 @@ module Samagotchi
 
     # [tokens, "models: KEY" | "hosts.NAME"], or nil when neither is set.
     def model_window(env, model)
-      return nil unless model
-
-      registry = HostRegistry.new(env: env)
-      target = registry.resolve(model)
-      names = registry.lookup_names(model, target: target)
-      models = ConfigFile.model_settings(env: env)
-      window = ContextWindow.setting(target, names: names, models: models)
-      return nil unless window
-      return [window.tokens, "hosts.#{target.entry.name}"] if window.source == :host_setting
-
-      [window.tokens, "models: #{ConfigFile.model_setting(names, :window_tokens, models: models).key}"]
-    rescue StandardError
-      nil
+      Degrade.call(:config, "model_window_unreadable") do
+        return nil unless model
+
+        registry = HostRegistry.new(env: env)
+        target = registry.resolve(model)
+        names = registry.lookup_names(model, target: target)
+        models = ConfigFile.model_settings(env: env)
+        window = ContextWindow.setting(target, names: names, models: models)
+        return nil unless window
+        return [window.tokens, "hosts.#{target.entry.name}"] if window.source == :host_setting
+
+        [window.tokens, "models: #{ConfigFile.model_setting(names, :window_tokens, models: models).key}"]
+      end
     end
 
     SESSION_MODEL_ENV = "SAMAGOTCHI_SESSION_MODEL"
@@ -220,11 +221,11 @@ module Samagotchi
     end
 
     def same_model?(one, other, env)
-      return true if one == other
+      Degrade.call(:config, "model_ref_unresolved", fallback: false) do
+        return true if one == other
 
-      ConfigFile.model_ref(one, env: env).ref == ConfigFile.model_ref(other, env: env).ref
-    rescue StandardError
-      false
+        ConfigFile.model_ref(one, env: env).ref == ConfigFile.model_ref(other, env: env).ref
+      end
     end
 
     # The memory overlay key (ModelOverlay.key_for the bare id, as the
@@ -257,41 +258,41 @@ module Samagotchi
     # session chi self runs in has one (an alias), else of the name chi self
     # reports. nil when that is the key itself. Read-only, never raising.
     def fallback_model_key(model, key, env)
-      typed = session_typed_model(env) || model
-      typed_key = ModelOverlay.key_for(HostRegistry.new(env: env).parse_qualified_model(typed).last)
-      typed_key == key ? nil : typed_key
-    rescue StandardError
-      nil
+      Degrade.call(:model, "fallback_key_unresolved") do
+        typed = session_typed_model(env) || model
+        typed_key = ModelOverlay.key_for(HostRegistry.new(env: env).parse_qualified_model(typed).last)
+        typed_key == key ? nil : typed_key
+      end
     end
 
     # The model name the session chi self runs in was typed as (an alias),
     # its model_typed, else nil.
     def session_typed_model(env)
-      id = env[PARENT_SESSION_ENV].to_s
-      return nil if id.empty? || !Session.valid_id?(id)
+      Degrade.call(:config, "session_typed_model_unreadable") do
+        id = env[PARENT_SESSION_ENV].to_s
+        return nil if id.empty? || !Session.valid_id?(id)
 
-      state_dir = Session.default_state_dir(env: env)
-      return nil unless Session.exist?(id, state_dir: state_dir)
+        state_dir = Session.default_state_dir(env: env)
+        return nil unless Session.exist?(id, state_dir: state_dir)
 
-      session = Session.load(id, state_dir: state_dir)
-      typed = session.model_typed.to_s.strip
-      typed.empty? ? nil : typed
-    rescue StandardError
-      nil
+        session = Session.load(id, state_dir: state_dir)
+        typed = session.model_typed.to_s.strip
+        typed.empty? ? nil : typed
+      end
     end
 
     # The --mute list of the session chi self runs in (its execute exports
     # SAMAGOTCHI_PARENT_SESSION); [] outside one.
     def session_muted(env)
-      id = env[PARENT_SESSION_ENV].to_s
-      return [] if id.empty? || !Session.valid_id?(id)
+      Degrade.call(:config, "session_mutes_unreadable", fallback: []) do
+        id = env[PARENT_SESSION_ENV].to_s
+        return [] if id.empty? || !Session.valid_id?(id)
 
-      state_dir = Session.default_state_dir(env: env)
-      return [] unless Session.exist?(id, state_dir: state_dir)
+        state_dir = Session.default_state_dir(env: env)
+        return [] unless Session.exist?(id, state_dir: state_dir)
 
-      MutedMemories.normalize_list(Session.load(id, state_dir: state_dir).muted_memory_names)
-    rescue StandardError
-      []
+        MutedMemories.normalize_list(Session.load(id, state_dir: state_dir).muted_memory_names)
+      end
     end
 
     def model_name
@@ -489,7 +490,9 @@ module Samagotchi
 
     # "samagotchi-system 0.1.5 (shipped 0.1.5), other 1.0.0"
     def bundles_summary
-      shipped = MemoryBundle::Manifest.read(dir: MemoryBundle::SystemBundle::GEM_BUNDLE_DIR).version rescue nil
+      shipped = Degrade.call(:memory, "shipped_bundle_unreadable") do
+        MemoryBundle::Manifest.read(dir: MemoryBundle::SystemBundle::GEM_BUNDLE_DIR).version
+      end
       installed = MemoryBundle::Provenance.each_installed.map do |name, bundle|
         version = bundle.version || "?"
         label = "#{name} #{version}"

data/lib/samagotchi/send_command/busy.rb

@@ -23,7 +23,7 @@ module Samagotchi
     #   parent_answers
     Busy = Data.define(:error, :session_id, :question, :strategy) do
       # @param session [Session] the session as just read
-      # @param owner [OwnerLock::Owner, nil] the worker or REPL that owns it
+      # @param owner [OwnerLock::Owner, nil] the worker or one-shot that owns it
       # @param queue [Boolean] chi send --queue
       # @return [Busy, nil] nil when the message may go in
       def self.for(session, owner:, queue:)

data/lib/samagotchi/send_command.rb

@@ -799,8 +799,11 @@ module Samagotchi
              end
       @info.puts("#{short}  sent#{with_images}#{note}")
       true
+    rescue SessionManager::ScratchSession => e
+      @info.puts("#{short}  refused: #{e.message}")
+      false
     rescue SessionManager::OwnedByTUI
-      @info.puts("#{short}  refused: it is open in a chi REPL; messages need attached mode")
+      @info.puts("#{short}  refused: it is #{OwnerLock::TUI_BUSY}; send once it ends")
       false
     rescue StandardError => e
       @info.puts("#{short}  failed: #{e.message}")

data/lib/samagotchi/session.rb

@@ -38,6 +38,11 @@ module Samagotchi
     STATUS_ERROR = "error"
     STATUS_STOPPED = "stopped"
     TOOLKIT_ORIGINS = %w[chosen default inherited suggested].freeze
+    # Why anything but the terminal that started a `chi scratch` session is
+    # refused it (chi --attach/--resume, chi send, chi web's wake, turn and
+    # command routes): one wording for a live one and a leftover one.
+    SCRATCH_REFUSED = "that's a chi scratch session: only the terminal that started it uses it " \
+                      "(a leftover one is deleted at the next sweep: chi sessions clean)"
 
     # A stopped session's marker, <session dir>/stopped: a stop (chi
     # sessions stop, from another process) creates it instead of rewriting
@@ -54,6 +59,9 @@ module Samagotchi
     # The memory a delegate child starts with (Tools::Delegate::CHILD_MEMORIES).
     DELEGATE_MEMORY = "system/delegated"
 
+    # What a command answers when there is no session to act on yet.
+    NONE_YET = "no session yet"
+
     SORT_KEYS = %w[created_at updated_at].freeze
     SORT_ORDERS = %w[asc desc].freeze
 
@@ -116,8 +124,9 @@ module Samagotchi
     # nil. Not a parent: archiving one link leaves the next alone. The chain
     # itself is derived (SessionChain), never stored.
     attr_accessor :continues
-    # A `chi scratch` session: deleted when its REPL ends, and by the next
-    # sweep (or `chi sessions clean`) when the process died first.
+    # A `chi scratch` session: deleted when its terminal leaves (its worker
+    # deletes it too once its last client is gone), and by the next sweep
+    # (or `chi sessions clean`) when both died first.
     attr_accessor :scratch
     # The question this session waits on (PendingQuestion), saved as
     # session.json's "pending_question"; nil with none. A Hash (a saved

data/lib/samagotchi/session_access/contract.rb

@@ -149,14 +149,14 @@ module Samagotchi
 
       # bin/chi's run flags under a remote (chi --remote NAME --attach ID,
       # RemoteAttachCommand): what a remote attach takes, and what runs
-      # this machine's REPL or reads this machine's files (P4-D2..D4). A
+      # this machine's Engine or reads this machine's files (P4-D2..D4). A
       # config registry flag (--recap-base-url …) is this machine's
       # config: LOCAL_ONLY without being listed.
       RUN = {
-        SUPPORTED => %w[--attach --resume -p --prompt --shared --model --thinking --llm-context --llm-context-apply
+        SUPPORTED => %w[--attach --resume -p --prompt --model --thinking --llm-context --llm-context-apply
                         --llm-context-budget --toolkit --tool --no-tool --set --parent-answers --no-interrupt
                         --no-default-input --dir --version -h --help],
-        LOCAL_ONLY => %w[--no-shared --non-interactive -v --verbose --append-system-prompt --memory --mute --profile
+        LOCAL_ONLY => %w[--non-interactive -v --verbose --append-system-prompt --memory --mute --profile
                          --port --open --new-token --tunnel --start-dir --scope --web-markdown --no-web-markdown]
       }.freeze
       # A short run flag's name in a refusal.

data/lib/samagotchi/session_access/local.rb

@@ -23,7 +23,7 @@ require_relative "../launch_mode"
 require_relative "../participants"
 require_relative "../config"
 require_relative "../live_versions"
-require_relative "../web/grants"
+require_relative "../grants"
 require_relative "../web/info_probe"
 require_relative "../web/public_url"
 require_relative "../web/link_codes"
@@ -76,7 +76,7 @@ module Samagotchi
       # @raise [ArgumentError] no such session
       def show(id) = Session.load(id, **dir)
 
-      # @return [OwnerLock::Owner, nil] the worker or chi REPL that owns it
+      # @return [OwnerLock::Owner, nil] the worker or one-turn chi run that owns it
       def owner(id) = SessionManager.session_owner(id, **dir)
 
       # SessionManager.list_sessions: Session objects, for chi sessions list.
@@ -94,11 +94,11 @@ module Samagotchi
       # a margin), so the resume finds the session free.
       # @return [Woken] its sidecar nil when the Bridge didn't come in time
       # @raise [ArgumentError] no such session
-      # @raise [Refused] code scratch: a leftover chi scratch session
-      # @raise [SessionManager::OwnedByTUI] a chi REPL has it
+      # @raise [Refused] code scratch: a chi scratch session (its terminal's alone)
+      # @raise [SessionManager::OwnedByTUI] a one-turn chi run has it
       def wake(id, wait:)
         session = show(id)
-        raise Refused.new(LaunchMode::SCRATCH_LEFTOVER, code: "scratch") if session.scratch
+        raise Refused.new(Session::SCRATCH_REFUSED, code: "scratch") if session.scratch
 
         link = WorkerLink.resolve(session_dir(id), unlink: true)
         case link
@@ -177,7 +177,7 @@ module Samagotchi
       end
 
       # @return [SessionManager::DeliverResult]
-      # @raise [SessionManager::OwnedByTUI] a chi REPL owns it
+      # @raise [SessionManager::OwnedByTUI] a one-turn chi run owns it
       def deliver_turn(id, prompt:, client_id:, images:, delivery: nil)
         SessionManager.deliver_turn(id, prompt: prompt, client_id: client_id, images: images, delivery: delivery, **dir)
       end
@@ -422,7 +422,7 @@ module Samagotchi
         Invitation.new(participant: ParticipantView.from_h(issued.grant.public_h(grants.now)), token: issued.token,
                        link: link, lan: !public_url.nil? || !web.ip.nil?,
                        warning: terms.warning)
-      rescue Web::Grants::Invalid => e
+      rescue Grants::Invalid => e
         raise BadRequest.new(e.message, code: "invalid_participant")
       end
 
@@ -446,13 +446,13 @@ module Samagotchi
         raise BadRequest.new(Participants.no_participant(participant, id), code: "invalid_participant") unless grant
 
         ParticipantView.from_h(grant.public_h(grants.now))
-      rescue Web::Grants::Invalid => e
+      rescue Grants::Invalid => e
         raise BadRequest.new(e.message, code: "invalid_participant")
       end
 
       private
 
-      def grants = @grants ||= Web::Grants.new(Web::Grants.path(state_dir: state_dir!))
+      def grants = @grants ||= Grants.new(Grants.path(state_dir: state_dir!))
 
       LOCAL_PROBE_TIMEOUT = 1.0
 

data/lib/samagotchi/session_access/remote.rb

@@ -12,7 +12,7 @@ require_relative "../bridge_client"
 require_relative "../session_continue"
 require_relative "../guardrails/parent_policy"
 require_relative "../model_profile"
-require_relative "../web/grants"
+require_relative "../grants"
 require_relative "http_transport"
 require_relative "../chi_invocation"
 
@@ -59,7 +59,7 @@ module Samagotchi
       def remote? = true
       def name = @entry.name
 
-      # Web::Grants::PREFIX, without loading chi web.
+      # Grants::PREFIX, without loading chi web.
       PARTICIPANT_PREFIX = "chp_"
 
       # Whether the token is a participant's (chi share's link), not the
@@ -229,7 +229,12 @@ module Samagotchi
           SessionManager::DeliverResult.new(status: :accepted, via: via, ack: ack.except("via"))
         when 504 then SessionManager::DeliverResult.new(status: :timeout, ack: { "detail" => ack["detail"] })
         when 409
-          raise SessionManager::OwnedByTUI, ack["session_id"] || id if ack["error"] == "owned_by_tui"
+          if ack["error"] == "owned_by_tui"
+            # A chi scratch session (scratch: true; an older chi web sends none).
+            raise SessionManager::ScratchSession, ack["session_id"] || id if ack["scratch"] == true
+
+            raise SessionManager::OwnedByTUI, ack["session_id"] || id
+          end
 
           SessionManager::DeliverResult.new(status: :refused, code: 409, ack: ack)
         when 404 then raise_refusal(reply)
@@ -316,7 +321,9 @@ module Samagotchi
 
           NoteDelivery::Result.new(id: id, status: json["status"].to_sym, queued: json["queued"].to_i)
         when 409
-          return NoteDelivery::Result.new(id: id, status: :refused, queued: 0) if json["error"] == "owned_by_tui"
+          if json["error"] == "owned_by_tui"
+            return NoteDelivery::Result.new(id: id, status: :refused, queued: 0, scratch: json["scratch"] == true)
+          end
 
           raise_refusal(reply)
         when 400
@@ -584,7 +591,7 @@ module Samagotchi
       # when none runs, waited for up to +wait+ seconds there (a leaving
       # worker first: +read_timeout+ covers that wait too).
       # @return [WakeReply]
-      # @raise [SessionManager::OwnedByTUI] a chi REPL has it there
+      # @raise [SessionManager::OwnedByTUI] a one-turn chi run has it there
       # @raise [Refused] a leftover scratch session (code scratch), or its
       #   Bridge didn't come in time (code worker_timeout): chi web's words,
       #   LaunchMode's constants
@@ -709,7 +716,10 @@ module Samagotchi
         case error
         when "not_found" then raise ArgumentError, message.to_s
         when "ambiguous_id" then raise Session::AmbiguousId.new(message, ids: Array(json["ids"]))
-        when "owned_by_tui" then raise SessionManager::OwnedByTUI, sid
+        when "owned_by_tui"
+          raise SessionManager::ScratchSession, sid if json["scratch"] == true
+
+          raise SessionManager::OwnedByTUI, sid
         when "worker_running", "still_stopping" then raise SessionManager::DeleteRefused.new(sid, reason)
         when "busy", "scratch"
           raise SessionManager::ArchiveRefused.new(sid, reason, busy_id: json["busy_id"]) if reason
@@ -728,7 +738,7 @@ module Samagotchi
         # A toolkit whose config kit's groups: is invalid there: the same.
         when "toolkit_refused" then raise Toolkit::Refused, message.to_s
         # The grants store doesn't read there: chi share says what it says here.
-        when "grants_unwritable" then raise Web::Grants::Unwritable, message.to_s
+        when "grants_unwritable" then raise Grants::Unwritable, message.to_s
         when /\Ainvalid_/, "missing_fields", "bad_images"
           # invalid_participant: chi share's name, kind or ttl, an archived session
           raise BadRequest.new(message.to_s, code: error)