samagotchi 0.153.0 → 0.154.0

data/lib/samagotchi/objectives_edit.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Objectives
+    # One /objectives edit line against a list, pure: what ObjectivesCommand
+    # applies and what a proposal (Proposal#refusal) is checked with, so the
+    # objectives tool refuses exactly what its card's Apply would. Reads the
+    # Objectives constants at a call, so objectives.rb can load it first.
+    module Edit
+      SEPARATOR = /\n|(?:\A|\s)\|(?:\s|\z)/
+
+      module_function
+
+      # What the frame shows a status as: typed at a text's start it would pass
+      # for one (Item#line).
+      def status_mark = /\A(?:\[(?:#{Objectives::STATUSES.join("|")})\]\s*)+/i
+
+      # The verbs that set a status, and the status each sets.
+      def marks = { "done" => Objectives::DONE, "drop" => Objectives::DROPPED, "undo" => Objectives::ACTIVE }
+
+      # @param verb [String] set, add, edit, done, drop or undo, lower case
+      # @param rest [String] what follows it
+      # @param was [String, nil] what a reword was proposed against (Objectives.fingerprint)
+      # @return [List, String, nil] the new list, what's wrong with the line,
+      #   or nil for a line that isn't one
+      def apply(list, verb, rest, was: nil)
+        case verb
+        when "set", "add"
+          entries = entries_of(rest)
+          return nil if entries.nil? || entries.empty?
+
+          verb == "set" ? list.set(entries) : entries.reduce(list) { |so_far, e| so_far.add(e[:text], done_when: e[:done_when]) }
+        when "edit" then reword(list, rest, was: was)
+        when *marks.keys then mark(list, marks.fetch(verb), rest)
+        end
+      end
+
+      def mark(list, status, rest)
+        ids = rest.upcase.split(/[\s,]+/).reject(&:empty?)
+        return nil if ids.empty?
+
+        missing = ids.reject { |id| list.find(id) }
+        return Objectives.unknown(missing, list) unless missing.empty?
+
+        if status == Objectives::DONE
+          dropped = ids.select { |id| list.find(id).status == Objectives::DROPPED }
+          return Objectives.dropped(dropped) unless dropped.empty?
+        end
+
+        ids.reduce(list) { |so_far, id| so_far.mark(id, status) }
+      end
+
+      # The objective's new text: the whole rest of the line, a | too.
+      def reword(list, rest, was: nil)
+        id, text = rest.strip.split(/\s+/, 2)
+        entry = text && entry_of(text.gsub(/[[:space:]]+/, " ").strip)
+        return nil unless entry
+
+        id = id.upcase
+        item = list.find(id) or return Objectives.unknown(id, list)
+        return "#{id} has changed since this was proposed: #{item.text}" if was && Objectives.fingerprint(item) != was
+
+        list.reword(id, entry[:text], done_when: entry[:done_when])
+      end
+
+      # One {text:, done_when:} per line or |-part, any whitespace collapsed
+      # (Unicode line separators too: the frame is one line per item).
+      # @return [Array<Hash>, nil] nil when a part has no text of its own
+      def entries_of(rest)
+        parts = rest.split(SEPARATOR).map { |part| part.gsub(/[[:space:]]+/, " ").strip }.reject(&:empty?)
+        entries = parts.map { |part| entry_of(part) }
+        entries.all? ? entries : nil
+      end
+
+      # A part's text and done-when, nil when it has no text of its own (only a
+      # done-when, or only status marks). A leading status mark is stripped.
+      def entry_of(part)
+        found = Objectives::DONE_WHEN.match(part)
+        text = (found ? found[1] : part).sub(status_mark, "").strip
+        return nil if text.empty?
+
+        done_when = found && found[2]
+        { text: text, done_when: done_when.to_s.empty? ? nil : done_when }
+      end
+    end
+  end
+end

data/lib/samagotchi/output_formatter.rb

@@ -62,6 +62,11 @@ module Samagotchi
 
     # Qwen3.6 thinking blocks: <think>...</think> (including empty)
     QWEN_THINK_RE = %r{<think>.*?</think>}m
+    # A Qwen thought cut off before it closed (no </think>), when the text
+    # opens with it (after any closed ones): the rest is thought, as with the
+    # Gemma channel. Only #strip_markup drops it; #remove_tokens (a streamed
+    # thought being shown) keeps it. A <think> mentioned mid-answer stays.
+    UNCLOSED_THINK_RE = /\A\s*<think>.*\z/m
     # Qwen tool_call XML blocks that survive when a tool call is rendered as text
     # e.g. <tool_call>\n<function=list_reminders>\n</function>\n</tool_call>
     QWEN_TOOL_CALL_RE = %r{<tool_call>.*?</tool_call>}m
@@ -93,7 +98,8 @@ module Samagotchi
     # a native Gemma step's closed tool-call blocks go with their bodies, as
     # Qwen's do (a step that only calls a tool has no text).
     def strip_markup(text)
-      remove_tokens(text.to_s.gsub(GEMMA_TOOL_CALL_RE, "")).gsub(/\n[ \t]*\n(?:[ \t]*\n)+/, "\n\n").strip
+      text = text.to_s.gsub(GEMMA_TOOL_CALL_RE, "").gsub(QWEN_THINK_RE, "").sub(UNCLOSED_THINK_RE, "")
+      remove_tokens(text).gsub(/\n[ \t]*\n(?:[ \t]*\n)+/, "\n\n").strip
     end
 
     def remove_tokens(text)

data/lib/samagotchi/owner_lock.rb

@@ -16,6 +16,12 @@ module Samagotchi
   # (even in the owner's own process) never releases the owner's lock.
   class OwnerLock
     FILE = "owner.lock"
+    # Who holds a "tui" lock now: a -p --non-interactive one-shot
+    # (TerminalUI), or an older chi's interactive REPL while an update is
+    # under way (N-1). In every refusal's words (SessionManager::OwnedByTUI
+    # and the callers that add what they refused); no parentheses: the
+    # web's continueRefusal reads "<short> (why)" out of a refusal.
+    TUI_BUSY = "in use by a one-turn chi --non-interactive run or an older chi's terminal"
     DEFAULT_WAIT = 2.0
     RETRY_INTERVAL = 0.05
     OWNER_READ_ATTEMPTS = 10
@@ -101,7 +107,7 @@ module Samagotchi
     # Wait for a leaving worker (Owner#leaving?) to release the lock: up to
     # its leave_wait still to run plus LEAVE_MARGIN, looking every
     # RELEASE_POLL seconds. An owner that isn't leaving (a live worker, a
-    # stuck one, a chi REPL) or no owner returns at once. A Ctrl-C (Interrupt)
+    # stuck one, a one-turn chi run) or no owner returns at once. A Ctrl-C (Interrupt)
     # stops the wait as it would any sleep.
     # @param on_wait [#call, nil] called once with the Owner before waiting
     # @return [Symbol] :not_leaving, :released, or :timeout (still held)

data/lib/samagotchi/parent_answers_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "guardrails/parent_policy"
+require_relative "session"
 
 module Samagotchi
   # /parent-answers, the session's own guardrails.parent_answers
@@ -9,13 +10,13 @@ module Samagotchi
   # soft) or `default` (none of its own) sets it, saved at once, for the next
   # answer a parent gives. It may only tighten config.yml's
   # (Guardrails::ParentPolicy.effective). Tightening goes from anyone;
-  # loosening (toward soft, or default) only from a user at a UI: the REPL,
-  # an attached TUI, the web (+user_ui+). A parent agent's line (chi send,
+  # loosening (toward soft, or default) only from a user at a UI: an
+  # attached TUI, the web (+user_ui+). A parent agent's line (chi send,
   # a piped or marked attach, a delegate's follow-up) is refused.
   class ParentAnswersCommand
     NAME = "/parent-answers"
     USAGE = "usage: #{NAME} [hard|standard|soft|default]".freeze
-    REFUSED = "loosening parent_answers is the user's: #{NAME} in chi --attach, the REPL or the web " \
+    REFUSED = "loosening parent_answers is the user's: #{NAME} in a chi terminal or the web " \
               "(not chi send or a parent agent)".freeze
 
     # What +args+ (the text after the name) asks for.
@@ -51,7 +52,7 @@ module Samagotchi
     # @return [Array(String, Boolean, Symbol)] the reply, whether the
     #   session's value changed, and :ok or :error
     def run(args, user_ui:)
-      session = @engine.session or return ["no session yet", false, :error]
+      session = @engine.session or return [Session::NONE_YET, false, :error]
       kind, value = self.class.parse(args)
       return [USAGE, false, :error] if kind == :usage
       return [listing(session), false, :ok] if kind == :show

data/lib/samagotchi/participant_exposure.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # What a participant may learn of their review's usage, by their grant's
+  # exposure level (Grants::Grant#exposure; the review-composer plan's D3):
+  # the policy that maps a level to the usage fields the review route
+  # gives them (Web::ParticipantReview#review_usage). One level today:
+  #
+  # - +own+ (every grant's): their own spend and cap, their own queued
+  #   turns and queue limit, their link's expiry, the session's model.
+  #   Never another participant's or the owner's usage, nor the session's.
+  #
+  # A later level (a tier that also shows the session's spend, say) adds
+  # its row to LEVELS and its fields' sources in Web::ParticipantReview: one
+  # place each. A level this chi doesn't know (written by a newer chi, or
+  # a hand-edited store) reads as DEFAULT, the narrowest: an unknown level
+  # never shows more. See docs/internals/participants.md (Exposure).
+  module ParticipantExposure
+    OWN = "own"
+    DEFAULT = OWN
+    # level => the usage fields it shows, in the order the page reads them.
+    LEVELS = {
+      OWN => %i[spent cap queued queue_limit expires_at model].freeze
+    }.freeze
+
+    # +value+ as a level this chi knows, else DEFAULT.
+    def self.level(value) = LEVELS.key?(value) ? value : DEFAULT
+
+    # @return [Array<Symbol>] the fields +value+'s level shows
+    def self.fields(value) = LEVELS.fetch(level(value))
+
+    # The usage +value+'s level shows, each field read from +sources+
+    # (field => a callable): only the fields shown are computed, and a
+    # field a level names with no source raises (KeyError), never shows
+    # nothing silently.
+    # @param sources [Hash{Symbol => #call}]
+    # @return [Hash{Symbol => Object}]
+    def self.usage(value, sources)
+      fields(value).to_h { |field| [field, sources.fetch(field).call] }
+    end
+  end
+end

data/lib/samagotchi/participant_mode.rb

@@ -38,7 +38,7 @@ module Samagotchi
     end
 
     # The mode a turn of the participant +entry+ (a Participants::Entry or a
-    # Web::Grants::Grant; nil: unknown) runs under in +session+.
+    # Grants::Grant; nil: unknown) runs under in +session+.
     # @return [Symbol]
     def for_turn(session, entry, features: nil)
       return REVIEW unless of(session, features: features) == PAIR

data/lib/samagotchi/participant_name.rb

@@ -5,7 +5,7 @@ module Samagotchi
   # line of at most MAX characters with no brackets (nor Unicode line
   # breaks, nor full-width square brackets), so a name can't close or forge
   # the review-contribution header (Steer.review_header). The grants store
-  # cleans a name at issue (Web::Grants.clean_name); the header cleans it
+  # cleans a name at issue (Grants.clean_name); the header cleans it
   # again, whatever a session file or a sidecar holds.
   module ParticipantName
     MAX = 64

data/lib/samagotchi/participants.rb

@@ -7,12 +7,12 @@ require_relative "atomic_file"
 require_relative "participant_messages"
 require_relative "archive_store"
 require_relative "session"
-require_relative "web/grants"
+require_relative "grants"
 
 module Samagotchi
   # A session's participants: the people (or agents) its owner invited to
   # review it (`chi share`, the owner's participants routes), each through a
-  # Web::Grants grant. Two files in the session dir, neither in the session
+  # Grants grant. Two files in the session dir, neither in the session
   # JSON (chi web never saves that, and a worker would overwrite a field it
   # added):
   # - participants.json, the sidecar: who is or was invited, never a token
@@ -62,7 +62,7 @@ module Samagotchi
       []
     end
 
-    # The sidecar rewritten from +grants+ (that session's Web::Grants::Grant
+    # The sidecar rewritten from +grants+ (that session's Grants::Grant
     # list). Nothing is written for a session without grants, nor for one
     # whose dir is gone.
     def write(session_id, grants, state_dir: Session.default_state_dir)
@@ -79,7 +79,7 @@ module Samagotchi
       AtomicFile.write(File.join(dir, FILE), "#{JSON.pretty_generate({ "participants" => entries })}\n", perm: 0o600)
     end
 
-    # Web::Grants' on_write for a change to +session_ids+ (nil: the sessions
+    # Grants' on_write for a change to +session_ids+ (nil: the sessions
     # of the grants it changed, a revoke's result): their sidecars rewritten
     # from the grants just written, under the store's lock (two writers, chi
     # web and chi share, can't finish out of order and lose a revoke here).
@@ -100,21 +100,21 @@ module Samagotchi
     end
 
     # Invites a participant to +session_id+: the grant (+grants+, a
-    # Web::Grants), the sidecar and the audit line. A grant bound to
+    # Grants), the sidecar and the audit line. A grant bound to
     # +identity+ needs +public_url+ (the chi web's Web::PublicUrl) with an
     # identity header: only a request through that proxy can carry it.
-    # @return [Web::Grants::Issued]
-    # @raise [Web::Grants::Invalid] an archived session, or bad values
+    # @return [Grants::Issued]
+    # @raise [Grants::Invalid] an archived session, or bad values
     #   (Unbindable: an identity without such a public_url)
     # @raise [ArgumentError] no such session
     def invite(grants, session_id:, name:, kind: "human", ttl: nil, cap: nil, identity: nil, public_url: nil,
                mode: nil, state_dir: Session.default_state_dir)
       raise ArgumentError, "Session not found: #{session_id}" unless File.exist?(Session.session_file(session_id, state_dir: state_dir))
 
-      identity = Web::Grants.clean_identity(identity) unless identity.nil?
-      raise Web::Grants::Unbindable if !identity.nil? && public_url&.identity_header.nil?
+      identity = Grants.clean_identity(identity) unless identity.nil?
+      raise Grants::Unbindable if !identity.nil? && public_url&.identity_header.nil?
       if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: state_dir))
-        raise Web::Grants::Invalid, "session #{session_id[0, 8]} is archived: unarchive it to invite anyone"
+        raise Grants::Invalid, "session #{session_id[0, 8]} is archived: unarchive it to invite anyone"
       end
 
       issued = grants.issue(session_id: session_id, name: name, kind: kind, ttl: ttl, cap: cap, identity: identity,
@@ -128,8 +128,8 @@ module Samagotchi
 
     # Sets participant +id+'s cap on +session_id+ (chi share cap): the
     # grant, the sidecar (the worker's check) and the audit line.
-    # @return [Web::Grants::Grant, nil] nil when +id+ isn't an active grant there
-    # @raise [Web::Grants::Invalid] a cap out of range
+    # @return [Grants::Grant, nil] nil when +id+ isn't an active grant there
+    # @raise [Grants::Invalid] a cap out of range
     def set_cap(grants, session_id:, id:, cap:, state_dir: Session.default_state_dir)
       grant = grants.set_cap(id, cap, session_id: session_id, on_write: sidecar_writer(state_dir, [session_id]))
       return nil unless grant
@@ -142,9 +142,9 @@ module Samagotchi
     # +session_id+.
     def no_participant(id, session_id) = "no active participant #{id} in #{session_id.to_s[0, 8]} (chi share ls lists them)"
 
-    # Revokes grants (Web::Grants#revoke's arguments) and brings each
+    # Revokes grants (Grants#revoke's arguments) and brings each
     # affected session's sidecar and audit trail along.
-    # @return [Array<Web::Grants::Grant>] the grants it revoked
+    # @return [Array<Grants::Grant>] the grants it revoked
     def revoke(grants, session_id: nil, id: nil, by: "owner", state_dir: Session.default_state_dir)
       revoked = grants.revoke(session_id: session_id, id: id, by: by, on_write: sidecar_writer(state_dir))
       revoked.group_by(&:session_id).each do |sid, ended|
@@ -156,15 +156,15 @@ module Samagotchi
     # Ends the grants of sessions that were archived or deleted
     # (SessionManager): +by+ "archive" or "delete". Nothing is written for a
     # session nobody was invited to.
-    # A grants store that doesn't read (Web::Grants::Corrupt) doesn't stop
+    # A grants store that doesn't read (Grants::Corrupt) doesn't stop
     # the archive or delete: its links already find no grant, and the
     # store itself says so (Log.warn) until it's fixed. Nor does one a newer
     # chi wrote (Newer): chi web's gate refuses a grant whose session is
     # archived or gone even when it can't write the revoke.
     def end_sessions(session_ids, by:, state_dir: Session.default_state_dir)
-      grants = Web::Grants.new(Web::Grants.path(state_dir: state_dir))
+      grants = Grants.new(Grants.path(state_dir: state_dir))
       session_ids.each { |sid| revoke(grants, session_id: sid, by: by, state_dir: state_dir) }
-    rescue Web::Grants::Unwritable
+    rescue Grants::Unwritable
       nil
     end
   end

data/lib/samagotchi/participants_watch.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  # Loaded only when a sidecar is read: it brings Web::Grants (and Rack).
+  # Loaded only when a sidecar is read: it brings Grants.
   autoload :Participants, File.expand_path("participants", __dir__)
 
   # Who is in a session's review now, and who came or went since the last

data/lib/samagotchi/pending_input_queue.rb

@@ -19,8 +19,8 @@ module Samagotchi
     end
 
     # Append a message to the queue. Nil/empty strings are ignored.
-    # +seq+ is the sender's own order number for it (the REPL numbers every
-    # line it takes during a turn, so its leftovers keep send order across
+    # +seq+ is the sender's own order number for it (a sender that numbers
+    # every line it takes during a turn, so its leftovers keep send order across
     # this queue and its after-turn list: #drain_entries).
     def push(text, seq: nil)
       text = text.to_s

data/lib/samagotchi/plugin/api.rb

@@ -56,7 +56,8 @@ module Samagotchi
         "ctx.context.propose" => "0.140.0", "ctx.context.candidates" => "0.140.0", "ctx.context.withdraw" => "0.140.0",
         "ctx.continues" => "0.141.0", "ctx.context.left_behind" => "0.141.0", "ctx.context.attach(movable:)" => "0.141.0",
         "ctx.session_dir" => "0.143.0", "ctx.session_dir(create:)" => "0.144.0",
-        "ctx.objectives" => "0.149.0", "ctx.turn_running?" => "0.149.0"
+        "ctx.objectives" => "0.149.0", "ctx.turn_running?" => "0.149.0",
+        "ctx.last_answer" => "0.154.0"
       }.freeze
 
       # @param bundle [String]
@@ -234,7 +235,7 @@ module Samagotchi
       # says how to stop it. It starts on first svc.value, or now with
       # eager: true (a raise then fails the plugin's load, unless the
       # plugin rescues it). The Engine stops its services when it shuts
-      # down (the REPL or the session's worker exits), newest first.
+      # down (the session's worker or a one-shot exits), newest first.
       # @param name [String, Symbol] unique in the plugin
       # @return [Service]
       def service(name, eager: false, &block)

data/lib/samagotchi/plugin/context.rb

@@ -18,6 +18,9 @@ module Samagotchi
   autoload :PluginSessionState, File.expand_path("../plugin_session_state", __dir__)
   # Context#objectives reads it; the kit shouldn't carry its files.
   autoload :Objectives, File.expand_path("../objectives", __dir__)
+  # Context#last_answer reads them.
+  autoload :AnswerTail, File.expand_path("../answer_tail", __dir__)
+  autoload :AnswerText, File.expand_path("../answer_text", __dir__)
 
   module Plugin
     # Loaded on first ctx.sessions / ctx.context (or a bundle naming
@@ -50,7 +53,7 @@ module Samagotchi
     # model's memory overlay key (ctx.model, ctx.model_key).
     # +steer+ takes (text, label), +stop_turn+ and +stop_generation+
     # (reason, label), each true when it acted on a running turn.
-    # +frontend+ returns the Engine's interface (:repl, :worker,
+    # +frontend+ returns the Engine's interface (:worker or
     # :non_interactive), which ctx.frontend names for plugins.
     # +toolkit+ returns the session's toolkit name, +declared_tools+ the
     # tool names its next turn declares, +use_toolkit+ takes a name and
@@ -260,12 +263,12 @@ module Samagotchi
       def scratch? = !!@host.scratch&.call
 
       # ctx.frontend's values, by the Engine's interface.
-      FRONTENDS = { repl: :repl, non_interactive: :one_shot, worker: :worker }.freeze
+      FRONTENDS = { non_interactive: :one_shot, worker: :worker }.freeze
 
       # What runs the session, read now (the host sets it after the plugins
-      # load): :repl (the REPL, -p without --non-interactive), :one_shot
-      # (-p --non-interactive: one turn, then exit) or :worker (a session
-      # worker: the web, an attached TUI). A host without one is :worker.
+      # load): :one_shot (-p --non-interactive: one turn, then exit) or
+      # :worker (a session worker: the web, an attached TUI). A host without
+      # one is :worker.
       # @return [Symbol]
       def frontend = FRONTENDS.fetch(@host.frontend&.call, :worker)
 
@@ -316,19 +319,30 @@ module Samagotchi
       # The conversation so far, a frozen copy, without the system prompt.
       # While a turn runs, a session worker's (attached TUI, web) adds the
       # turn so far: its prompt, the model's text and the lines merged into
-      # it; the REPL's is the conversation before that turn
+      # it; a one-shot's is the conversation before that turn
       # (#messages_partial?).
       # @return [Array<Hash>]
       def messages
         Array(@host.messages.call).map { |message| message.dup.freeze }.freeze
       end
 
+      # The newest answer's text as the user saw it (AnswerText.visible): the
+      # newest bubble of #messages, its thoughts (a cut-off one too) and call
+      # markup out. Mid-turn a worker's can be the running turn's interim text.
+      # @return [String, nil] nil when there is none, or it was a thought alone
+      def last_answer
+        found = AnswerTail.find(messages)
+        content = found && (found[:content] || found["content"])
+        text = content.is_a?(String) ? AnswerText.visible(content) : ""
+        text.empty? ? nil : text
+      end
+
       # Whether a turn runs now. Its :after_turn hooks run inside it, so a thread
       # one of them starts can use this to wait for the end: a card shown before
       # then belongs to that turn's block.
       def turn_running? = !!@host.turn_running&.call
 
-      # Whether #messages leaves out a running turn (the REPL mid-turn), so
+      # Whether #messages leaves out a running turn (a one-shot mid-turn), so
       # a plugin can say what its answer is about.
       def messages_partial? = !!@host.messages_partial&.call
 

data/lib/samagotchi/plugin/peer.rb

@@ -6,6 +6,7 @@ require "open3"
 require "tempfile"
 require "time"
 require_relative "../paths"
+require_relative "../session"
 
 module Samagotchi
   module Plugin
@@ -149,7 +150,7 @@ module Samagotchi
       def pair_again(ctx)
         peer = self.class
         previous = ctx.continues or return "not a continue"
-        id = ctx.session_id or return "no session yet"
+        id = ctx.session_id or return Session::NONE_YET
         left = ctx.context.left_behind.find { |row| row.name == peer::INBOX }
         hint = left&.hint.to_s.strip
         return "no #{peer::INBOX} left behind" if hint.empty?

data/lib/samagotchi/plugin/sessions.rb

@@ -110,7 +110,7 @@ module Samagotchi
       # @param delivery [Symbol, String, nil] nil or :next_step (default),
       #   :queue
       # @return [String] the id of the session it went to
-      # @raise [Error] no such session, a REPL owns it, it wasn't taken
+      # @raise [Error] no such session, a one-shot owns it, it wasn't taken
       #   (a worker older than queueing refuses a queue), or delivery is
       #   :cut or unknown
       def send(id, text, delivery: nil)
@@ -128,8 +128,10 @@ module Samagotchi
         when :timeout then raise Error, "session #{sid[0, 8]}'s worker did not answer in time; the message was not sent"
         else raise Error, "the message to session #{sid[0, 8]} could not be written"
         end
+      rescue SessionManager::ScratchSession => e
+        raise Error, "session #{sid[0, 8]}: #{e.message}"
       rescue SessionManager::OwnedByTUI
-        raise Error, "session #{sid[0, 8]} is open in a chi REPL, which takes no messages from others"
+        raise Error, "session #{sid[0, 8]} is #{OwnerLock::TUI_BUSY}, which takes no messages from others"
       end
 
       # The wire value for send's delivery: (nil for the default).
@@ -182,7 +184,7 @@ module Samagotchi
       # its worker to let go.
       # @return [String] the child's id
       # @raise [Error] not a child of this session, no such session, or a
-      #   REPL owns it
+      #   one-shot owns it
       def stop(id)
         state_dir = self.state_dir
         sid = resolve(id, state_dir)
@@ -194,7 +196,7 @@ module Samagotchi
         SessionManager.stop_session(sid, state_dir: state_dir, wait: STOP_WAIT)
         sid
       rescue SessionManager::OwnedByTUI
-        raise Error, "session #{sid[0, 8]} is open in a chi REPL; stop it there"
+        raise Error, "session #{sid[0, 8]} is #{OwnerLock::TUI_BUSY}; let it finish"
       end
 
       private

data/lib/samagotchi/plugin_tasks.rb

@@ -70,8 +70,7 @@ module Samagotchi
     end
 
     # Start the init tasks not started yet, each on its own thread. The
-    # worker calls it once its Bridge is up, the REPL once it renders
-    # events, and every turn (a -p run has only that); later calls start
+    # worker calls it once its Bridge is up, and every turn (a -p run has only that); later calls start
     # nothing new.
     def start!
       @mutex.synchronize do

data/lib/samagotchi/private_files.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # chi web's private state folders (web-grants/, web-push/): a folder
+  # only this user can enter (0700) with files only this user can read
+  # (0600). chi web refuses to start on one others can read (Web::Server.launch);
+  # the reason words say what the folder holds.
+  module PrivateFiles
+    module_function
+
+    # Refuses +dir+ or any of +files+ when others can read it or it isn't
+    # this user's. Only these: the state dir above them is often 0755, and
+    # that is fine. A folder or file not made yet passes (it is made 0700 /
+    # 0600).
+    # @param holds [String] what is in them ("the participants' grants")
+    # @param error [Class] the exception to raise
+    def check!(dir, files, holds:, error:)
+      [dir, *files].each do |target|
+        stat = File.stat(target)
+        next if stat.mode.nobits?(0o077) && stat.uid == Process.uid
+
+        raise error, "#{target} can be read by other users: chmod 700 #{dir} and 600 #{files.join(" ")} " \
+                     "(it holds #{holds})"
+      rescue Errno::ENOENT
+        next
+      end
+    end
+  end
+end

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.