samagotchi 0.103.0 → 0.104.0

data/lib/samagotchi/chi_invocation.rb

@@ -2,12 +2,10 @@
 
 module Samagotchi
   # How the follow-up commands chi prints (ParentReport's chi answer and
-  # chi send --wait, a stop's chi --resume) are spelled so that they work
-  # when pasted: on this machine plain chi, against a remote (chi --remote
-  # NAME, CHI_REMOTE=NAME alike) chi --remote NAME. What runs on this
-  # machine only (--attach, --resume: remote attach is its own phase) has
-  # no remote form: #attach and #resume are nil there, and #open_it and
-  # #shows name the remote's chi web instead.
+  # chi send --wait, a stop's chi --resume, the attached TUI's re-attach
+  # lines) are spelled so that they work when pasted: on this machine plain
+  # chi, against a remote (chi --remote NAME, CHI_REMOTE=NAME alike) chi
+  # --remote NAME. A remote's chi web is named where the page is meant.
   # @!attribute remote [String, nil] the remote's name; nil: this machine
   ChiInvocation = Data.define(:remote) do
     def remote? = !remote.nil?
@@ -18,19 +16,18 @@ module Samagotchi
     # +words+ after #chi: command("answer ID …").
     def command(words) = "#{chi} #{words}"
 
-    # chi --attach ID; nil remotely.
-    def attach(id) = ("chi --attach #{id}" unless remote?)
+    # chi --attach ID (chi --remote NAME --attach ID).
+    def attach(id) = command("--attach #{id}")
 
-    # chi --resume ID; nil remotely.
-    def resume(id) = ("chi --resume #{id}" unless remote?)
+    # chi --resume ID (chi --remote NAME --resume ID).
+    def resume(id) = command("--resume #{id}")
 
-    # What shows the session ("… shows it"): chi --attach ID, or the
-    # remote's chi web.
-    def shows(id) = attach(id) || web
+    # What shows the session ("… shows it"): its attach.
+    def shows(id) = attach(id)
 
-    # Where the user opens it ("open it: …"): chi --attach ID or the web,
-    # or the remote's chi web.
-    def open_it(id) = remote? ? web : "#{attach(id)} or the web"
+    # Where the user opens it ("open it: …"): its attach, or the web (the
+    # remote's chi web).
+    def open_it(id) = "#{attach(id)} or #{remote? ? web : "the web"}"
 
     # The remote's chi web, by name.
     def web = "chi web on #{remote}"

data/lib/samagotchi/context_status.rb

@@ -116,13 +116,20 @@ module Samagotchi
     #   last status line's bucket is where rises count from)
     # @param llm_context [LLMContextStrategy::Resolved, nil] the turn's
     #   strategy (its budget)
-    def initialize(conversation: [], llm_context: nil)
+    # @param counted_chars_per_token [Float, nil] the last turn's
+    #   #counted_chars_per_token: the turn's estimate before its first count
+    #   uses it instead of the configured ratio, so the value doesn't dip at
+    #   a turn's start (the chat loop's chars leave out the tool schemas the
+    #   server counts)
+    def initialize(conversation: [], llm_context: nil, counted_chars_per_token: nil)
       @budget = llm_context&.budget_tokens
       @forget = llm_context&.forget? || false
       @offered = self.class.last_line(conversation).to_s.include?(OFFER_TOOL)
       @enabled = self.class.enabled?
       chars_per_token = Config.get("context.chars_per_token").to_f
       @chars_per_token = chars_per_token.positive? ? chars_per_token : DEFAULT_CHARS_PER_TOKEN
+      @estimate_chars_per_token = counted_chars_per_token.to_f.positive? ? counted_chars_per_token.to_f : @chars_per_token
+      @counted_chars_per_token = nil
       parsed = Config.get("context.status_thresholds").to_s.split(",").map { |value| value.strip.to_i }
                      .select { |value| value.between?(1, 99) }.uniq.sort
       @thresholds = parsed.empty? ? DEFAULT_THRESHOLDS : parsed
@@ -137,6 +144,10 @@ module Samagotchi
     # @return [Hash, nil] the status line's value ({est_pct:, bucket:});
     #   nil with context.status off or before the first request
     attr_reader :display
+    # @return [Float, nil] the chars per token of the last request the
+    #   server counted (its prompt chars over its prompt tokens, images
+    #   aside), for the next turn's tracker; nil before a count
+    attr_reader :counted_chars_per_token
 
     def enabled? = @enabled
 
@@ -212,6 +223,8 @@ module Samagotchi
 
       @counted = { chars: prompt_chars, image_tokens: image_tokens }
       @edited = false
+      text_tokens = usage[:prompt_tokens].to_i - image_tokens.to_i
+      @counted_chars_per_token = prompt_chars.to_f / text_tokens if prompt_chars.positive? && text_tokens.positive?
       value = display_for(used_tokens: usage[:total_tokens], window_tokens: usage[:context_window_tokens] || window&.tokens)
       @display = value if value
     end
@@ -243,7 +256,7 @@ module Samagotchi
         source = "server"
       else
         window_tokens = counted_against(window.tokens)
-        used_tokens = (prompt_chars / @chars_per_token).ceil + image_tokens
+        used_tokens = (prompt_chars / @estimate_chars_per_token).ceil + image_tokens
         source = "estimate"
       end
 

data/lib/samagotchi/engine.rb

@@ -1858,6 +1858,11 @@ module Samagotchi
       @recap&.write_now(on_start: on_start)
     end
 
+    # The longest #write_recap_now waits (recap.timeout), nil when no recap
+    # is set up.
+    # @return [Float, nil]
+    def recap_timeout = @recap&.timeout
+
     # Ask for a recap now (/recap), without waiting for the idle window.
     # @return [Symbol] IdleRecap#request_now's answer, or :off
     def request_recap
@@ -1887,9 +1892,12 @@ module Samagotchi
       self
     end
 
-    # Stop the shared idle scheduler (TerminalUI calls this when the REPL exits).
-    def stop_idle
-      @idle_scheduler&.stop
+    # Stop the shared idle scheduler (TerminalUI calls this when the REPL
+    # exits). +join+: wait for a tick under way (IdleScheduler#stop); a
+    # caller holding #synchronize_events passes false, since a recap's emit
+    # in that tick waits for the same lock.
+    def stop_idle(join: true)
+      @idle_scheduler&.stop(join: join)
       self
     end
 
@@ -1947,9 +1955,11 @@ module Samagotchi
     #   run it resumes started (ModelResult#run_start, kept in the offer by
     #   TurnFlow), so it keeps that run's reasoning; nil starts cold (a
     #   model change while the offer stood, every other turn).
-    # @param origin [Hash, nil] who queued the turn ({client_id:, enqueued_id:});
-    #   when given, the turn's boundary events (:turn_started, :turn_completed,
-    #   :turn_canceled, :turn_failed) carry it as `origin:`
+    # @param origin [Hash, nil] who queued the turn ({client_id:, enqueued_id:},
+    #   and author: when someone other than the session's owner wrote it, from
+    #   its input file; absent for the owner); when given, the turn's boundary
+    #   events (:turn_started, :turn_completed, :turn_canceled, :turn_failed)
+    #   carry it as `origin:`, and GuardrailWiring#begin_turn gets it
     # @param images [Array<Hash>] the prompt's images: {path:} (a file on this
     #   machine; in-process and attached-TUI callers only) or {file:, name:}
     #   (already in the session's images/, e.g. a web upload). They are

data/lib/samagotchi/guardrail_wiring.rb

@@ -83,12 +83,18 @@ module Samagotchi
       @protected = nil
     end
 
-    # A turn starts: its origin, and the git facts read afresh.
+    # A turn starts: its origin (Engine#run_turn's: {client_id:,
+    # enqueued_id:, author:}, each optional), and the git facts read afresh.
     def begin_turn(origin)
       @origin = origin
       @git = Guardrails::GitInfo.new
     end
 
+    # Who wrote the running turn when it isn't the session's owner (its
+    # origin's author); nil for the owner's turns and every other origin.
+    # @return [String, nil]
+    def turn_author = @origin.is_a?(Hash) ? @origin[:author] : nil
+
     # The gate every tool call asks first.
     # @return [Guardrails::Gate]
     def gate

data/lib/samagotchi/idle_recap.rb

@@ -254,7 +254,7 @@ module Samagotchi
     end
 
     # @return [Array(Integer, Integer)] the recap length range, e.g. [2, 4]
-    attr_reader :generation, :inactivity, :min_user_turns, :sentences
+    attr_reader :generation, :inactivity, :min_user_turns, :sentences, :timeout
 
     # @param callable [#call] true while a continue offer waits for an
     #   answer (the Worker's or the REPL's TurnFlow); read at each attempt

data/lib/samagotchi/idle_scheduler.rb

@@ -18,23 +18,37 @@ module Samagotchi
   # raises is logged and isolated — the remaining jobs keep polling.
   class IdleScheduler
     POLL_INTERVAL_SECONDS = 0.5
+    # How long #stop waits for the thread to finish its tick before it
+    # kills it.
+    STOP_JOIN_SECONDS = 1.0
+    THREAD_NAME = "idle_scheduler"
 
-    attr_reader :engine, :jobs
+    attr_reader :engine, :jobs, :interval
 
-    def initialize(engine:, jobs: [])
+    # +interval+: the pause between ticks (a spec passes a long one, so its
+    # own #tick is the only one after the first).
+    def initialize(engine:, jobs: [], interval: POLL_INTERVAL_SECONDS)
       raise ArgumentError, "IdleScheduler requires an engine" unless engine
 
       @engine = engine
       @jobs = jobs.compact.freeze
+      @interval = interval
+      # The loop's pause: a pop with the interval as its timeout, which
+      # #stop ends at once by pushing.
+      @wake = Queue.new
       @thread = nil
+      # The thread a stop(join: false) left to finish its tick.
+      @unjoined = nil
       @stopped = false
     end
 
     # Spawn the polling thread (idempotent; no-op when there are no jobs).
+    # A stopped scheduler doesn't start again.
     def start
       return self if running? || @jobs.empty?
 
       @thread = Thread.new { run_loop }
+      @thread.name = THREAD_NAME
       self
     end
 
@@ -42,11 +56,24 @@ module Samagotchi
       !@thread.nil? && @thread.alive? && !@stopped
     end
 
-    # Stop the polling thread (idempotent).
-    def stop
+    # Stop the polling thread (idempotent): it ticks no more and its pause
+    # ends at once. +join+: wait up to STOP_JOIN_SECONDS for a tick under
+    # way to finish, then kill the thread. A caller holding a lock a tick
+    # may take (Worker#leave_idle holds the event log, which a recap's emit
+    # takes) passes join: false: the thread finishes its tick and exits by
+    # itself, and a later joining stop (Engine#shutdown, the worker's
+    # teardown) still joins it. From the scheduler's own thread (a job's
+    # tick) it never joins.
+    def stop(join: true)
       @stopped = true
-      @thread&.kill
+      @wake << :stop
+      thread = @thread || @unjoined
       @thread = nil
+      @unjoined = join ? nil : thread
+      return if thread.nil? || !join || thread == Thread.current
+
+      thread.kill unless thread.join(STOP_JOIN_SECONDS)
+      nil
     end
 
     # Swap the job +old+ for +new+ (Engine#session= rebuilding the recap):
@@ -78,11 +105,9 @@ module Samagotchi
     private
 
     def run_loop
-      loop do
-        break if @stopped
-
+      until @stopped
         tick
-        sleep(POLL_INTERVAL_SECONDS)
+        @wake.pop(timeout: @interval)
       end
     rescue StandardError => e
       Log.exception(:idle, "scheduler_crashed", e, echo: "[IdleScheduler] scheduler thread crashed: #{e.class}: #{e.message}")

data/lib/samagotchi/kernel_loop.rb

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

data/lib/samagotchi/launch_mode.rb

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

data/lib/samagotchi/llm/chat_loop.rb

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

data/lib/samagotchi/owner_lock.rb

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

data/lib/samagotchi/participants.rb

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