samagotchi 0.103.0 → 0.104.0

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)

data/lib/samagotchi/session_access/contract.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../config"
+
 module Samagotchi
   module SessionAccess
     # Which session commands and flags run against another machine's
@@ -7,13 +9,16 @@ module Samagotchi
     # and which run on this machine only (refused under a remote, exit 2:
     # "chi <cmd> runs on this machine only: run it on <remote>"). The v1 scope is the remote-sessions plan's
     # D3: send, answer, note, a session's context (add, push, ls, show, rm)
-    # and sessions list/stop/restart/archive/unarchive/delete; the rest
+    # and sessions list/stop/restart/archive/unarchive/delete, and chi share
+    # (the shared-sessions plan's P2); the rest
     # stays local. bin/chi's subcommands that act on the machine, not on
-    # sessions, are MACHINE. The run flags (--attach, -p, --resume) are not
-    # subcommands and not in this table (remote attach is its own phase).
+    # sessions, are MACHINE. The run flags (chi --attach, -p, --resume: a
+    # session in this terminal, a remote attach there) are RUN's.
     #
     # spec/session_access_contract_spec.rb fails when a subcommand, one of
-    # its subcommands or one of a supported one's flags is in neither.
+    # its subcommands or one of a supported one's flags is in neither, or
+    # a run flag (RunOptions.switches) is in neither RUN list and isn't a
+    # config registry flag.
     module Contract
       SUPPORTED = :supported
       LOCAL_ONLY = :local_only
@@ -111,11 +116,44 @@ module Samagotchi
         "sessions clean" => LOCAL_ONLY,
         "sessions stats" => LOCAL_ONLY,
 
+        # Participants (docs/internals/participants.md): the remote's link,
+        # through its chi web's participants routes.
+        "share" => SUPPORTED,
+        "share --name" => SUPPORTED,
+        "share --agent" => SUPPORTED,
+        "share --expires" => SUPPORTED,
+        "share ls" => SUPPORTED,
+        "share ls --format" => SUPPORTED,
+        "share revoke" => SUPPORTED,
+        "share revoke --all" => SUPPORTED,
+
         "broadcast" => LOCAL_ONLY
       }.freeze
 
+      # 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
+      # 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
+                        --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
+                         --port --open --new-token --scope --web-markdown --no-web-markdown]
+      }.freeze
+      # A short run flag's name in a refusal.
+      RUN_WORDS = { "-v" => "--verbose" }.freeze
+
       module_function
 
+      # @param flag [String] a run flag as RunOptions.switches lists it
+      # @return [Symbol, nil] SUPPORTED or LOCAL_ONLY; nil: not a run flag
+      def run_status(flag)
+        RUN.each { |status, flags| return status if flags.include?(flag) }
+        LOCAL_ONLY if Config.cli_entries.any? { |entry| [entry.cli_flag, entry.cli_flag.sub("--", "--no-")].include?(flag) }
+      end
+
       # @param words [Array<String>] a command, maybe its subcommand, maybe
       #   a flag's long name: status("context", "add", "--cmd")
       # @return [Symbol, nil] SUPPORTED, LOCAL_ONLY, or nil when not listed

data/lib/samagotchi/session_access/dispatch.rb

@@ -21,10 +21,8 @@ module Samagotchi
       # bin/chi's own words besides its SUBCOMMANDS (a refusal names them).
       OWN_WORDS = %w[web scratch self].freeze
       HELP = %w[--version -h --help].freeze
-      # The run flags (not subcommands) a refusal names: remote attach is
-      # its own phase (P4).
-      RUN_FLAGS = { "--attach" => "--attach", "--resume" => "--resume", "-p" => "-p", "--prompt" => "-p",
-                    "--shared" => "--shared", "--no-shared" => "--no-shared" }.freeze
+      # --non-interactive's refusal: what runs one turn there instead.
+      ONE_TURN = "(%s send --new --dir D -m TEXT --wait runs one turn there)"
 
       # A usage error in the flag itself (--remote with no name, a bad one).
       class Usage < StandardError; end
@@ -54,6 +52,14 @@ module Samagotchi
 
       def remote? = !@remote.nil?
 
+      # Whether the arguments are run flags, no subcommand: a session in
+      # this terminal (bin/chi's RunOptions parse them; under a remote,
+      # RemoteAttachCommand runs them).
+      def run_flags?
+        command = @argv.first
+        command.nil? || command.start_with?("-")
+      end
+
       # Whether the arguments run here as they would without a remote: chi
       # remote, --version, --help.
       def here?
@@ -67,7 +73,8 @@ module Samagotchi
       def refusal
         words = local_words or return nil
 
-        "chi #{words} runs on this machine only: run it on #{@remote}"
+        line = "chi #{words} runs on this machine only: run it on #{@remote}"
+        words == "--non-interactive" ? "#{line} #{format(ONE_TURN, "chi --remote #{@remote}")}" : line
       end
 
       # The session command against the remote: refused (exit 2), or run
@@ -101,11 +108,11 @@ module Samagotchi
       private
 
       # The words that run here only: the command (and its subcommand, a
-      # flag) the Contract lists local_only, a machine command, or the run
-      # flags (a session in this terminal, attach). nil: supported.
+      # flag) the Contract lists local_only, a machine command, or a run
+      # flag Contract::RUN lists local_only. nil: supported.
       def local_words
         command = @argv.first
-        return run_words if command.nil? || command.start_with?("-")
+        return run_words if run_flags?
         return command if Contract::MACHINE.include?(command) || Contract.status(command).nil?
         return command if Contract.status(command) == Contract::LOCAL_ONLY
 
@@ -124,9 +131,21 @@ module Samagotchi
         @argv.drop(1).take_while { |arg| arg != "--" }.select { |arg| arg.start_with?("--") }.map { |arg| arg.split("=", 2).first }
       end
 
+      # The first local-only run flag, a value (-p TEXT, --model NAME)
+      # never read as one. An unknown flag is the parser's to refuse.
       def run_words
-        flag = @argv.take_while { |arg| arg != "--" }.map { |arg| arg.split("=", 2).first }.find { |arg| RUN_FLAGS.key?(arg) }
-        flag ? RUN_FLAGS[flag] : "(a session in this terminal)"
+        require_relative "../run_options"
+        values = RunOptions.value_switches
+        words = @argv.take_while { |arg| arg != "--" }
+        index = 0
+        while index < words.size
+          arg = words[index]
+          flag = arg.start_with?("--") ? arg.split("=", 2).first : arg[0, 2]
+          return Contract::RUN_WORDS.fetch(flag, flag) if arg.start_with?("-") && Contract.run_status(flag) == Contract::LOCAL_ONLY
+
+          index += values.include?(arg) ? 2 : 1
+        end
+        nil
       end
     end
   end

data/lib/samagotchi/session_access/local.rb

@@ -4,6 +4,7 @@ require_relative "../session"
 require_relative "../session_access"
 require_relative "../reply_wait"
 require_relative "../bridge_client"
+require_relative "../owner_lock"
 require_relative "../parent_report"
 require_relative "../note_delivery"
 require_relative "../image_store"
@@ -12,6 +13,10 @@ require_relative "../send_command/busy"
 require_relative "../chi_invocation"
 require_relative "../worker_sidecar"
 require_relative "../launch_mode"
+require_relative "../participants"
+require_relative "../config"
+require_relative "../web/grants"
+require_relative "../web/info_probe"
 
 module Samagotchi
   # Loaded on first use: SessionManager and its ~80 files only when a
@@ -69,7 +74,10 @@ module Samagotchi
 
       # The session's worker for an attach: the live one as is, else
       # resumed and waited for up to +wait+ seconds (chi --attach on this
-      # machine; chi web's POST …/wake for a remote one).
+      # machine; chi web's POST …/wake for a remote one). A worker still
+      # leaving (its Bridge closed, its recap on leave being written) is
+      # waited for first (OwnerLock.await_release: its recap's timeout and
+      # 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
@@ -81,6 +89,7 @@ module Samagotchi
         live = WorkerSidecar.live(session_dir(id), unlink: true)
         return Woken.new(woke: false, sidecar: live) if live
 
+        OwnerLock.await_release(session_dir(id))
         SessionManager.resume_session(id, **dir)
         found = BridgeClient.wait_for(id, session_dir: session_dir(id), timeout: wait)
         Woken.new(woke: true, sidecar: found && WorkerSidecar.read(session_dir(id)))
@@ -322,8 +331,50 @@ module Samagotchi
         end
       end
 
+      # --- participants (chi share)
+
+      # Remote's: through this machine's grants store, as chi web would.
+      # @return [Array<ParticipantView>]
+      def participants(id = nil)
+        grants.list(session_id: id).map { |grant| ParticipantView.from_h(grant.public_h(grants.now)) }
+      end
+
+      # The link names this machine's chi web: its LAN address when one
+      # runs on the LAN (web.port), else 127.0.0.1 (+lan+ false).
+      # @return [Invitation]
+      # @raise [ArgumentError] no such session
+      # @raise [BadRequest] a bad name, kind or ttl, an archived session
+      def invite(id, name:, kind:, ttl: nil)
+        issued = Participants.invite(grants, session_id: id, name: name, kind: kind, ttl: ttl, state_dir: state_dir!)
+        ip, port = local_web
+        Invitation.new(participant: ParticipantView.from_h(issued.grant.public_h(grants.now)), token: issued.token,
+                       link: "http://#{ip || "127.0.0.1"}:#{port}/?token=#{issued.token}#s=#{id}", lan: !ip.nil?)
+      rescue Web::Grants::Invalid => e
+        raise BadRequest.new(e.message, code: "invalid_participant")
+      end
+
+      # @return [Array<ParticipantView>] the ones it revoked
+      def revoke_participants(id = nil, participant: nil)
+        Participants.revoke(grants, session_id: id, id: participant, state_dir: state_dir!)
+                    .map { |grant| ParticipantView.from_h(grant.public_h(grants.now)) }
+      end
+
       private
 
+      def grants = @grants ||= Web::Grants.new(Web::Grants.path(state_dir: state_dir!))
+
+      # Web::Server::DEFAULT_PORT, without loading chi web.
+      WEB_PORT = 4567
+      LOCAL_PROBE_TIMEOUT = 1.0
+
+      # [LAN ip or nil, port] of this machine's chi web (GET /api/info).
+      def local_web
+        port = Config.get("web.port").to_s.to_i
+        port = WEB_PORT unless port.positive?
+        info = Web::InfoProbe.call("127.0.0.1", port, timeout: LOCAL_PROBE_TIMEOUT)
+        [info.is_a?(Hash) ? info["lan"] : nil, port]
+      end
+
       def dir = @state_dir ? { state_dir: @state_dir } : {}
       def state_dir! = @state_dir || Session.default_state_dir
       def session_dir(id) = Session.session_dir(id, state_dir: state_dir!)

data/lib/samagotchi/session_access/remote.rb

@@ -74,8 +74,8 @@ module Samagotchi
       # add checks the same).
       # @return [RemoteFailed, nil]
       def self.info_problem(entry, reply)
-        failure = auth_failure(entry, reply)
-        return RemoteFailed.new(failure) if failure
+        refused = access_error(entry, reply)
+        return refused if refused
         unless reply.status == 200 && reply.json.is_a?(Hash) && reply.json["app"] == "chi-web"
           return RemoteFailed.new("#{entry.label}: not chi web (GET /api/info answered #{reply.status})")
         end
@@ -91,20 +91,31 @@ module Samagotchi
           "update chi there (chi update)"
       end
 
-      # The words for a 401 or a 403 forbidden from +entry+'s chi web, nil
-      # for any other answer (chi remote add says the same).
-      def self.auth_failure(entry, reply)
+      # The errors any route of +entry+'s chi web can answer, each its one
+      # message: the token refused (401 unauthorized) or ended (401
+      # token_revoked / token_expired), the LAN IP only (403 forbidden), a
+      # participant's token on an owner's route (403 not_permitted) or over
+      # its limits (429 too_many_turns / cap_reached). nil for any other
+      # answer (chi remote add says the same).
+      # @return [RemoteFailed, nil]
+      def self.access_error(entry, reply)
+        error = reply.error
+        known = ACCESS_ERRORS.find { |klass| error == klass::CODE }
+        return known.new(entry.label) if known
+
         case reply.status
-        when 401 then "#{entry.label}: the token was refused (chi web's LAN link carries the current one: " \
-                      "chi remote add #{entry.name} #{entry.url} --token-file FILE)"
+        when 401 then AuthRefused.new("#{entry.label}: the token was refused (chi web's LAN link carries the current one: " \
+                                      "chi remote add #{entry.name} #{entry.url} --token-file FILE)")
         when 403
-          return nil unless reply.error == "forbidden"
+          return nil unless error == "forbidden"
 
           ip = reply.json["detail"].to_s[/ and (\S+) are answered/, 1]
-          "#{entry.label}: chi web answers its LAN IP only: use the LAN IP#{" #{ip}" if ip}, not a hostname"
+          AuthRefused.new("#{entry.label}: chi web answers its LAN IP only: use the LAN IP#{" #{ip}" if ip}, not a hostname")
         end
       end
 
+      ACCESS_ERRORS = [TokenRevoked, TokenExpired, NotPermitted, TooManyTurns, CapReached].freeze
+
       # --- ids and sessions
 
       # @raise [Session::AmbiguousId]
@@ -220,6 +231,40 @@ module Samagotchi
 
       # @return [NoteDelivery::Result]
       # @raise [SessionInbox::NoteRejected]
+      # --- participants (chi share)
+
+      # @param id [String, nil] one session's, or every session's
+      # @return [Array<ParticipantView>]
+      def participants(id = nil)
+        reply = request(:get, id ? "#{session_path(id)}/participants" : "/api/participants")
+        raise_refusal(reply) unless reply.status == 200
+
+        Array(reply.json["participants"]).map { |row| ParticipantView.from_h(row) }
+      end
+
+      # @param ttl [Integer, nil] seconds; nil: the grant's default
+      # @return [Invitation]
+      # @raise [BadRequest] a bad name, kind or ttl, an archived session
+      def invite(id, name:, kind:, ttl: nil)
+        reply = request(:post, "#{session_path(id)}/participants", body: { name: name, kind: kind, ttl: ttl }.compact)
+        raise_refusal(reply) unless reply.status == 201
+
+        json = reply.json
+        Invitation.new(participant: ParticipantView.from_h(json.fetch("participant")), token: json.fetch("token"),
+                       link: json.fetch("link"), lan: json["lan"] == true)
+      end
+
+      # Revokes one participant (+participant+), a session's, or with no
+      # +id+ every session's.
+      # @return [Array<ParticipantView>] the ones it revoked
+      def revoke_participants(id = nil, participant: nil)
+        reply = request(:delete, id ? "#{session_path(id)}/participants" : "/api/participants",
+                        query: { id: participant }.compact)
+        raise_refusal(reply) unless reply.status == 200
+
+        Array(reply.json["revoked"]).map { |row| ParticipantView.from_h(row) }
+      end
+
       def note(id, text:, source:)
         reply = request(:post, "#{session_path(id)}/notes", body: { text: text, source: source })
         json = reply.json.is_a?(Hash) ? reply.json : {}
@@ -317,13 +362,13 @@ module Samagotchi
 
       # --- sessions
 
-      # chi web stops it and waits its own bounded time (Web::App::
-      # STOP_WAIT_SECONDS, not +wait+).
+      # chi web stops it and waits up to +wait+ seconds (capped there at
+      # SessionManager::STOP_WAIT; a chi web before the field waits its
+      # Web::App::STOP_WAIT_SECONDS).
       # @return [Boolean] whether the worker had released it by then, as
       #   chi web's released says (absent: true)
       def stop(id, wait:)
-        _ = wait
-        reply = request(:post, "#{session_path(id)}/stop")
+        reply = request(:post, "#{session_path(id)}/stop", body: { wait: wait })
         raise_refusal(reply) unless reply.status == 200
 
         reply.json["released"] != false
@@ -454,6 +499,50 @@ module Samagotchi
         WebBridgeClient.new(remote: self, session_id: id, worker_key: worker["epoch"] || worker["started_at"])
       end
 
+      # This chi web has +feature+ (GET /api/info's), else RemoteTooOld in
+      # Remote.too_old_message's words.
+      # @raise [RemoteFailed]
+      def require_feature!(feature)
+        check_server!
+        raise RemoteTooOld, too_old(@version) unless Array(@features).include?(feature)
+      end
+
+      # POST …/wake: the session's live worker for a remote attach, started
+      # 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 [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
+      # @raise [ArgumentError] no such session
+      def attach_wake(id, wait:, read_timeout: nil)
+        reply = request(:post, "#{session_path(id)}/wake", body: { wait: wait }, read_timeout: read_timeout)
+        if reply.status != 200 && %w[scratch worker_timeout].include?(reply.error)
+          raise Refused.new((reply.json["message"] || reply.json["detail"]).to_s, code: reply.error)
+        end
+
+        raise_refusal(reply) unless reply.status == 200
+
+        json = reply.json
+        WakeReply.new(woke: json["woke"] == true, worker: json["worker"], default_model: json["default_model"],
+                      strategy: strategy_or_hard(json["parent_strategy"]), installed: json["installed"])
+      end
+
+      # GET …/worker: the session's worker now (never started).
+      # @return [WorkerReply]
+      # @raise [ArgumentError] no such session
+      def attach_worker(id)
+        reply = request(:get, "#{session_path(id)}/worker")
+        raise_refusal(reply) unless reply.status == 200
+
+        json = reply.json
+        seconds = json["leave_seconds"]
+        WorkerReply.new(live: json["live"] == true, stopped: json["stopped"] == true, worker: json["worker"],
+                        strategy: strategy_or_hard(json["parent_strategy"]), default_model: json["default_model"],
+                        leaving: json["leaving"] == true, leave_seconds: (seconds.to_f if seconds.is_a?(Numeric)))
+      end
+
       # One request to a route, as the session commands make them (the
       # server check first; a refused token or a missing route raise
       # RemoteFailed): WebBridgeClient's, which maps the reply itself.
@@ -476,7 +565,8 @@ module Samagotchi
       def request(method, path, **)
         check_server!
         reply = @transport.call(method, path, **)
-        raise RemoteFailed, Remote.auth_failure(@entry, reply) if Remote.auth_failure(@entry, reply)
+        refused = Remote.access_error(@entry, reply)
+        raise refused if refused
         raise RemoteTooOld, too_old(@version) if missing_route?(reply)
 
         reply
@@ -486,7 +576,10 @@ module Samagotchi
         return if @checked
 
         reply = @transport.call(:get, "/api/info")
-        @version = reply.json["version"] if reply.json.is_a?(Hash)
+        if reply.json.is_a?(Hash)
+          @version = reply.json["version"]
+          @features = Array(reply.json["features"])
+        end
         problem = Remote.info_problem(@entry, reply)
         raise problem if problem
 
@@ -495,6 +588,8 @@ module Samagotchi
 
       def too_old(version) = Remote.too_old_message(@entry, version)
 
+      def strategy_or_hard(json) = strategy_of(json) || Guardrails::ParentPolicy.strategy(Guardrails::ParentPolicy::HARD)
+
       # chi web's 404 for a path no route takes (#serve_static's), not a
       # route's own "no such session".
       def missing_route?(reply)
@@ -527,6 +622,7 @@ module Samagotchi
         # spawn_session raises here (chi send: could not start a session).
         when "invalid_model" then raise ModelProfile::MissingModel, 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)
         end
         raise RemoteFailed, "#{@entry.label} answered #{reply.status}#{" #{error}" unless error.empty?}" \
@@ -535,7 +631,7 @@ module Samagotchi
 
       def create_body(spec)
         body = { model: spec.model_name, client_id: spec.client_id, history: false }
-        if spec.preview
+        if spec.preview || spec.idle
           body.merge!(idle: true, preview: spec.preview)
         else
           body[:prompt] = spec.prompt