samagotchi 0.103.0 → 0.104.0

data/lib/samagotchi/session_access/web_bridge_client.rb

@@ -36,6 +36,9 @@ module Samagotchi
       # No byte for this long on the stream (the Bridge pings every 15 s): a
       # half-open connection (Wi-Fi gone, the laptop asleep), reconnected.
       STREAM_IDLE_TIMEOUT = 40.0
+      # A read a join waits on (a turn's saved records, the children
+      # counts): a slow chi web can't hold the join up for long (L9).
+      JOIN_READ_TIMEOUT = 5
       # chi web answers no live worker for the session (Mapping).
       NO_WORKER = "no live worker for session %s on %s"
 
@@ -44,7 +47,7 @@ module Samagotchi
         module_function
 
         # @param route [Symbol] :turn, :command, :answer, :dismiss,
-        #   :dequeue, :cancel
+        #   :dequeue, :cancel, :exit, :recap, :stats, :children, :records
         # @param reply [HTTPTransport::Reply]
         # @param session_id [String]
         # @param remote [String] the remote's name
@@ -133,6 +136,51 @@ module Samagotchi
         post(:cancel, "cancel", { reason: reason })
       end
 
+      # POST …/exit: the worker asked to exit (chi web passes client_id on
+      # only when it is an attached TUI's).
+      # @return [BridgeClient::Response] 200 {status: exiting, discard}, 409
+      #   held {reason, tasks}, 408 late, 404 an older worker's
+      def request_exit(client_id:, delete: false)
+        body = { client_id: client_id }
+        body[:delete] = true if delete
+        post(:exit, "exit", body)
+      end
+
+      # POST …/recap: the saved recap, and a new one asked for.
+      # @return [BridgeClient::Response] 200 {enabled, saved, request, min_user_turns, session_off}
+      def request_recap = post(:recap, "recap", {})
+
+      # GET …/stats: the worker's metrics (its state's, for an older
+      # worker), nil when it didn't give them.
+      # @return [Hash, nil]
+      # @raise [Unreachable]
+      def stats
+        response = get(:stats, "stats", read_timeout: READ_TIMEOUT)
+        response.status == 200 ? response.json&.dig("metrics") : nil
+      end
+
+      # GET …/children/counts: the session's delegates' counts there.
+      # @return [Hash] {running, waiting, unreported}
+      # @raise [Unreachable] chi web couldn't answer (or the session is gone)
+      def children_counts
+        response = get(:children, "children/counts", read_timeout: JOIN_READ_TIMEOUT)
+        raise Unreachable, "children counts: chi web answered #{response.status}" unless response.status == 200
+
+        response.json
+      end
+
+      # GET …/turns/:turn_id/records: a turn's saved tool records and turn
+      # record there.
+      # @return [Hash] {tool_records: [...], turn_record: {...} | nil}
+      # @raise [Unreachable]
+      def turn_records(turn_id)
+        response = get(:records, "turns/#{URI.encode_www_form_component(turn_id.to_s)}/records",
+                       read_timeout: JOIN_READ_TIMEOUT)
+        raise Unreachable, "turn records: chi web answered #{response.status}" unless response.status == 200
+
+        response.json
+      end
+
       # Follow the session's events through chi web (see EventStream): with
       # epoch_watch, announce_retries and STREAM_IDLE_TIMEOUT.
       # @return [BridgeClient::EventStream] started
@@ -172,6 +220,13 @@ module Samagotchi
         raise Unreachable, e.message
       end
 
+      def get(route, path, read_timeout:)
+        reply = @remote.route_request(:get, "/api/sessions/#{@session_id}/#{path}", read_timeout: read_timeout)
+        Mapping.response(route, reply, session_id: @session_id, remote: @remote.name)
+      rescue RemoteFailed => e
+        raise Unreachable, e.message
+      end
+
       def refused(reason)
         Log.warn(:attached, "stream_refused", reason: reason, remote: @remote.name)
         nil

data/lib/samagotchi/session_access.rb

@@ -28,6 +28,47 @@ module Samagotchi
     # --remote: update chi there (chi update)").
     class RemoteTooOld < RemoteFailed; end
 
+    # A remote's chi web refused this machine's token (401), or answers its
+    # LAN IP only (403 forbidden): Remote.access_error's words.
+    class AuthRefused < RemoteFailed; end
+
+    # The errors a participant's token meets (docs/internals/participants.md),
+    # one message each, built from the remote's label ("remote studio
+    # (http://…)"). chi web's code for each is its CODE.
+
+    # 401 token_revoked: the owner revoked the grant, or archived or
+    # deleted its session.
+    class TokenRevoked < AuthRefused
+      CODE = "token_revoked"
+      def initialize(label) = super("#{label}: this review link was revoked by the session's owner")
+    end
+
+    # 401 token_expired: the grant's time ran out.
+    class TokenExpired < AuthRefused
+      CODE = "token_expired"
+      def initialize(label) = super("#{label}: this review link expired: ask the session's owner for a new one")
+    end
+
+    # 403 not_permitted: a participant's token on a route only the session's
+    # owner may use.
+    class NotPermitted < RemoteFailed
+      CODE = "not_permitted"
+      def initialize(label) = super("#{label}: this token is a participant's: only the session's owner can do that")
+    end
+
+    # 429 too_many_turns (P3b): the participant's turns already wait in the
+    # queue up to their limit.
+    class TooManyTurns < RemoteFailed
+      CODE = "too_many_turns"
+      def initialize(label) = super("#{label}: this participant has too many turns waiting: wait for one to finish")
+    end
+
+    # 429 cap_reached (P3b): the participant's grant spent its cap.
+    class CapReached < RemoteFailed
+      CODE = "cap_reached"
+      def initialize(label) = super("#{label}: this participant's spending cap is reached: ask the session's owner to raise it")
+    end
+
     # A remote's chi web refused a request for a reason this machine checks
     # itself before sending (a parent's /continue yes, a loosening
     # /parent-answers, images to a model that can't see them): +message+
@@ -47,11 +88,30 @@ module Samagotchi
     # exits 2 with its message.
     class BadRequest < Refused; end
 
+    # One participant's grant as chi share ls shows it
+    # (Web::Grants::Grant#public_h): never its token or digest. +state+
+    # "active", "revoked" or "expired".
+    ParticipantView = Data.define(:id, :session_id, :kind, :name, :role, :created_at, :expires_at, :revoked_at,
+                                  :revoked_by, :last_used_at, :state) do
+      def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key] || hash[key.to_s]] })
+    end
+
+    # What chi share made: the participant, their token and the link that
+    # carries it (both shown this once: chi keeps only a digest), and
+    # whether that chi web listens on the LAN (+lan+ false: the link works
+    # on that machine only).
+    Invitation = Data.define(:participant, :token, :link, :lan) do
+      def inspect = "#<Invitation #{participant.id}>"
+      alias_method :to_s, :inspect
+    end
+
     # A session to create (chi send --new): a new one, or with +continues+
     # the next link of that session's chain (which brings its own folder,
     # LLM context, thinking, toolkit and settings: the rest is nil then).
     # +preview+ set: the session starts idle with it as its preview, and
-    # +prompt+ (nil) goes in later as a turn (images, a session command).
+    # +prompt+ (nil) goes in later as a turn (images, a session command);
+    # +idle+ alone: it starts idle with no preview (a remote attach's new
+    # session, whose -p goes in once attached).
     # +setup+ is a SessionSetup for Local, a SetupWords for Remote (the
     # flags as typed: the server checks them against its own config and
     # bundles). +client_id+ (chi send's, or chi answer's for a parent's
@@ -59,9 +119,9 @@ module Samagotchi
     # which checks the first line and the model as chi send checks them
     # here (Local checks before it creates).
     NewSession = Data.define(:prompt, :preview, :continues, :working_directory, :model_name, :setup, :client_id,
-                             :images) do
+                             :images, :idle) do
       def initialize(prompt:, preview: nil, continues: nil, working_directory: nil, model_name: nil, setup: nil,
-                     client_id: nil, images: false) = super
+                     client_id: nil, images: false, idle: false) = super
     end
 
     # chi send --new's setup flags as typed, for a Remote: +llm_context+
@@ -94,6 +154,10 @@ module Samagotchi
     # its OwnerLock::Owner (a worker, a chi REPL, nil).
     WorkerState = Data.define(:sidecar, :stopped, :owner) do
       def live? = !sidecar.nil?
+
+      # No Bridge, and the owner is a worker leaving (writing its recap on
+      # leave): a wake waits for it (Local#wake).
+      def leaving? = !live? && !!owner&.leaving?
     end
 
     # What a wake for an attach did (Local#wake, chi web's POST …/wake):
@@ -101,6 +165,24 @@ module Samagotchi
     # worker's (nil: its Bridge didn't come within the wait).
     Woken = Data.define(:woke, :sidecar)
 
+    # A remote attach's wake (Remote#attach_wake, chi web's POST …/wake):
+    # +worker+ the live worker as chi web names it ({"epoch", "started_at",
+    # "version", "features"}, string keys: Remote#attach_client's), and
+    # what the TUI reads of that machine: its config's +default_model+,
+    # the session's parent +strategy+ (Guardrails::ParentPolicy::Strategy),
+    # the newest chi +installed+ there.
+    WakeReply = Data.define(:woke, :worker, :default_model, :strategy, :installed)
+
+    # A remote session's worker now (Remote#attach_worker, chi web's GET
+    # …/worker): +live+, +stopped+ (its stop marker), +worker+ as in
+    # WakeReply (nil: none runs), the parent +strategy+ read now, and that
+    # machine's +default_model+ (nil from a chi web before it sent one).
+    # +leaving+: its worker is leaving (WorkerState#leaving?), for up to
+    # +leave_seconds+ more there (nil from a chi web before it sent them).
+    WorkerReply = Data.define(:live, :stopped, :worker, :strategy, :default_model, :leaving, :leave_seconds) do
+      def initialize(live:, stopped:, worker:, strategy:, default_model: nil, leaving: false, leave_seconds: nil) = super
+    end
+
     # What chi send --wait and chi answer read before anything is sent, so
     # neither an older reply nor a turn that ends before the first look is
     # taken for the answer (ReplyWait's cursor:, baseline:, turn:).

data/lib/samagotchi/session_continue.rb

@@ -170,7 +170,7 @@ module Samagotchi
     private_class_method def self.discard_failed_link(id, state_dir)
       orphan = SessionChain.next_of(id, state_dir: state_dir) or return
       if SessionManager.refuse_tui!(orphan, state_dir: state_dir) &&
-         !SessionManager.stop_session(orphan, state_dir: state_dir, wait: 10)
+         !SessionManager.stop_session(orphan, state_dir: state_dir, wait: SessionManager::STOP_WAIT)
         raise SessionManager::DeleteRefused.new(orphan, :still_stopping)
       end
 

data/lib/samagotchi/session_inbox.rb

@@ -45,18 +45,23 @@ module Samagotchi
     #   "cut" or "queue"
     # @param images [Array<Hash>] image refs ({file:, name:}) in the
     #   session's images/
+    # @param author [String, nil] who wrote the message when it isn't the
+    #   session's owner (Web::Principal#author); nil, the owner's, is never
+    #   written, so an owner's file is as it always was
+    # @param now [Time] the time the file is named by (a spec's clock)
     # @return [String, false] the input file's path, or false
     def self.write_input(session_dir, prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [],
-                         delivery: nil)
+                         delivery: nil, author: nil, now: Time.now)
       images = Array(images)
       input_dir = File.join(session_dir, INPUT_DIR)
       FileUtils.mkdir_p(input_dir)
 
-      path = File.join(input_dir, "#{Time.now.strftime("%Y%m%d%H%M%S%9N")}.json")
+      path = File.join(input_dir, "#{now.strftime("%Y%m%d%H%M%S%9N")}.json")
       record = { "prompt" => prompt.to_s, "client_id" => client_id, "enqueued_id" => enqueued_id,
                  "no_interrupt" => (no_interrupt ? true : nil),
                  "delivery" => (Delivery.queue?(delivery) ? Delivery::QUEUE : nil),
-                 "images" => (images.empty? ? nil : images.map { |image| image.transform_keys(&:to_s) }) }.compact
+                 "images" => (images.empty? ? nil : images.map { |image| image.transform_keys(&:to_s) }),
+                 "author" => author }.compact
       AtomicFile.write(path, JSON.generate(record))
       path
     rescue StandardError
@@ -67,9 +72,11 @@ module Samagotchi
     # to the conversation between turns. It never starts a turn.
     # @param source [String] where it came from ("cli", "slack", "session")
     # @param from_session [String, nil] the sending session, for a peer's note
+    # @param now [Time] the time the file is named and stamped by (a spec's clock)
     # @return [String] the note file's path
     # @raise [NoteRejected] for an empty note or one over 16 KiB (never cut)
-    def self.write_note(session_id, text:, source: "cli", from_session: nil, from_cwd: nil, state_dir: nil)
+    def self.write_note(session_id, text:, source: "cli", from_session: nil, from_cwd: nil, state_dir: nil,
+                        now: Time.now)
       body = checked_text(text)
       sd = state_dir || Session.default_state_dir
       notes_dir = File.join(Session.session_dir(session_id, state_dir: sd), NOTES_DIR)
@@ -77,10 +84,10 @@ module Samagotchi
 
       # The random part keeps two writers in one nanosecond apart; the
       # timestamp keeps the names in arrival order.
-      name = "#{Time.now.strftime("%Y%m%d%H%M%S%9N")}-#{SecureRandom.hex(3)}.json"
+      name = "#{now.strftime("%Y%m%d%H%M%S%9N")}-#{SecureRandom.hex(3)}.json"
       path = File.join(notes_dir, name)
       record = { "text" => body, "source" => source.to_s, "from_session" => from_session,
-                 "from_cwd" => from_cwd, "created_at" => Time.now.iso8601 }.compact
+                 "from_cwd" => from_cwd, "created_at" => now.iso8601 }.compact
       AtomicFile.write(path, JSON.generate(record))
       path
     end
@@ -166,10 +173,11 @@ module Samagotchi
     # so an id'd name and a bare one of the same timestamp keep order);
     # every reader globs *.txt.
     # @param enqueued_id [String, nil] the turn's input id (LastTurn#enqueued_id)
-    def self.write_output(session_dir, response, enqueued_id: nil)
+    # @param now [Time] the time the file is named by (a spec's clock)
+    def self.write_output(session_dir, response, enqueued_id: nil, now: Time.now)
       output_dir = File.join(session_dir, OUTPUT_DIR)
       FileUtils.mkdir_p(output_dir)
-      timestamp = Time.now.strftime("%Y%m%d%H%M%S%9N")
+      timestamp = now.strftime("%Y%m%d%H%M%S%9N")
       AtomicFile.write(File.join(output_dir, "#{output_name(timestamp, enqueued_id)}.txt"), response.to_s)
     end
 
@@ -229,7 +237,8 @@ module Samagotchi
       data = JSON.parse(File.read(claimed_file).to_s)
       return UNREADABLE_INPUT unless data.is_a?(Hash)
 
-      origin = { client_id: data["client_id"], enqueued_id: data["enqueued_id"] }.compact
+      # author: only a file that names one (an owner's names none).
+      origin = { client_id: data["client_id"], enqueued_id: data["enqueued_id"], author: data["author"] }.compact
       images = Array(data["images"]).select { |image| image.is_a?(Hash) }.map { |image| image.transform_keys(&:to_sym) }
       Input.new(prompt: data["prompt"].to_s, origin: origin.empty? ? nil : origin, no_interrupt: data["no_interrupt"] == true,
                 images: images, delivery: Delivery.queue?(data["delivery"]) ? Delivery::QUEUE : nil)

data/lib/samagotchi/session_manager.rb

@@ -69,6 +69,8 @@ module Samagotchi
   autoload :SessionRetention, File.expand_path("session_retention", __dir__)
   # session_continue requires this file.
   autoload :SessionContinue, File.expand_path("session_continue", __dir__)
+  # Needed only on an archive or a delete (it loads Web::Grants).
+  autoload :Participants, File.expand_path("participants", __dir__)
 
   class SessionManager
     # Raised when the interactive TUI owns the session: it runs its own Engine
@@ -384,6 +386,8 @@ module Samagotchi
       stopped = tree.select { |sid| owners[sid] }
       stopped.each { |sid| stop_session(sid, state_dir: sd, wait: wait) }
       archived, discarded = tree.partition { |sid| ArchiveStore.archive(sid, state_dir: sd) }
+      # D8: an archive ends the review (unarchiving doesn't restore it).
+      Participants.end_sessions(archived, by: "archive", state_dir: sd)
       { id: id, archived: archived, stopped: stopped, discarded: discarded }
     end
 
@@ -706,6 +710,10 @@ module Samagotchi
     end
 
     STOP_CANCEL_WAIT = 3.0
+    # How long a stop from the CLI (chi sessions stop, delete, a continue's
+    # orphan) waits for the worker to let go of the session, here or
+    # through chi web (POST …/stop's wait, capped at it).
+    STOP_WAIT = 10
     # The cancel reason of a turn a session stop cancels (Bridge::CANCEL_REASONS):
     # not the user's Stop, which only ends the turn ("user").
     STOP_CANCEL_REASON = "session_stopped"
@@ -869,7 +877,7 @@ module Samagotchi
     # @raise [OwnedByTUI] a chi REPL owns it (never stopped from here)
     # @raise [DeleteRefused] a worker owns it and +stop+ is false, or it
     #   outlived the wait
-    def self.delete_session(id_or_prefix, state_dir: nil, stop: false, wait: 10)
+    def self.delete_session(id_or_prefix, state_dir: nil, stop: false, wait: STOP_WAIT)
       sd = state_dir || Session.default_state_dir
       given = id_or_prefix.to_s
       # Only a plain id: anything else could name a path outside the state dir.
@@ -897,6 +905,7 @@ module Samagotchi
       end
       PluginSessionState.remove(id)
       removed.concat(ContextSources.remove_session(id, state_dir: sd))
+      Participants.end_sessions([id], by: "delete", state_dir: sd)
       { id: id, removed: removed, stopped: !owner.nil? }
     end
 
@@ -960,7 +969,8 @@ module Samagotchi
       # loop run in-process (specs) traps nothing.
       signals = spawned ? WorkerSignals.new.install! : WorkerSignals::NONE
       worker = Worker.new(session_id: session_id, state_dir: sd, session_dir: session_dir,
-                          idle_exit_minutes: idle_exit_minutes, poll_interval: poll_interval, signals: signals)
+                          idle_exit_minutes: idle_exit_minutes, poll_interval: poll_interval, signals: signals,
+                          owner_lock: @owner_lock)
       result = begin
         worker.run
       rescue StandardError, ScriptError => e
@@ -1137,10 +1147,10 @@ module Samagotchi
     #   session's images/
     # @return [String, false] the input file's path, or false.
     def self.write_turn_input(session_id, prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, state_dir: nil,
-                              images: [], delivery: nil)
+                              images: [], delivery: nil, author: nil)
       session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
       SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                                            no_interrupt: no_interrupt, images: images, delivery: delivery)
+                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author)
     end
 
     # How long a turn waits for the Bridge of a worker a resume just spawned.
@@ -1202,6 +1212,10 @@ module Samagotchi
     # @param no_interrupt [Boolean] the turn runs with the raised iteration
     #   limit (an attached TUI's --no-interrupt), through the Bridge or the
     #   file; sent only when true, so older callees see no new field
+    # @param author [String, nil] who wrote it when it isn't the session's
+    #   owner (Web::Principal#author: chi web stamps it, never the body);
+    #   to the Bridge or the file only when given, so an owner's turn is
+    #   sent and saved as before
     # @param manager [#resume_session, #write_turn_input] this class, or a
     #   stand-in (the web's specs); #session_owner is optional
     # @param bridge [#call, nil] returns the BridgeClient or nil; defaults to
@@ -1215,7 +1229,7 @@ module Samagotchi
     # @raise [OwnedByTUI] a chi REPL owns the session
     # @raise [ArgumentError] no such session
     def self.deliver_turn(session_id, prompt:, client_id: nil, images: [], delivery: nil, no_interrupt: false,
-                          state_dir: nil, manager: self, bridge: nil)
+                          author: nil, state_dir: nil, manager: self, bridge: nil)
       session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
       bridge ||= -> { BridgeClient.wait_for(session_id, session_dir: session_dir, timeout: TURN_BRIDGE_WAIT) }
       manager.resume_session(session_id, state_dir: state_dir)
@@ -1230,6 +1244,7 @@ module Samagotchi
           # An old worker ignores the field: it cuts anyway (its own default).
           options[:delivery] = delivery unless Delivery.next_step?(delivery)
           options[:no_interrupt] = true if no_interrupt
+          options[:author] = author if author
           reply = client.post_turn(**options)
           ack = reply.json
           return DeliverResult.new(status: :accepted, via: :bridge, ack: ack) if reply.status == 202 && ack.is_a?(Hash)
@@ -1257,6 +1272,7 @@ module Samagotchi
       input[:images] = images unless images.empty?
       input[:delivery] = delivery unless Delivery.next_step?(delivery)
       input[:no_interrupt] = true if no_interrupt
+      input[:author] = author if author
       path = manager.write_turn_input(session_id, **input)
       return DeliverResult.new(status: :failed) unless path
 

data/lib/samagotchi/sessions_command.rb

@@ -389,7 +389,7 @@ module Samagotchi
       ok = ids.uniq.map do |given|
         begin
           id = @access.resolve_id(given)
-          released = @access.stop(id, wait: 10)
+          released = @access.stop(id, wait: Samagotchi::SessionManager::STOP_WAIT)
         rescue Samagotchi::SessionManager::OwnedByTUI => e
           @stdout.flush
           @stderr.puts e.message
@@ -399,13 +399,13 @@ module Samagotchi
           @stderr.puts e.message
           next false
         end
-        # Remotely no chi --resume (remote attach is its own phase).
+        # chi --resume ID, or chi --remote NAME --resume ID.
         resume = @access.invocation.resume(id)
         if released
-          @stdout.puts "Stopped session #{id}.#{" #{resume} starts a fresh worker." if resume}"
+          @stdout.puts "Stopped session #{id}. #{resume} starts a fresh worker."
         else
           @stdout.flush
-          @stderr.puts "Stopped session #{id}, but its worker is still shutting down#{"; try #{resume} in a moment" if resume}."
+          @stderr.puts "Stopped session #{id}, but its worker is still shutting down; try #{resume} in a moment."
         end
         true
       end

data/lib/samagotchi/share_command.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "session"
+require_relative "session_access"
+require_relative "session_access/local"
+require_relative "web/grants"
+require_relative "web/qr"
+
+module Samagotchi
+  # `chi share`: invite a participant to review a session (the
+  # shared-sessions plan: a Web::Grants grant, one session, one person or
+  # agent, 7 days unless --expires says otherwise), list the participants,
+  # revoke them. Local or through chi --remote NAME (SessionAccess). The
+  # token is printed once, in the link; chi keeps only its digest. See
+  # docs/internals/participants.md.
+  class ShareCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi share ID --name NAME [--agent] [--expires 3d]
+             chi share ls [ID] [--format text|json]
+             chi share revoke ID [PARTICIPANT] | --all
+        ID --name NAME   invite NAME to review session ID: prints the link they open (chi web on
+                         the LAN, web.host: lan) and its QR code at a terminal. The link is shown
+                         once; chi keeps only a digest of its token.
+          --agent        the participant is an agent (the same link, used as a Bearer token)
+          --expires N    Nh or Nd, 1h to 30d (default 7d)
+        ls [ID]          the participants of ID, or of every session (never a token)
+        revoke ID [P]    end participant P's link, or every link to ID; --all every session's
+      Archiving or deleting a session revokes its links. A participant sees the session's title
+      and status; comments come in a later chi.
+    TEXT
+
+    SUBCOMMANDS = %w[ls revoke].freeze
+
+    # The invite's flags (chi share ID …), and ls's and revoke's.
+    FLAGS = CLI::Flags.new(help: HELP_WORDS) do |f|
+      f.value "--name"
+      f.switch "--agent"
+      f.value "--expires"
+    end
+    SUB_FLAGS = {
+      "ls" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--format" },
+      "revoke" => CLI::Flags.new(help: HELP_WORDS) { |f| f.switch "--all" }
+    }.freeze
+
+    EXPIRES_RE = /\A(\d+)([hd])\z/
+    TIME_FORMAT = "%m-%d %H:%M"
+
+    # @param access [SessionAccess::Local, SessionAccess::Remote, nil]
+    #   where the sessions are; default this machine's, in +state_dir+
+    # @param tty [Boolean, nil] print the QR code (default: stdout is a TTY)
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, access: nil, tty: nil)
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @access = access || SessionAccess::Local.new(state_dir: state_dir)
+      @tty = tty.nil? ? @stdout.respond_to?(:tty?) && @stdout.tty? : tty
+    end
+
+    # @return [Integer] exit status: 0 done, 1 refused or failed, 2 usage
+    def run
+      first = @argv[0]
+      if first.nil? || HELP_WORDS.include?(first)
+        @stdout.puts(USAGE)
+        return 0
+      end
+
+      @sub = SUBCOMMANDS.include?(first) ? first : nil
+      parsed = parse_flags(@sub ? SUB_FLAGS.fetch(@sub) : FLAGS, @sub ? @argv[1..] : @argv)
+      return parsed if parsed.is_a?(Integer)
+
+      send(:"run_#{@sub || "invite"}", parsed.options, parsed.args)
+    rescue SessionAccess::BadRequest => e
+      usage_error(e.message)
+    rescue ArgumentError => e
+      error_line("#{command_name}: #{e.is_a?(Session::AmbiguousId) ? e.message : e.message.sub(/\ASession not found: /, "no session ")}")
+      CLI::Exit::FAILED
+    end
+
+    private
+
+    def command_name = @sub ? "chi share #{@sub}" : "chi share"
+    def usage_on_error = nil
+
+    def run_invite(options, args)
+      return usage_error("give one session ID") unless args.size == 1
+      return usage_error("--name NAME: who the link is for") if options[:name].to_s.strip.empty?
+
+      ttl = expires(options[:expires])
+      return usage_error("--expires takes Nh or Nd, 1h to 30d (e.g. 3d)") if ttl == false
+
+      id = @access.resolve(args.first)
+      invitation = @access.invite(id, name: options[:name], kind: options[:agent] ? "agent" : "human", ttl: ttl)
+      print_invitation(id, invitation)
+      0
+    end
+
+    def run_ls(options, args)
+      return usage_error("ls takes at most one session ID") if args.size > 1
+
+      format = options[:format]
+      return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
+
+      id = args.first && @access.resolve(args.first)
+      rows = @access.participants(id)
+      if format == "json"
+        @stdout.puts(JSON.generate(rows.map(&:to_h)))
+      elsif rows.empty?
+        @stdout.puts(id ? "no participants in #{id[0, 8]} (chi share #{id[0, 8]} --name NAME invites one)" : "no participants")
+      else
+        print_table(rows)
+      end
+      0
+    end
+
+    def run_revoke(options, args)
+      if options[:all]
+        return usage_error("--all takes no session ID") unless args.empty?
+      elsif !args.size.between?(1, 2)
+        return usage_error("give a session ID (and a participant), or --all")
+      end
+      participant = args[1]
+      return usage_error("not a participant: #{participant} (chi share ls lists them)") if participant && !Web::Grants::ID_RE.match?(participant)
+
+      id = args.first && @access.resolve(args.first)
+      revoked = @access.revoke_participants(id, participant: participant)
+      revoked.each { |row| @stdout.puts("#{row.id}  #{row.name}  revoked") }
+      @stdout.puts("nothing to revoke") if revoked.empty?
+      0
+    end
+
+    # Seconds, nil for the default, false for words that aren't Nh/Nd.
+    def expires(words)
+      return nil if words.nil?
+
+      match = EXPIRES_RE.match(words.to_s.strip) or return false
+      seconds = match[1].to_i * (match[2] == "h" ? 3600 : Web::Grants::DAY)
+      seconds.between?(3600, Web::Grants::MAX_TTL) ? seconds : false
+    end
+
+    def print_invitation(id, invitation)
+      row = invitation.participant
+      @stdout.puts("#{row.id}  #{row.name} (#{row.kind}, #{row.role}) · session #{id[0, 8]} · expires #{local(row.expires_at, "%Y-%m-%d %H:%M")}")
+      @stdout.puts(invitation.link)
+      @stdout.puts("(shown once: chi keeps only its digest; chi share revoke #{id[0, 8]} #{row.id} ends it)")
+      unless invitation.lan
+        @stdout.puts("chi web isn't on the LAN there (web.host: lan): this link opens on that machine only")
+      end
+      @stdout.puts(Web::QR.lines(invitation.link)) if @tty
+    end
+
+    COLUMNS = ["SESSION", "PARTICIPANT", "NAME", "KIND", "ROLE", "CREATED", "EXPIRES", "LAST USED", "STATE"].freeze
+
+    def print_table(rows)
+      cells = rows.map do |row|
+        [row.session_id[0, 8], row.id, row.name, row.kind, row.role, local(row.created_at), local(row.expires_at),
+         row.last_used_at ? local(row.last_used_at) : "-", row.state]
+      end
+      widths = COLUMNS.each_index.map { |i| ([COLUMNS[i]] + cells.map { |c| c[i] }).map(&:length).max }
+      [COLUMNS, *cells].each do |line|
+        @stdout.puts(line.each_with_index.map { |cell, i| i == line.size - 1 ? cell : cell.ljust(widths[i]) }.join("  "))
+      end
+    end
+
+    def local(stamp, format = TIME_FORMAT) = Time.iso8601(stamp.to_s).localtime.strftime(format)
+  end
+end

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -107,13 +107,15 @@ module Samagotchi
           close_surface(surface)
         end
         if ended == :unanswered && attached.unanswered
-          # A link's strategy is read where the session is, its commands
-          # spelled its way.
+          # A link's strategy is read where the session is, now (L4), its
+          # commands spelled its way.
           where = connector ? { strategy: link.parent_strategy, via: link.via } : {}
           report_unanswered(attached.unanswered, session_id: client.session_id, state_dir: state_dir, **where)
         end
         report_ended(ended)
         ended
+      ensure
+        link&.close
       end
 
       # This TUI's client id: tui:PID, or the connector's own (a remote one
@@ -193,6 +195,7 @@ module Samagotchi
           resume = attach
         end
 
+        await_leaving_worker(resume, sd, err) if resume
         session = if resume
                     SessionManager.resume_session(resume, state_dir: sd)
                   else
@@ -206,12 +209,22 @@ module Samagotchi
                   end
         client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
         client || raise(Error, format(LaunchMode::BRIDGE_LATE, session.id))
-      rescue SessionManager::OwnedByTUI
-        raise Error, "session #{resume} is open in a chi REPL; close it there first"
+      rescue SessionManager::OwnedByTUI => e
+        raise Error, e.message
       rescue ArgumentError => e
         raise Error, e.message
       end
 
+      # The session's previous worker may still be leaving: its Bridge
+      # closed, the lock held while it writes its recap on leave (a resume
+      # now would start nothing, the lock taken). Wait for it to let go
+      # (OwnerLock.await_release), with one line saying so; any other owner
+      # is left to resume_session as before.
+      def await_leaving_worker(session_id, state_dir, err)
+        OwnerLock.await_release(Session.session_dir(session_id, state_dir: state_dir),
+                                on_wait: ->(_owner) { err.puts(LaunchMode::RECAP_WAIT) })
+      end
+
       # --model as typed: spawn_session stores the resolved ref and this name.
       def model_ref(model)
         ModelProfile.required_model_name(model)