samagotchi 0.104.0 → 0.106.0

data/lib/samagotchi/guardrails/review_boundary.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "protected_paths"
+require_relative "shell_paths"
+require_relative "../paths"
+require_relative "../toolkit"
+require_relative "../steer"
+
+module Samagotchi
+  module Guardrails
+    # A participant's turn may only read (D3, D4: it proposes, the owner
+    # applies). A core check, on in every guardrails mode and with
+    # guardrails.enabled: false, active only while the running turn's author
+    # is a participant (GuardrailWiring#checks); the owner's turns never get
+    # it. It denies, never asks (nobody on the participant's side may
+    # approve, and the owner's approval would be the participant's text
+    # acting with the owner's power), every call outside the review kit
+    # (Toolkit::REVIEW_TOOLS). Not forget_outputs: it would replace the
+    # owner's earlier tool outputs with a note of the participant's, which
+    # later owner turns read as their own output, with no review header.
+    #   read: only under the session's project root, and never a file of
+    #     the read denylist (chi's state and config dirs, home secret dirs,
+    #     project secret files), checked on the path as given and as it
+    #     resolves (a symlink in the project to ~/.ssh is ~/.ssh);
+    #   memory_read: the project scope only, named (no fallback to system);
+    #   anything else, call_tool's real target included: a call_tool of a
+    #     built-in reaches the gate as that built-in (ToolRunner#unwrapped),
+    #     so what is left of call_tool is a plugin or MCP tool, denied in v1.
+    # The declared tools stay the session's (no prompt rebuild per author),
+    # so a participant turn's model may still try a write: it is denied
+    # here, with the header's "This turn may only read" to keep it rare.
+    class ReviewBoundary
+      RULE = "review-boundary"
+      SOURCE = "core"
+      ALLOWED = Toolkit::REVIEW_TOOLS
+      PROJECT_SCOPE = "project"
+
+      # Home folders that hold keys and tokens, never read in a review turn.
+      HOME_SECRET_DIRS = %w[.ssh .gnupg .aws].freeze
+      # Project files that hold secrets, by a path part's name: .env*,
+      # netrc, keys and certificates, anything named credentials, package
+      # registry tokens (.npmrc, .pypirc), ssh keys, terraform state, a
+      # secrets file; and a git config (.git/config, a submodule's
+      # .git/modules/x/config), checked apart.
+      SECRET_FILE = /\A(?:\.env.*|[._]netrc|.*\.(?:pem|key|p12|pfx|tfstate(?:\.backup)?)|.*credentials.*|
+                       \.npmrc|\.pypirc|\.git-credentials|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|secrets?\.(?:ya?ml|json))\z/xi
+      # The .docker/config.json kind: a dot dir's config holding tokens.
+      SECRET_DIR_FILES = { ".docker" => "config.json", ".kube" => "config" }.freeze
+      GIT_DIR = ".git"
+
+      ADVICE = "This is a participant's review turn: answer from what you can read and propose any change as " \
+               "text or a diff for the owner to apply."
+      NOT_IN_KIT = "a participant's review turn may only read (read, memory_read): %s is not allowed"
+      OUTSIDE = "a participant's review turn reads only inside the session's project"
+      SECRET = "a participant's review turn can't read secrets or chi's own files"
+      HOME_ROOT = "a participant's review turn reads only inside a project, and this session's folder is the " \
+                  "home folder or above it"
+      MEMORY_SCOPE = "a participant's review turn reads project memories only: call memory_read with scope: project"
+
+      # @param author [#call] → String, nil: the running turn's author
+      #   (GuardrailWiring#turn_author); the check is off unless it is a
+      #   participant's (Steer.participant_author?)
+      # @param root [#call] → String, nil: the session's project root (the
+      #   work tree top of its folder); nil denies every read
+      # @param denied_dirs [#call] → Array<String>: chi's own dirs (state,
+      #   config: sessions, grants, the web token, memories and .bundles,
+      #   config.yml, hooks)
+      # @param home [#call] → String, nil
+      def initialize(author:, root:, denied_dirs: -> { ReviewBoundary.chi_dirs }, home: -> { Dir.home })
+        @author = author
+        @root = root
+        @denied_dirs = denied_dirs
+        @home = home
+      end
+
+      # chi's state dir and config dir, as Paths has them now.
+      def self.chi_dirs = [Paths.state_dir, File.join(Paths.config_home, Paths::APP_DIR)]
+
+      # Vote on +verdict+ (its call and targets).
+      def check(verdict)
+        return verdict unless Steer.participant_author?(@author.call)
+
+        reason = refusal(verdict)
+        return verdict unless reason
+
+        verdict.deny!(reason, rule: RULE, source: SOURCE, decided_by: "core", advice: ADVICE)
+      end
+
+      private
+
+      def refusal(verdict)
+        call = verdict.call || {}
+        tool = call[:name].to_s
+        return format(NOT_IN_KIT, tool_label(tool, verdict.targets)) unless ALLOWED.include?(tool)
+
+        case tool
+        when "read" then read_refusal(verdict.targets&.paths || [])
+        when "memory_read" then MEMORY_SCOPE unless call[:scope].to_s.strip.downcase == PROJECT_SCOPE
+        end
+      end
+
+      # A plugin or MCP tool behind call_tool names what it acts as.
+      def tool_label(tool, targets)
+        acts_as = targets&.acts_as
+        acts_as && acts_as != tool ? "#{tool} (#{acts_as})" : tool
+      end
+
+      def read_refusal(paths)
+        return OUTSIDE if paths.empty?
+
+        root = @root.call.to_s
+        return OUTSIDE if root.empty?
+
+        real_root = ProtectedPaths.real(root)
+        home = @home.call.to_s
+        return HOME_ROOT if !home.empty? && ShellPaths.within?(ProtectedPaths.real(home), real_root)
+
+        paths.each do |path|
+          given = File.expand_path(path)
+          real = ProtectedPaths.real(given)
+          return OUTSIDE unless ShellPaths.within?(real, real_root)
+          return SECRET if secret?(given, home) || secret?(real, home)
+        end
+        nil
+      end
+
+      def secret?(path, home)
+        dirs = @denied_dirs.call.compact.map { |dir| File.expand_path(dir) }
+        dirs += dirs.map { |dir| ProtectedPaths.real(dir) }
+        dirs += HOME_SECRET_DIRS.map { |dir| File.join(home, dir) } unless home.empty?
+        return true if dirs.any? { |dir| ShellPaths.within?(path, dir) }
+
+        parts = path.split(File::SEPARATOR)
+        return true if parts.any? { |part| SECRET_FILE.match?(part) }
+        return true if parts.each_cons(2).any? { |dir, file| SECRET_DIR_FILES[dir.downcase] == file.downcase }
+
+        git_config?(parts)
+      end
+
+      # A config file anywhere under a .git dir (.git/config,
+      # .git/modules/<sub>/config, a worktree's config.worktree).
+      def git_config?(parts)
+        git = parts.index { |part| part.casecmp?(GIT_DIR) } or return false
+        parts[(git + 1)..].any? { |part| part.downcase.start_with?("config") }
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails.rb

@@ -13,6 +13,7 @@ require_relative "guardrails/approvals"
 require_relative "guardrails/protected_paths"
 require_relative "guardrails/scratch_writes"
 require_relative "guardrails/child_boundary"
+require_relative "guardrails/review_boundary"
 require_relative "guardrails/load_failures"
 require_relative "guardrails/rules"
 require_relative "guardrails/gate"

data/lib/samagotchi/hook_routes.rb

@@ -22,11 +22,13 @@ module Samagotchi
     # @param question_desk     [#call] → QuestionDesk
     # @param cancel_controller [#call] → the running turn's CancellationController, nil
     # @param steer             [#call] (text, source) → steers the running turn
-    def initialize(event_routes:, question_desk:, cancel_controller:, steer:)
+    # @param turn_author       [#call] → the running turn's participant author, nil
+    def initialize(event_routes:, question_desk:, cancel_controller:, steer:, turn_author: -> {})
       @event_routes = event_routes
       @question_desk = question_desk
       @cancel_controller = cancel_controller
       @steer = steer
+      @turn_author = turn_author
       @unknown_fallbacks = Set.new
     end
 
@@ -40,7 +42,8 @@ module Samagotchi
         ask_user: ->(question) { ask_user(question) },
         stop_turn: ->(reason:, hook:) { stop_turn(reason, hook) },
         steer: ->(text:, hook:) { @steer.call(text, source(hook)) },
-        stop_generation: ->(reason:, hook:) { stop_generation(reason, hook) }
+        stop_generation: ->(reason:, hook:) { stop_generation(reason, hook) },
+        turn_author: @turn_author
       )
     end
 

data/lib/samagotchi/hooks/registry.rb

@@ -119,9 +119,12 @@ module Samagotchi
     # cancels the running turn (true when it did); +steer+ takes (text:,
     # hook:) and puts the text into the running turn (Engine#steer, true
     # when queued); +stop_generation+ takes (reason:, hook:) and cuts the
-    # streaming generation while the turn goes on (true when it did). A
-    # registry without one gives hooks no-op helpers.
-    Runtime = Struct.new(:notify, :ask_user, :stop_turn, :steer, :stop_generation, keyword_init: true)
+    # streaming generation while the turn goes on (true when it did);
+    # +turn_author+ returns the running turn's author when a participant
+    # wrote it ("p:<id>"), nil for the owner's (every event of such a turn
+    # carries it as author:). A registry without one gives hooks no-op
+    # helpers.
+    Runtime = Struct.new(:notify, :ask_user, :stop_turn, :steer, :stop_generation, :turn_author, keyword_init: true)
 
     # A thread-safe registry for named hook callbacks.
     #
@@ -386,6 +389,12 @@ module Samagotchi
       def with_runtime(event)
         return unless event.is_a?(Hash)
 
+        # A participant's turn: its events say whose it is (the owner's
+        # carry no author:, as before).
+        if !event.key?(:author) && (author = @runtime&.turn_author&.call)
+          event[:author] = author
+        end
+
         event[:notify] ||= lambda { |text, level: :info, fallback_for: nil|
           notice = { text: text.to_s, level: level, hook: event[:hook] }
           notice[:fallback_for] = fallback_for unless fallback_for.nil?

data/lib/samagotchi/idle_recap.rb

@@ -55,6 +55,8 @@ module Samagotchi
       TOOL_OUTPUT_SEPARATOR = "\n\n---\n\n"
       TOOL_OUTPUT_HEADER_RE = /\A\[([\w.:-]+)\]/
       DELEGATE_REPORT_LINE = "(a delegate session's report, delivered by chi; not the user's words)"
+      # A participant's message (chi share): a reviewer's, not the user's.
+      PARTICIPANT_LINE = "(a review contribution from %s, a participant; not the user's words)"
 
       module_function
 
@@ -75,6 +77,8 @@ module Samagotchi
             # A delegate child's report (ChildReports) is chi's news, not
             # what the user said.
             content = "#{DELEGATE_REPORT_LINE}\n#{content}" if message["source"].to_s == Steer::DELEGATE_REPORT
+            # A participant's is theirs, by the name it was saved with.
+            content = "#{participant_line(message)}\n#{content}" if Steer.participant_message?(message)
             images = ImageRef.placeholder_only?(content) ? [] : image_lines(message["images"])
             [content, *images].reject(&:empty?).join("\n")
           when "model", "assistant"
@@ -97,6 +101,11 @@ module Samagotchi
         end
       end
 
+      def participant_line(message)
+        name = ParticipantName.clean(message["author_name"])
+        format(PARTICIPANT_LINE, name.empty? ? "a participant" : name)
+      end
+
       def image_lines(images)
         Array(images).filter_map { |ref| "[image #{ref["name"] || File.basename(ref["file"].to_s)}]" if ref.is_a?(Hash) }
       end

data/lib/samagotchi/last_turn.rb

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

data/lib/samagotchi/llm/chat_loop.rb

@@ -451,6 +451,7 @@ module Samagotchi
           message[AnswerDisplay::KEY] = entry[AnswerDisplay::KEY] if entry[AnswerDisplay::KEY]
           message[AnswerRefs::KEY] = entry[AnswerRefs::KEY] if entry[AnswerRefs::KEY]
           ContextNote::KEYS.each { |key| message[key] = entry[key] if entry.key?(key) }
+          Steer::AUTHOR_KEYS.each { |key| message[key] = entry[key] if entry[key] }
           message[ToolResponse::LOADED] = entry[ToolResponse::LOADED] if entry[ToolResponse::LOADED].is_a?(Array)
           message[TOOL_CHANGE] = entry[TOOL_CHANGE] if entry[TOOL_CHANGE].is_a?(Hash)
           message

data/lib/samagotchi/parent_report.rb

@@ -33,14 +33,20 @@ module Samagotchi
       end
     end
 
+    # A participant's turn waiting on the session's owner (a question or
+    # approval it raised, the owner's step-limit Continue offer it is held
+    # for): what chi web's participant wait says, and how it reads here.
+    WAITING_FOR_OWNER = "waiting for the session's owner"
+
     module_function
 
     # @param result [ReplyWait::Result]
     # @return [String] answered, question, failed, canceled, limit (the
     #   turn ran out of iterations, nobody asked), not_continued (a Stop
     #   answered the step-limit question), removed (the queued message was
-    #   taken back before it ran), no_answer, error, worker_gone, stopped
-    #   or running
+    #   taken back before it ran), no_answer, error, worker_gone, stopped,
+    #   waiting_for_owner (a participant's turn waits on the owner: chi
+    #   web's participant wait, through --remote) or running
     def status(result)
       case result.status
       when :done then "answered"
@@ -57,6 +63,7 @@ module Samagotchi
       when :error then "error"
       when :worker_gone then "worker_gone"
       when :stopped then "stopped"
+      when :waiting_for_owner then "waiting_for_owner"
       # ReplyWait's own :canceled is the caller giving up (its cancelled:),
       # and :timeout the deadline: the turn goes on either way.
       else "running"
@@ -64,12 +71,13 @@ module Samagotchi
     end
 
     # @return [Integer] 0 answered (or not continued: the Stop asked for
-    #   was carried out), 3 a question waits, 4 still running, 1 anything
+    #   was carried out), 3 a question waits (or, for a participant, the
+    #   owner: waiting_for_owner), 4 still running, 1 anything
     #   else
     def exit_status(result)
       case status(result)
       when "answered", "not_continued" then CLI::Exit::OK
-      when "question" then CLI::Exit::QUESTION
+      when "question", "waiting_for_owner" then CLI::Exit::QUESTION
       when "running" then CLI::Exit::RUNNING
       else CLI::Exit::FAILED
       end
@@ -304,8 +312,12 @@ module Samagotchi
       when :error then "the worker failed: #{result.text}; #{shows} shows what happened"
       when :worker_gone then "the worker is gone; #{shows} shows what happened"
       when :stopped then "the session was stopped (chi sessions stop)"
+      when :waiting_for_owner
+        turn = turn_id || result.turn_id
+        turn.to_s.empty? ? WAITING_FOR_OWNER : "#{WAITING_FOR_OWNER}: #{via.command("send --wait --turn #{turn} #{session_id}")}"
       else
-        wait_again = via.command("send --wait --turn #{turn_id} #{session_id}") unless turn_id.to_s.empty?
+        turn = turn_id || result.turn_id
+        wait_again = via.command("send --wait --turn #{turn} #{session_id}") unless turn.to_s.empty?
         hint = wait_again || shows
         timeout ? "still running after #{format("%g", timeout)} s: #{hint}" : "still running: #{hint}"
       end

data/lib/samagotchi/participant_messages.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The words a participant is refused with, one per condition, wherever
+  # it is met: chi web's routes, the Bridge, the worker, and the
+  # SessionAccess errors a chi --remote client raises for the same codes.
+  # No requires, so any file can use it.
+  module ParticipantMessages
+    # 403 not_permitted: a route, a command or a shell line only the owner may use.
+    NOT_PERMITTED = "a participant can't do that: only the session's owner can"
+    # 429 too_many_turns: their running turn and its queue are full.
+    TOO_MANY_TURNS = "this participant has too many turns waiting: wait for one to finish"
+    # 429 cap_reached: their grant spent its cap.
+    CAP_REACHED = "this participant's spending cap is reached: ask the session's owner to raise it"
+  end
+end

data/lib/samagotchi/participant_name.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A participant's name as chi shows it to anyone, the model included: one
+  # line of at most MAX characters with no brackets (nor Unicode line
+  # breaks, nor full-width square brackets), so a name can't close or forge
+  # the review-contribution header (Steer.review_header). The grants store
+  # cleans a name at issue (Web::Grants.clean_name); the header cleans it
+  # again, whatever a session file or a sidecar holds.
+  module ParticipantName
+    MAX = 64
+    UNSAFE = /[[:cntrl:]\p{Zl}\p{Zp}\[\]［］【】〔〕]/
+
+    module_function
+
+    # @return [String] "" when nothing is left
+    def clean(name)
+      name.to_s.gsub(UNSAFE, " ").squeeze(" ").strip[0, MAX].to_s.strip
+    end
+  end
+end

data/lib/samagotchi/participants.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require "json"
 require "time"
 require_relative "atomic_file"
+require_relative "participant_messages"
 require_relative "archive_store"
 require_relative "session"
 require_relative "web/grants"
@@ -26,11 +27,16 @@ module Samagotchi
   module Participants
     FILE = "participants.json"
     LOG = "participants.jsonl"
+    # What a participant is told when they try what only the owner may do:
+    # a route (chi web's 403 not_permitted), a command or a shell line.
+    NOT_PERMITTED = ParticipantMessages::NOT_PERMITTED
 
     # 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
+    # +expires_at+ says when). +cap+: their spending cap in dollars (the
+    # worker's check before their queued turn starts), nil in a sidecar
+    # from before caps.
+    Entry = Data.define(:id, :kind, :name, :role, :added_at, :expires_at, :removed_at, :cap) do
       def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key.to_s]] })
 
       # Still in the review at +now+.
@@ -65,7 +71,8 @@ module Samagotchi
 
       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 }
+          "added_at" => grant.created_at, "expires_at" => grant.expires_at, "removed_at" => grant.revoked_at,
+          "cap" => grant.spend_cap }
       end
       AtomicFile.write(File.join(dir, FILE), "#{JSON.pretty_generate({ "participants" => entries })}\n", perm: 0o600)
     end
@@ -85,20 +92,36 @@ module Samagotchi
     # @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)
+    def invite(grants, session_id:, name:, kind: "human", ttl: nil, cap: 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)
+      issued = grants.issue(session_id: session_id, name: name, kind: kind, ttl: ttl, cap: cap)
       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)
+                               role: grant.role, expires_at: grant.expires_at, cap: grant.spend_cap)
       issued
     end
 
+    # Sets participant +id+'s cap on +session_id+ (chi share cap): the
+    # grant, the sidecar (the worker's check) and the audit line.
+    # @return [Web::Grants::Grant, nil] nil when +id+ isn't an active grant there
+    # @raise [Web::Grants::Invalid] a cap out of range
+    def set_cap(grants, session_id:, id:, cap:, state_dir: Session.default_state_dir)
+      grant = grants.set_cap(id, cap, session_id: session_id) or return nil
+
+      write(session_id, grants.list(session_id: session_id), state_dir: state_dir)
+      log(session_id, :cap, state_dir: state_dir, participant: grant.id, cap: grant.spend_cap)
+      grant
+    end
+
+    # The refusal for a cap change of +id+, no active participant of
+    # +session_id+.
+    def no_participant(id, session_id) = "no active participant #{id} in #{session_id.to_s[0, 8]} (chi share ls lists them)"
+
     # 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

data/lib/samagotchi/participants_watch.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # Loaded only when a sidecar is read: it brings Web::Grants (and Rack).
+  autoload :Participants, File.expand_path("participants", __dir__)
+
+  # Who is in a session's review now, and who came or went since the last
+  # look: participants.json (Participants.read) read again when its mtime
+  # moves, each entry's expiry measured at every look. The worker asks
+  # #changes on its idle tick and announces :participants_changed; the
+  # Bridge's join snapshot asks #active (any thread). A session nobody was
+  # invited to has no sidecar: one stat per look. Joined means invited (an
+  # active grant the last look didn't have), left means revoked or expired:
+  # participants have no presence of their own yet. See
+  # docs/internals/participants.md (The owner's terminal).
+  class ParticipantsWatch
+    # Participants::FILE, without loading Participants for a stat.
+    FILE = "participants.json"
+
+    # What changed: the active participants now, the ones that joined, and
+    # the ones that left (each with +reason+ "revoked" or "expired").
+    Change = Data.define(:participants, :joined, :left) do
+      def to_event = { type: :participants_changed, participants: participants, joined: joined, left: left }
+    end
+
+    # @param session_id [#call] → the session's id (nil before it has one)
+    # @param state_dir [#call] → the sessions' state dir
+    # @param clock [#call] → Time
+    def initialize(session_id:, state_dir:, clock: -> { Time.now })
+      @session_id = session_id
+      @state_dir = state_dir
+      @clock = clock
+      @mutex = Mutex.new
+      @stamp = nil
+      @entries = []
+      @known = nil
+    end
+
+    # The participants in the review now: [{id:, name:, kind:}], [] for none.
+    # @return [Array<Hash>]
+    def active
+      @mutex.synchronize { active_rows(read_entries) }
+    end
+
+    # The change since the last call, nil when none. The first call only
+    # takes the state as it is (a worker's start announces nobody).
+    # @return [Change, nil]
+    def changes
+      @mutex.synchronize do
+        entries = read_entries
+        rows = active_rows(entries)
+        known = @known
+        @known = rows.to_h { |row| [row[:id], row] }
+        next nil if known.nil?
+
+        joined = rows.reject { |row| known.key?(row[:id]) }
+        left = known.values.reject { |row| @known.key?(row[:id]) }.map do |row|
+          entry = entries.find { |e| e.id == row[:id] }
+          row.merge(reason: entry&.removed_at ? "revoked" : "expired")
+        end
+        next nil if joined.empty? && left.empty?
+
+        Change.new(participants: rows, joined: joined, left: left)
+      end
+    end
+
+    private
+
+    def active_rows(entries)
+      now = @clock.call
+      entries.select { |entry| entry.active?(now) }.map { |entry| { id: entry.id, name: entry.name, kind: entry.kind } }
+    end
+
+    # The sidecar's entries, read again only when its mtime moved.
+    def read_entries
+      id = @session_id.call
+      return @entries = [] if id.to_s.empty?
+
+      file = File.join(Session.session_dir(id, state_dir: @state_dir.call), FILE)
+      stamp = [id, File.mtime(file)]
+      return @entries if stamp == @stamp
+
+      @stamp = stamp
+      @entries = Participants.read(id, state_dir: @state_dir.call)
+    rescue SystemCallError
+      @stamp = nil
+      @entries = []
+    end
+  end
+end

data/lib/samagotchi/plugin/context.rb

@@ -61,7 +61,7 @@ module Samagotchi
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
-                      :cancel_controller, :cost, :usage, keyword_init: true)
+                      :cancel_controller, :cost, :usage, :turn_author, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -175,6 +175,12 @@ module Samagotchi
       #   with no session
       def usage = @host.usage&.call || SessionMetrics::Usage.zero
 
+      # @return [String, nil] who wrote the running turn when it isn't the
+      #   session's owner: a participant's "p:<id>" (chi share); nil for the
+      #   owner's turns and between turns. A handler runs with the owner's
+      #   power whatever the author (docs/hooks.md).
+      def turn_author = @host.turn_author&.call
+
       # @return [String, nil] the name of the session's toolkit ("full" for
       #   one from before toolkits; nil with no session)
       def toolkit = @host.toolkit&.call

data/lib/samagotchi/plugin/side_question.rb

@@ -42,13 +42,21 @@ module Samagotchi
           line = IdleRecap::TranscriptFilter.build([message])
           next if line.strip.empty?
 
-          "#{message["role"] == "user" ? "User" : "Assistant"}: #{line}"
+          "#{speaker(message)}: #{line}"
         end.join("\n\n")
         return text if text.length <= MAX_TRANSCRIPT_CHARS
 
         "[earlier conversation left out]\n\n#{text[-MAX_TRANSCRIPT_CHARS..]}"
       end
 
+      # Who a paragraph is: a participant's message is a Participant's (the
+      # filter's line names them), any other user message the User's.
+      def speaker(message)
+        return "Assistant" unless message["role"] == "user"
+
+        Steer.participant_message?(message) ? "Participant" : "User"
+      end
+
       # String keys, as TranscriptFilter reads a saved session.
       def stringified(messages)
         JSON.parse(JSON.generate(Array(messages)))

data/lib/samagotchi/queued_command.rb

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