samagotchi 0.103.0 → 0.105.0

data/lib/samagotchi/kernel_loop.rb

@@ -147,6 +147,11 @@ module Samagotchi
     #   write; the Engine's own (it hands it to a kernel it was given).
     attr_accessor :reminder_store
 
+    # @return [Float, nil] the last counted request's chars per token
+    #   (ContextStatus#counted_chars_per_token), for the next turn's first
+    #   estimate (no dip at a turn's start)
+    attr_accessor :counted_chars_per_token
+
     # @return [ModelProfile] the active prompt profile
     attr_reader :profile
 
@@ -309,7 +314,8 @@ module Samagotchi
 
     def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:, reasoning_since: nil)
       conversation = prepare_conversation(messages, keep_thought_from: ReasoningHistory.run_start(messages, reasoning_since))
-      context = ContextStatus.new(conversation: conversation, llm_context: @turn_settings.llm_context)
+      context = ContextStatus.new(conversation: conversation, llm_context: @turn_settings.llm_context,
+                                  counted_chars_per_token: @counted_chars_per_token)
       emit = ->(event) { emit_stream_event(on_stream_event, event) }
       @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context, emit: emit)
       Turn.new(
@@ -609,6 +615,7 @@ module Samagotchi
       response = generation.response.to_s
       turn.context.generation_done(generation.usage, prompt_chars: request.prompt.length, image_tokens: request.image_tokens,
                                                      window: request.window)
+      @counted_chars_per_token = turn.context.counted_chars_per_token || @counted_chars_per_token
       emit(turn, type: :generation_completed, iteration: turn.iteration, content_length: response.length,
                  thinking_chars: thinking_chars(response, generation.streamed_thinking),
                  served_model: generation.served_model, requested_model: turn.model_name,

data/lib/samagotchi/last_turn.rb

@@ -16,9 +16,12 @@ module Samagotchi
   # known. enqueued_id: the input's id when the turn ran one (a POST /turn
   # ack's, an input file's), so a wait for a queued message (`chi send
   # --queue --wait`, ReplyWait's turn:) tells its own turn's end from
-  # another's. A field may be nil (unset; left out of the file).
+  # another's. author: who wrote the turn when it wasn't the owner ("p:<id>",
+  # a participant; origin stays the category), nil for the owner. A field
+  # may be nil (unset; left out of the file).
   LastTurn = Data.define(:outcome, :ended_at, :seconds, :origin, :exhausted, :limit,
-                         :error_kind, :retryable, :kept_steps, :cancel_reason, :stopped_by, :enqueued_id) do
+                         :error_kind, :retryable, :kept_steps, :cancel_reason, :stopped_by, :enqueued_id,
+                         :author) do
     def initialize(**fields)
       super(**members.to_h { |m| [m, nil] }, **fields)
     end

data/lib/samagotchi/launch_mode.rb

@@ -19,6 +19,10 @@ module Samagotchi
     # A worker spawned or resumed for an attach whose Bridge never came (%s:
     # the session id).
     BRIDGE_LATE = "the worker for session %s did not start its Bridge in time"
+    # An attach (or a resume) that found the session's worker leaving, its
+    # Bridge closed and its recap on leave still being written: it waits for
+    # the worker to let go (OwnerLock.await_release), then starts a new one.
+    RECAP_WAIT = "(waiting for the session to finish its recap…)"
 
     module_function
 

data/lib/samagotchi/llm/chat_loop.rb

@@ -63,6 +63,11 @@ module Samagotchi
       # The session every request is for; Engine sets it with the adapter.
       # Goes out as a Session-Id header (OpenAIChat#chat).
       attr_accessor :session_id
+      # The last counted request's chars per token
+      # (ContextStatus#counted_chars_per_token), carried to the next turn's
+      # tracker: its first estimate counts the tool schemas the chars leave
+      # out, so the ctx value doesn't dip at each turn's start.
+      attr_accessor :counted_chars_per_token
 
       # @param kernel [KernelLoop] tool dispatch, thought stripping, hooks
       # @param adapter [OpenAIChat, nil] the host to talk to; Engine sets it
@@ -446,6 +451,7 @@ module Samagotchi
           message[AnswerDisplay::KEY] = entry[AnswerDisplay::KEY] if entry[AnswerDisplay::KEY]
           message[AnswerRefs::KEY] = entry[AnswerRefs::KEY] if entry[AnswerRefs::KEY]
           ContextNote::KEYS.each { |key| message[key] = entry[key] if entry.key?(key) }
+          Steer::AUTHOR_KEYS.each { |key| message[key] = entry[key] if entry[key] }
           message[ToolResponse::LOADED] = entry[ToolResponse::LOADED] if entry[ToolResponse::LOADED].is_a?(Array)
           message[TOOL_CHANGE] = entry[TOOL_CHANGE] if entry[TOOL_CHANGE].is_a?(Hash)
           message
@@ -585,7 +591,8 @@ module Samagotchi
           @recovery_repeated = false
           # The names the last request declared deferred.
           @deferred = []
-          @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context)
+          @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context,
+                                       counted_chars_per_token: loop.counted_chars_per_token)
           loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context,
                                                              emit: method(:emit))
         end
@@ -976,6 +983,7 @@ module Samagotchi
                                                    "completion_tokens" => usage.completion_tokens } })
           @context.generation_done(counts, prompt_chars: @request_chars.to_i, image_tokens: @request_image_tokens.to_i,
                                            window: window)
+          @loop.counted_chars_per_token = @context.counted_chars_per_token || @loop.counted_chars_per_token
         end
 
         # The model's answer at debug level, as the native loop dumps its

data/lib/samagotchi/owner_lock.rb

@@ -19,17 +19,37 @@ module Samagotchi
     DEFAULT_WAIT = 2.0
     RETRY_INTERVAL = 0.05
     OWNER_READ_ATTEMPTS = 10
+    # Seconds .await_release waits past a leaving worker's own budget: its
+    # last save, the task watch's absorb, its exit.
+    LEAVE_MARGIN = 5.0
+    # Seconds between .await_release's looks at the lock.
+    RELEASE_POLL = 0.1
 
     # Who holds the lock, as .owner reads it from the lock file. Its fields
     # may be nil for a moment right after acquisition.
-    # kind: "worker" or "tui"; pid as written (an Integer).
-    Owner = Data.define(:pid, :kind, :started_at) do
-      def initialize(pid: nil, kind: nil, started_at: nil) = super
+    # kind: "worker" or "tui"; pid as written (an Integer). leaving_at (an
+    # ISO 8601 time) and leave_wait (seconds): set once a worker is leaving
+    # (#mark_leaving), its Bridge closed, the lock held for its last work
+    # (the recap on leave) for up to leave_wait.
+    Owner = Data.define(:pid, :kind, :started_at, :leaving_at, :leave_wait) do
+      def initialize(pid: nil, kind: nil, started_at: nil, leaving_at: nil, leave_wait: nil) = super
 
       # The interactive TUI's: it reads no input files and takes no notes.
       def tui? = kind == "tui"
 
       def worker? = kind == "worker"
+
+      # A worker that closed its Bridge and releases the lock once its
+      # last work is done.
+      def leaving? = worker? && !leaving_at.nil?
+
+      # Seconds of its leave_wait still to run at +now+ (0 when past).
+      def leave_left(now = Time.now)
+        started = Time.iso8601(leaving_at.to_s)
+        [leave_wait.to_f - (now - started), 0.0].max
+      rescue ArgumentError
+        leave_wait.to_f
+      end
     end
 
     # Take the lock, retrying for up to +wait+ seconds (another process's
@@ -71,12 +91,35 @@ module Samagotchi
 
           sleep(RETRY_INTERVAL / 5)
         end
-        Owner.new(pid: data["pid"], kind: data["kind"], started_at: data["started_at"])
+        Owner.new(pid: data["pid"], kind: data["kind"], started_at: data["started_at"],
+                  leaving_at: data["leaving_at"], leave_wait: data["leave_wait"])
       end
     rescue Errno::ENOENT
       nil
     end
 
+    # 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)
+    # 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)
+    def self.await_release(session_dir, on_wait: nil, margin: LEAVE_MARGIN, clock: method(:monotonic_now),
+                           sleeper: method(:sleep), now: -> { Time.now })
+      holder = owner(session_dir)
+      return :not_leaving unless holder&.leaving?
+
+      on_wait&.call(holder)
+      deadline = clock.call + holder.leave_left(now.call) + margin
+      loop do
+        return :released unless owner(session_dir)
+        return :timeout if clock.call >= deadline
+
+        sleeper.call(RELEASE_POLL)
+      end
+    end
+
     def self.path(session_dir)
       File.join(session_dir, FILE)
     end
@@ -99,11 +142,28 @@ module Samagotchi
     def initialize(file, kind:)
       @file = file
       @kind = kind.to_s
+      @record = { "pid" => Process.pid, "kind" => @kind, "started_at" => Time.now.iso8601(3) }
+      write_record
+    end
+
+    # The holder is leaving: its Bridge is closed and it releases the lock
+    # within +wait+ seconds (its recap on leave's timeout), which
+    # .await_release reads. .owner retries the moment the file is empty.
+    # @param wait [Numeric]
+    def mark_leaving(wait:)
+      return if @file.closed?
+
+      @record = @record.merge("leaving_at" => Time.now.iso8601(3), "leave_wait" => wait.to_f)
+      write_record
+    end
+
+    def write_record
       @file.truncate(0)
       @file.rewind
-      @file.write(JSON.generate("pid" => Process.pid, "kind" => @kind, "started_at" => Time.now.iso8601(3)))
+      @file.write(JSON.generate(@record))
       @file.flush
     end
+    private :write_record
 
     # Release the lock (process exit releases it too).
     def release

data/lib/samagotchi/participant_name.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A participant's name as chi shows it to anyone, the model included: one
+  # 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
+  # again, whatever a session file or a sidecar holds.
+  module ParticipantName
+    MAX = 64
+    UNSAFE = /[[:cntrl:]\p{Zl}\p{Zp}\[\]［］【】〔〕]/
+
+    module_function
+
+    # @return [String] "" when nothing is left
+    def clean(name)
+      name.to_s.gsub(UNSAFE, " ").squeeze(" ").strip[0, MAX].to_s.strip
+    end
+  end
+end

data/lib/samagotchi/participants.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "atomic_file"
+require_relative "archive_store"
+require_relative "session"
+require_relative "web/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
+  # 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
+  #   or a digest. Written by whoever changes a grant (chi web, chi share);
+  #   the worker reads it (Participants.read; P3's system-prompt line). A
+  #   session nobody was invited to has none, so its files stay as they were.
+  # - participants.jsonl, the audit trail (0600, append-only): grants issued,
+  #   revoked and expired, a participant's first use and each new peer,
+  #   every route refused to them.
+  # Neither is copied to a continue, a fork or a delegate. See
+  # docs/internals/participants.md.
+  module Participants
+    FILE = "participants.json"
+    LOG = "participants.jsonl"
+
+    # One participant as the sidecar has them. +removed_at+ when the grant
+    # was revoked (nil while it works, or once it simply expired:
+    # +expires_at+ says when).
+    Entry = Data.define(:id, :kind, :name, :role, :added_at, :expires_at, :removed_at) do
+      def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key.to_s]] })
+
+      # Still in the review at +now+.
+      def active?(now)
+        removed_at.nil? && Time.iso8601(expires_at.to_s) > now
+      rescue ArgumentError
+        false
+      end
+    end
+
+    module_function
+
+    # @return [Array<Entry>] the session's participants, [] without any
+    def read(session_id, state_dir: Session.default_state_dir)
+      file = File.join(Session.session_dir(session_id, state_dir: state_dir), FILE)
+      return [] unless File.exist?(file)
+
+      data = JSON.parse(File.read(file))
+      Array(data.is_a?(Hash) ? data["participants"] : nil).filter_map { |hash| Entry.from_h(hash) if hash.is_a?(Hash) }
+    rescue JSON::ParserError, SystemCallError
+      []
+    end
+
+    # The sidecar rewritten from +grants+ (that session's Web::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)
+      return if grants.empty?
+
+      dir = Session.session_dir(session_id, state_dir: state_dir)
+      return unless File.directory?(dir)
+
+      entries = grants.map do |grant|
+        { "id" => grant.id, "kind" => grant.kind, "name" => grant.name, "role" => grant.role,
+          "added_at" => grant.created_at, "expires_at" => grant.expires_at, "removed_at" => grant.revoked_at }
+      end
+      AtomicFile.write(File.join(dir, FILE), "#{JSON.pretty_generate({ "participants" => entries })}\n", perm: 0o600)
+    end
+
+    # One audit line: {"at", "event", …fields}. Nothing for a session whose
+    # dir is gone (deleted, pruned).
+    def log(session_id, event, state_dir: Session.default_state_dir, at: Time.now, **fields)
+      dir = Session.session_dir(session_id, state_dir: state_dir)
+      return unless File.directory?(dir)
+
+      line = JSON.generate({ "at" => at.utc.iso8601(3), "event" => event.to_s }.merge(fields.transform_keys(&:to_s)))
+      File.open(File.join(dir, LOG), File::WRONLY | File::APPEND | File::CREAT, 0o600) { |io| io.write("#{line}\n") }
+    end
+
+    # Invites a participant to +session_id+: the grant (+grants+, a
+    # Web::Grants), the sidecar and the audit line.
+    # @return [Web::Grants::Issued]
+    # @raise [Web::Grants::Invalid] an archived session, or bad values
+    # @raise [ArgumentError] no such session
+    def invite(grants, session_id:, name:, kind: "human", ttl: 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))
+      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"
+      end
+
+      issued = grants.issue(session_id: session_id, name: name, kind: kind, **{ ttl: ttl }.compact)
+      write(session_id, grants.list(session_id: session_id), state_dir: state_dir)
+      grant = issued.grant
+      log(session_id, :issued, state_dir: state_dir, participant: grant.id, name: grant.name, kind: grant.kind,
+                               role: grant.role, expires_at: grant.expires_at)
+      issued
+    end
+
+    # Revokes grants (Web::Grants#revoke's arguments) and brings each
+    # affected session's sidecar and audit trail along.
+    # @return [Array<Web::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)
+      revoked.group_by(&:session_id).each do |sid, ended|
+        write(sid, grants.list(session_id: sid), state_dir: state_dir)
+        ended.each { |grant| log(sid, :revoked, state_dir: state_dir, participant: grant.id, by: by) }
+      end
+      revoked
+    end
+
+    # 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.
+    def end_sessions(session_ids, by:, state_dir: Session.default_state_dir)
+      grants = Web::Grants.new(Web::Grants.path(state_dir: state_dir))
+      session_ids.each { |sid| revoke(grants, session_id: sid, by: by, state_dir: state_dir) }
+    end
+  end
+end

data/lib/samagotchi/queued_command.rb

@@ -11,21 +11,25 @@ module Samagotchi
   # :queue, :refuse, :loop), +after_seq+ (the event count then, so a
   # turn's end knows it came before), +after_file+ (the input file it runs
   # after, a basename) and +enqueued_id+ (a file-delivered command's sender).
-  QueuedCommand = Data.define(:command_id, :client_id, :line, :card, :mid_turn, :after_seq, :after_file, :enqueued_id) do
+  # +author+: who sent it when it wasn't the owner ("p:<id>", as a turn's
+  # origin author), nil for the owner.
+  QueuedCommand = Data.define(:command_id, :client_id, :line, :card, :mid_turn, :after_seq, :after_file, :enqueued_id,
+                              :author) do
     def initialize(command_id:, line:, client_id: nil, card: false, mid_turn: nil, after_seq: nil, after_file: nil,
-                   enqueued_id: nil) = super
+                   enqueued_id: nil, author: nil) = super
 
     # A new command with a fresh id.
-    def self.mint(line, client_id: nil, card: false)
-      new(command_id: SecureRandom.uuid, client_id: client_id, line: line, card: card ? true : false)
+    def self.mint(line, client_id: nil, card: false, author: nil)
+      new(command_id: SecureRandom.uuid, client_id: client_id, line: line, card: card ? true : false, author: author)
     end
 
     # The fields its command_queued and command_ran name: card only when
-    # it is a card's.
+    # it is a card's, author only when it isn't the owner's.
     # @return [Hash]
     def event_fields
       fields = { command_id: command_id, client_id: client_id, line: line }
       fields[:card] = true if card
+      fields[:author] = author if author
       fields
     end
 

data/lib/samagotchi/remote_attach_command.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "session_access"
+require_relative "session_access/remote"
+require_relative "launch_mode"
+require_relative "model_profile"
+require_relative "cli/exit"
+require_relative "terminal_ui"
+require_relative "terminal_ui/attach_launcher"
+require_relative "terminal_ui/remote_connector"
+
+module Samagotchi
+  # chi --remote NAME --attach ID | --resume ID | --dir DIR [-p TEXT]: the
+  # 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
+  # (SessionAccess::Contract::RUN). The setup flags go as typed: that
+  # machine checks them against its own config and bundles.
+  class RemoteAttachCommand
+    # @param options [Hash] RunOptions.parse's
+    # @param access [SessionAccess::Remote]
+    def initialize(options, access:, stderr: $stderr, launcher: TerminalUI::AttachLauncher,
+                   connector: TerminalUI::RemoteConnector)
+      @options = options
+      @access = access
+      @stderr = stderr
+      @launcher = launcher
+      @connector = connector
+    end
+
+    # @return [Integer] the exit status: AttachLauncher.exit_status's, 1 a
+    #   launch that failed, 2 a usage error, 130 a Ctrl-C before the TUI
+    #   ran (the wake, a wait for a leaving worker there)
+    def run
+      if (conflict = LaunchMode.attached_conflict(@options))
+        return failed(conflict)
+      end
+
+      existing = @options[:attach] || @options[:resume]
+      return usage(new_needs_dir) if !existing && !absolute_dir?
+
+      @access.require_feature!(SessionAccess::Remote::ATTACH_FEATURE)
+      id = existing ? @access.resolve(existing) : create
+      return id if id.is_a?(Integer)
+
+      ignored(id) if existing
+      launch(id, existing: existing)
+    rescue TerminalUI::AttachLauncher::Error, SessionAccess::RemoteFailed, SessionAccess::Refused,
+           SessionManager::OwnedByTUI, ModelProfile::MissingModel, ArgumentError => e
+      e.is_a?(SessionAccess::BadRequest) ? usage(e.message) : failed(e.message)
+    rescue Interrupt
+      CLI::Exit::INTERRUPTED
+    end
+
+    private
+
+    def launch(id, existing:)
+      model = @options[:model]
+      ended = @launcher.run(attach: (id if @options[:attach]), resume: (id if @options[:resume]), prompt: @options[:prompt],
+                            model: (model if existing), no_interrupt: !!@options[:no_interrupt],
+                            default_input: !@options[:no_default_input],
+                            llm_context: (existing && @options[:llm_context]) || {},
+                            thinking: (@options[:thinking] if existing),
+                            connector: @connector.new(@access, session_id: id))
+      @launcher.exit_status(ended)
+    end
+
+    # A new session there, idle (its -p goes in once attached), as chi send
+    # --new makes one: the create's warnings printed as it prints them.
+    # @return [String, Integer] its id, or the exit status of a refusal
+    def create
+      settings = Array(@options[:sets]).to_h do |pair|
+        key, sep, value = pair.partition("=")
+        return usage("--set takes KEY=VALUE, not #{pair}") if sep.empty? || key.strip.empty?
+
+        [key.strip, value]
+      end
+      llm = @options[:llm_context] || {}
+      words = SessionAccess::SetupWords.new(
+        llm_context: (llm unless llm.empty?), thinking: @options[:thinking]&.to_s, toolkit: @options[:toolkit],
+        tools: Array(@options[:tools]), no_tools: Array(@options[:no_tools]),
+        settings: (settings unless settings.empty?), parent_answers: @options[:parent_answers]
+      )
+      created = @access.create(SessionAccess::NewSession.new(prompt: nil, idle: true, working_directory: @options[:dir],
+                                                             model_name: @options[:model], setup: words,
+                                                             client_id: @connector.client_id))
+      @stderr.puts("chi: warning: #{created.model_warning}") if created.model_warning
+      @stderr.puts("chi: warning: --parent-answers #{created.parent_answers_warning}") if created.parent_answers_warning
+      created.id
+    end
+
+    # An existing session keeps its own setup: the line says which flags
+    # went unused, as chi --attach here says it.
+    def ignored(id)
+      flags = [("--dir" if @options[:dir]), ("--toolkit" if @options[:toolkit]), ("--tool" if @options[:tools]),
+               ("--no-tool" if @options[:no_tools]), ("--set" if @options[:sets]),
+               ("--parent-answers" if @options[:parent_answers])].compact
+      TerminalUI::AttachLauncher.warn_memory_flags_ignored(id, [], [], @stderr, toolkit_flags: flags)
+    end
+
+    def absolute_dir? = @options[:dir].to_s.start_with?("/")
+
+    def new_needs_dir
+      "a new session on #{@access.name} needs --dir, that machine's absolute path (or --attach ID / --resume ID)"
+    end
+
+    def failed(message)
+      @stderr.puts("Error: #{message}")
+      CLI::Exit::FAILED
+    end
+
+    def usage(message)
+      @stderr.puts("Error: #{message}")
+      CLI::Exit::USAGE
+    end
+  end
+end

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 --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token].freeze
+    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].freeze
 
     module_function
 
@@ -107,6 +107,14 @@ module Samagotchi
       [options, cli_overrides]
     end
 
+    # The switches that take a value (--model NAME, -p TEXT), long and
+    # short: a word after one is its value, not a flag.
+    # @return [Array<String>]
+    def value_switches
+      parser_switches(build_parser({}, {})).select { |switch| switch.is_a?(OptionParser::Switch::RequiredArgument) }
+                                           .flat_map { |switch| switch.long + switch.short }.push("--no-tool").uniq
+    end
+
     # Every switch the parser takes, long and short, a --[no-]x as --x and
     # --no-x (--no-tool too, read before the parse), for what classifies the
     # run flags.
@@ -138,12 +146,14 @@ module Samagotchi
                  chi context <add|push|ls|show|refresh|rm|mute|unmute>   live external text attached to sessions
                  chi send [-m TEXT] ID...|--new   a message into sessions, as if typed there
                  chi answer ID --question QID --option N   answer a question a session waits on
+                 chi share ID --name NAME | ls [ID] | revoke ID [P]|--all   participants who review a session
                  chi memory <ls|rm> [--scope project|system]   the memories; rm moves one to the bundle trash
                  chi bundle <install|upgrade|uninstall|status|diff|list|build|trash|new|test|check|try>
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME
-                 chi --remote NAME <send|answer|note|context|sessions> …   those commands on that machine (or CHI_REMOTE=NAME)
+                 chi --remote NAME <send|answer|note|context|sessions|share> …   those commands on that machine (or CHI_REMOTE=NAME)
+                 chi --remote NAME --attach ID | --resume ID | --dir DIR [-p TEXT]   a session on that machine, in this terminal
                  chi self                         version, paths, model and bundles
                  chi update [--dry-run]           update this chi, its bundles and the desktop helper
           (each subcommand takes --help)
@@ -152,6 +162,8 @@ module Samagotchi
         opts.on("-p", "--prompt PROMPT", "Run PROMPT as the first turn, then stay in the REPL") { |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,

data/lib/samagotchi/send_command.rb

@@ -646,7 +646,7 @@ module Samagotchi
       # its preview; the user can attach and send it again.
       unless result
         attach = @access.invocation.attach(session.id)
-        @info.puts("#{session.id}  failed: its worker did not start; the session is kept#{" (#{attach})" if attach}")
+        @info.puts("#{session.id}  failed: its worker did not start; the session is kept (#{attach})")
         return false
       end
       unless result.accepted?

data/lib/samagotchi/session.rb

@@ -395,10 +395,12 @@ module Samagotchi
     # @param messages [Array<Hash>] a conversation to start from (a fork's
     #   seed); [] by default
     # @param setup [SessionSetup] the session's own settings (none by default)
+    # @param now [Time] its created_at and updated_at (a spec's clock)
     def self.new_session(mode:, model_name:, working_directory:, test_run: nil,
                          preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, messages: [],
-                         scratch: false, model_typed: nil, delegate: false, setup: SessionSetup.new, continues: nil)
-      now = Time.now.iso8601(3)
+                         scratch: false, model_typed: nil, delegate: false, setup: SessionSetup.new, continues: nil,
+                         now: Time.now)
+      now = now.iso8601(3)
       resolved_test = if test_run.nil?
                         test_session_env?
                       else
@@ -614,9 +616,11 @@ module Samagotchi
     # Never call it from a trap handler (Mutex#lock raises ThreadError
     # there; WorkerSignals saves on a thread of its own) or from inside a
     # save (the lock isn't re-entrant).
-    def save(state_dir: self.class.default_state_dir)
+    # @param now [Time, nil] the updated_at to stamp (a spec's clock); nil,
+    #   the time the lock is taken
+    def save(state_dir: self.class.default_state_dir, now: nil)
       @save_lock.synchronize do
-        @updated_at = Time.now.iso8601(3)
+        @updated_at = (now || Time.now).iso8601(3)
         # Persist with current metadata version so new flag is written
         @metadata_version = METADATA_VERSION
         FileUtils.mkdir_p(state_dir)