samagotchi 0.103.0 → 0.105.0

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/session_metrics.rb

@@ -17,6 +17,7 @@ require_relative "session_metrics/cost"
 require_relative "session_metrics/usage"
 require_relative "session_metrics/side_totals"
 require_relative "side_usage"
+require_relative "steer"
 
 module Samagotchi
   # SessionMetrics is a persistent, error-isolated collector of per-session
@@ -174,6 +175,9 @@ module Samagotchi
       # The turn the user started by answering the step-limit question with
       # Continue (:turn_started's +resumed+): it resumed the run before it.
       :resumed,
+      # Who wrote the turn when it wasn't the owner (:turn_started's
+      # origin author, "p:<id>"); its record carries it, the owner's none.
+      :author,
       :id,
       :started_at,
       :started_monotonic,
@@ -695,6 +699,7 @@ module Samagotchi
           gen_switch: false,
           continue: event[:continue] ? true : false,
           resumed: event[:resumed] ? true : false,
+          author: Steer.sender_author(event[:origin].is_a?(Hash) ? event[:origin][:author] : nil),
           id: event[:turn_id] || SecureRandom.uuid,
           started_at: now.iso8601(3),
           started_monotonic: monotonic_time,
@@ -735,6 +740,7 @@ module Samagotchi
           # from one written before the mark.
           record[:continue] = @turn.continue
           record[:resumed] = @turn.resumed
+          record[:author] = @turn.author if @turn.author
           record.merge!(turn_token_fields(@turn))
           @turn_records << record
           count_turn(record)
@@ -751,7 +757,7 @@ module Samagotchi
       {
         id: @turn.id, status: "canceled", started_at: @turn.started_at, completed_at: now.iso8601(3),
         duration_ms: elapsed_ms(@turn.started_monotonic), cancellation_reason: "worker_stopped",
-        continue: @turn.continue, resumed: @turn.resumed
+        continue: @turn.continue, resumed: @turn.resumed, **{ author: @turn.author }.compact
       }.merge(turn_token_fields(@turn))
     end
 

data/lib/samagotchi/session_participants.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Loaded only when a session is read: it brings Web::Grants (and Rack).
+  autoload :Participants, File.expand_path("participants", __dir__)
+
+  # What a session's Engine knows of its participants: participants.json
+  # (Participants.read), read at each turn's start (#refresh!), never
+  # written here. A session nobody was invited to has no sidecar: one
+  # File.exist? per turn. See docs/internals/participants.md (Attribution).
+  class SessionParticipants
+    # @param state_dir [#call] → the sessions' state dir
+    # @param clock [#call] → Time, what "still active" is measured at
+    def initialize(state_dir:, clock: -> { Time.now })
+      @state_dir = state_dir
+      @clock = clock
+      @session_id = nil
+      @entries = []
+    end
+
+    # Reads +session+'s sidecar again.
+    def refresh!(session)
+      @session_id = session&.id
+      @entries = read
+      self
+    end
+
+    # Whether anyone is still in the review (Participants::Entry#active?),
+    # as of the last #refresh!.
+    def active? = @entries.any? { |entry| entry.active?(@clock.call) }
+
+    # The name +author+ ("p:<id>") had when it was invited, nil for none
+    # (the owner, or a participant the sidecar doesn't name). A miss reads
+    # the sidecar again: someone invited after the turn began. +session+:
+    # the session it is asked for, when that may not be the last refreshed
+    # (the worker's running save, before the Engine's first turn).
+    def name_for(author, session: nil)
+      return nil unless Steer.participant_author?(author)
+
+      refresh!(session) if session && session.id != @session_id
+      id = author.to_s.delete_prefix("p:")
+      entry = @entries.find { |e| e.id == id } || (@entries = read).find { |e| e.id == id }
+      entry&.name
+    end
+
+    private
+
+    def read
+      return [] if @session_id.to_s.empty?
+
+      dir = Session.session_dir(@session_id, state_dir: @state_dir.call)
+      return [] unless File.exist?(File.join(dir, "participants.json"))
+
+      Participants.read(@session_id, state_dir: @state_dir.call)
+    rescue StandardError
+      []
+    end
+  end
+end

data/lib/samagotchi/sessions_command.rb

@@ -176,29 +176,32 @@ module Samagotchi
       # project's. Machine-local (this cwd's project): remotely every
       # project's (D4), and --scope=project is --cwd's project there (the
       # server finds its root). The rows are the server's (list_summaries).
+      # The picker (chi note from a script): filters apply before the limit,
+      # and test runs stay out, unless this is one (SAMAGOTCHI_ENV=test, CI):
+      # then its own sessions are what it looks for. The plain listing shows
+      # them, marked [test], here and remotely.
+      picker = @opts[:live] || cwd || (format && format != "text")
+      include_tests = !picker || Samagotchi::Session.test_session_env?
       if @access.remote?
         return usage_error("--scope=project on a remote needs --cwd: a folder there") if scope == "project" && !cwd
 
         project = scope == "project" ? cwd : nil
         scope_note = ->(count) { "#{count} session(s) in #{File.basename(project)} on #{@access.name} (--scope=all: every project)" }
-        return list_summaries(project, scope_note)
+        return list_summaries(project, scope_note, include_tests: include_tests)
       end
       project = scope == "all" || cwd ? nil : Samagotchi::ProjectScope.root_for(Dir.pwd)
       scope_note = ->(count) { "#{count} session(s) in #{File.basename(project)} (--scope=all: every project)" }
 
-      # The picker (chi note from a script): filters apply before the limit,
-      # and test runs stay out, unless this is one (SAMAGOTCHI_ENV=test, CI):
-      # then its own sessions are what it looks for.
-      return list_summaries(project, scope_note) if @opts[:live] || cwd || (format && format != "text")
+      return list_summaries(project, scope_note, include_tests: include_tests) if picker
 
       list_plain(project, scope_note)
     end
 
-    def list_summaries(project, scope_note)
+    def list_summaries(project, scope_note, include_tests:)
       live, cwd, limit, include_archived, format, sort, order =
         @opts.values_at(:live, :cwd, :limit, :include_archived, :format, :sort, :order)
       summaries = @access.summaries(
-        live: live, cwd: cwd, limit: limit || (live ? 10 : nil), include_tests: Samagotchi::Session.test_session_env?,
+        live: live, cwd: cwd, limit: limit || (live ? 10 : nil), include_tests: include_tests,
         project_root: project,
         include_archived: include_archived, sort: sort, order: order
       )
@@ -389,7 +392,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 +402,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