samagotchi 0.106.0 → 0.108.0

data/lib/samagotchi/bundles/work-cap/plugin.rb

@@ -63,6 +63,7 @@ class Plugin
     @resolved = nil        # {session:, settings:, meters: {meter => {cap:, step:, key:}}, unreadable: {name => value}}
     @warned = {}           # meter => [session id, cap] the share warning was given for
     @unread_warned = nil   # the session id the "isn't a number" notice was given for
+    @corrupt_warned = nil  # the session id the "state file doesn't read" notice was given for
   end
 
   def register(chi)
@@ -126,6 +127,7 @@ class Plugin
   def check(ctx)
     resolved = resolve(ctx)
     unreadable(ctx, resolved)
+    corrupt(ctx, resolved)
     capped = resolved[:meters].select { |_meter, meter_cap| meter_cap[:cap] }
     return if capped.empty?
 
@@ -161,11 +163,26 @@ class Plugin
     return if bad.empty? || !first_time?(:@unread_warned, resolved[:session])
 
     named = bad.map { |key, value| "#{key}: #{value.inspect}" }.join(" and ")
+    ctx.notify("work-cap: #{named} #{bad.size == 1 ? "isn't" : "aren't"} a number or off; #{using(resolved)}",
+               level: :warn)
+  end
+
+  # Once per session: a state file that is there but doesn't read (not
+  # JSON, or not a mapping) holds no /workcap caps, so the settings' are
+  # used; said rather than a /workcap cap silently gone.
+  def corrupt(ctx, resolved)
+    path = resolved[:corrupt]
+    return unless path && first_time?(:@corrupt_warned, resolved[:session])
+
+    ctx.notify("work-cap: #{path} doesn't read, its /workcap caps are ignored; #{using(resolved)}", level: :warn)
+  end
+
+  # "using tool_calls: (400), minutes: (60)", or "no cap".
+  def using(resolved)
     used = resolved[:meters].values.filter_map do |meter_cap|
       "#{meter_cap[:key]}: (#{count(meter_cap[:cap])})" if meter_cap[:cap]
     end
-    using = used.empty? ? "no cap" : "using #{used.join(", ")}"
-    ctx.notify("work-cap: #{named} #{bad.size == 1 ? "isn't" : "aren't"} a number or off; #{using}", level: :warn)
+    used.empty? ? "no cap" : "using #{used.join(", ")}"
   end
 
   def at_cap(ctx, resolved, reached, usage, used)
@@ -280,29 +297,37 @@ class Plugin
     cached = @mutex.synchronize { @resolved }
     return cached if cached && cached[:session] == session && cached[:settings] == settings
 
-    saved = state(ctx, session)
+    saved, corrupt = state(ctx, session)
     configured = configured(ctx)
     meters = METERS.to_h { |meter| [meter, saved[meter] || configured[:meters][meter]] }
-    resolved = { session: session, settings: settings, meters: meters, unreadable: configured[:unreadable] }
+    resolved = { session: session, settings: settings, meters: meters, unreadable: configured[:unreadable],
+                 corrupt: corrupt }
     @mutex.synchronize { @resolved = resolved }
   end
 
-  # The state file's meters ({meter => {cap:, step:}}), {} without one.
+  # The state file's meters ({meter => {cap:, step:}}), {} without one,
+  # and the file's path when it is there but doesn't read (logged; the
+  # user is told by #corrupt), else nil.
   def state(ctx, session)
-    return {} unless session
+    return [{}, nil] unless session
 
-    saved = JSON.parse(File.read(state_path(ctx, session)))
-    return {} unless saved.is_a?(Hash)
+    path = state_path(ctx, session)
+    saved = JSON.parse(File.read(path))
+    raise JSON::ParserError, "not a JSON object" unless saved.is_a?(Hash)
 
-    METERS.each_with_object({}) do |meter, meters|
+    meters = METERS.each_with_object({}) do |meter, found|
       entry = saved[meter]
       next unless entry.is_a?(Hash) && entry.key?("cap")
 
       cap = self.class.amount(entry["cap"], meter)
-      meters[meter] = { cap: cap, step: self.class.amount(entry["step"], meter) || cap, key: "/workcap" }
+      found[meter] = { cap: cap, step: self.class.amount(entry["step"], meter) || cap, key: "/workcap" }
     end
-  rescue Errno::ENOENT, JSON::ParserError
-    {}
+    [meters, nil]
+  rescue Errno::ENOENT
+    [{}, nil]
+  rescue JSON::ParserError => e
+    ctx.log.warn(:workcap_state_unreadable, path: path, error: e.message.to_s[0, 200])
+    [{}, path]
   end
 
   # Per meter the first of its own value, child:'s (a delegate's) and
@@ -358,21 +383,32 @@ class Plugin
   end
 
   # Write one meter's cap into the session's state file (the other kept).
+  # One there that doesn't read (#state) is written over: logged and said,
+  # never a silent replace.
   def save_meter(ctx, session, meter, data)
     path = state_path(ctx, session)
     FileUtils.mkdir_p(File.dirname(path))
     saved = begin
       JSON.parse(File.read(path))
-    rescue Errno::ENOENT, JSON::ParserError
+    rescue Errno::ENOENT
       {}
+    rescue JSON::ParserError
+      nil
     end
-    saved = {} unless saved.is_a?(Hash)
+    replacing = !saved.is_a?(Hash)
+    saved = {} if replacing
     saved[meter] = data.transform_values { |value| whole(value) }
     Samagotchi::AtomicFile.write(path, "#{JSON.generate(saved)}\n")
+    replaced(ctx, path) if replacing
     # Resolved again at the next use, from the file now holding the meter.
     @mutex.synchronize { @resolved = nil }
   end
 
+  def replaced(ctx, path)
+    ctx.log.warn(:workcap_state_replaced, path: path)
+    ctx.notify("work-cap: #{path} didn't read; replaced with the new cap", level: :warn)
+  end
+
   # 800.0 as 800 (a whole cap is saved as an Integer), 2.5 as it is.
   def whole(value) = value.is_a?(Float) && value.finite? && value == value.to_i ? value.to_i : value
 

data/lib/samagotchi/child_reports.rb

@@ -7,6 +7,7 @@ require_relative "session"
 require_relative "session_inbox"
 require_relative "reply_wait"
 require_relative "steer"
+require_relative "turn_origin"
 require_relative "log"
 require_relative "config"
 require_relative "tools/delegate_wait"
@@ -138,7 +139,7 @@ module Samagotchi
       def initialize(relay: nil, **) = super
 
       def line(mark: nil) = Steer::Line.new(text: text, source: ChildReports::SOURCE, mark: mark)
-      def origin = { client_id: "#{ClientId::CHILD_PREFIX}#{child_id[0, 8]}" }
+      def origin = TurnOrigin.new(client_id: "#{ClientId::CHILD_PREFIX}#{child_id[0, 8]}")
     end
 
     # @param predecessor [String, nil] the link this session continues

data/lib/samagotchi/cli/parent_wait.rb

@@ -96,7 +96,7 @@ module Samagotchi
           @stdout.flush
           @reported = true
         end
-        error_line("#{command_name}: still running: #{@access.invocation.shows(id)}")
+        error_line("#{command_name}: still running: #{ParentReport.still_running_hint(id, report_turn_id, via: @access.invocation)}")
         Exit::INTERRUPTED
       rescue ArgumentError
         error_line("#{command_name}: the session is gone (deleted while waiting)")

data/lib/samagotchi/context_sources.rb

@@ -359,12 +359,7 @@ module Samagotchi
     def project_location_for(project_root, state_dir: nil)
       return nil if project_root.to_s.empty?
 
-      project_location(project_key_of(project_root), state_dir: state_dir)
-    end
-
-    # MemoryPaths.project_key for a root already resolved.
-    def project_key_of(root)
-      "#{File.basename(root)}_#{Digest::MD5.hexdigest(root)[0..7]}"
+      project_location(MemoryPaths.key_for_root(project_root), state_dir: state_dir)
     end
 
     # A session's sources: its own, then the project's it doesn't shadow

data/lib/samagotchi/continue_offer.rb

@@ -4,6 +4,7 @@ require "time"
 require_relative "last_turn"
 require_relative "log"
 require_relative "steer"
+require_relative "turn_origin"
 
 module Samagotchi
   # A session worker's continue offer: what it announces when a turn runs out
@@ -35,10 +36,13 @@ module Samagotchi
     # @param max_iterations [#call] (no_interrupt) → Integer
     # @param queue_command [#call] (line, client_id:) queues a session
     #   command as a card's (Bridge#queue_command, card: true)
-    # +participant_refused+ (author → Boolean): whether a participant's
-    # turn may no longer run (revoked, expired, at the cap: Worker's check).
-    def initialize(engine:, turn_flow:, run_turn:, max_iterations:, queue_command: nil, participant_refused: ->(_) { false })
+    # +participant_refused+ (author → reason or nil): why a participant's
+    # turn may no longer run ("revoked", "cap_reached": Worker's check).
+    # @param save [#call] saves the session (a refused Continue's Stop)
+    def initialize(engine:, turn_flow:, run_turn:, max_iterations:, queue_command: nil, participant_refused: ->(_) {},
+                   save: -> {})
       @engine = engine
+      @save = save
       @turn_flow = turn_flow
       @run_turn = run_turn
       @max_iterations = max_iterations
@@ -68,6 +72,7 @@ module Samagotchi
 
     # A prompt (or a reminder turn) taken while a continue is offered
     # replaces the answer (D2): the offer goes, the partial turn stays.
+    # @param origin [TurnOrigin] the taken turn's
     def drop(origin)
       return unless awaiting?
 
@@ -75,7 +80,7 @@ module Samagotchi
       close("dropped")
       @engine.synchronize_events do
         @turn_flow.drop_offer!
-        @engine.announce(type: :continue_resolved, decision: "dropped", client_id: origin&.dig(:client_id))
+        @engine.announce(type: :continue_resolved, decision: "dropped", client_id: origin.client_id)
       end
       @engine.record_activity
     end
@@ -91,7 +96,14 @@ module Samagotchi
     # it ends (chi answer --option Stop).
     # It carries the offer turn's enqueued_id, so a wait on that turn
     # (ReplyWait's turn:) ends on it too.
+    # A Continue on the offer of a participant who may no longer run a turn
+    # (revoked, expired, at the cap since) is decided here, before anything
+    # says "resume": it ends the offer as a Stop does (#refuse_continue).
     def announce_resolved(result, command)
+      if result.resume && (reason = refusal_of_offer_author)
+        return refuse_continue(reason, command)
+      end
+
       @engine.announce(type: :continue_resolved, decision: result.decision.to_s, client_id: command.client_id)
       return if result.resume
 
@@ -133,12 +145,18 @@ module Samagotchi
     # review boundary and on their spend (never as the owner's). One whose
     # participant may no longer run a turn isn't continued.
     def run_continue_turn(command)
+      # Refused as it was answered (#announce_resolved): the offer is gone.
+      return @continue_steer = nil unless awaiting?
+
       offer = @turn_flow.offer
       resume_from = @turn_flow.resume_from
       enqueued_id = offer_turn_id
-      author = Steer.sender_author(@engine.session&.last_turn&.author)
+      author = @engine.session&.last_turn&.participant_author
       close("answered")
-      return if author && @participant_refused.call(author)
+      if author && (reason = @participant_refused.call(author))
+        @continue_steer = nil
+        return @engine.synchronize_events { refuse_continue(reason, command) }
+      end
 
       steer = @continue_steer
       @continue_steer = nil
@@ -150,7 +168,7 @@ module Samagotchi
           Log.warn(:worker, "turn_not_begun", continue: true, error: e.class.name, msg: e.message)
           return announce_offer(offer)
         end
-        origin = { client_id: command.client_id, enqueued_id: enqueued_id, author: author }.compact
+        origin = TurnOrigin.new(client_id: command.client_id, enqueued_id: enqueued_id, author: author)
         @run_turn.call(nil, continue: true, origin: origin, resumed: true, resume_from: resume_from,
                             max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
           if error
@@ -175,6 +193,37 @@ module Samagotchi
 
     private
 
+    def refusal_of_offer_author
+      author = @engine.session&.last_turn&.participant_author
+      author && @participant_refused.call(author)
+    end
+
+    # The offer of a participant refused since (+reason+: revoked,
+    # cap_reached) ends as a Stop: announced as "refused" (with a notice
+    # for the owner), the model reads it wasn't continued, last_turn says
+    # not_continued with the offer turn's enqueued_id (a wait on it ends),
+    # and awaiting_continue? goes false (idle exit, /exit, the held
+    # participant turns go on). The question goes with the next close.
+    # Called with the event log held.
+    def refuse_continue(reason, command)
+      author = @engine.session&.last_turn&.participant_author
+      enqueued_id = offer_turn_id
+      @engine.announce(type: :continue_resolved, decision: "refused", reason: reason.to_s, client_id: command.client_id)
+      @engine.announce(type: :hook_notice, hook: "participants", level: :warn, between_turns: true,
+                       text: format(REFUSED_NOTICE, who: Steer.participant_id(author), reason: REFUSED_WHY.fetch(reason.to_s, reason.to_s)))
+      @turn_flow.abort_continue!
+      session = @engine.session
+      session.last_turn = LastTurn.new(outcome: NOT_CONTINUED, ended_at: Time.now.iso8601(3), enqueued_id: enqueued_id) if session
+      @continue_steer = nil
+      close("answered")
+      @save.call
+      nil
+    end
+
+    REFUSED_NOTICE = "Not continued: participant %<who>s's turn %<reason>s."
+    REFUSED_WHY = { "revoked" => "is refused (their link was revoked or expired)",
+                    "cap_reached" => "is refused (they reached their review cap)" }.freeze
+
     # The enqueued_id of the turn the offer stands for: the exhausted
     # turn's last_turn (a canceled continue turn's carries the same id);
     # nil when it ran no input (a reminder turn, a delegate's first).

data/lib/samagotchi/engine.rb

@@ -13,6 +13,7 @@ require_relative "context_note"
 require_relative "context_status"
 require_relative "steer"
 require_relative "turn_note"
+require_relative "turn_origin"
 require_relative "model_profile"
 require_relative "effective_model"
 require_relative "session_setting"
@@ -57,6 +58,7 @@ require_relative "hook_routes"
 require_relative "guardrails"
 require_relative "reminder_store"
 require_relative "reminder_queue"
+require_relative "memory_orphans"
 require_relative "tools/memory"
 require_relative "muted_memories"
 require_relative "used_memories"
@@ -623,7 +625,7 @@ module Samagotchi
     def side_author(kind)
       return nil unless turn_running? || kind.to_s == RECAP_SIDE_KIND
 
-      Steer.sender_author(@guardrail_wiring.turn_author)
+      @guardrail_wiring.turn_author
     end
 
     RECAP_SIDE_KIND = "recap"
@@ -631,7 +633,7 @@ module Samagotchi
     # The running turn's author when a participant wrote it, else nil
     # (ctx.turn_author, the hooks' author).
     # @return [String, nil]
-    def turn_author = turn_running? ? Steer.sender_author(@guardrail_wiring.turn_author) : nil
+    def turn_author = turn_running? ? @guardrail_wiring.turn_author : nil
 
     # @return [SessionMetrics] the per-session analytics collector
     attr_reader :metrics
@@ -984,7 +986,8 @@ module Samagotchi
 
     # Announce what failed to load and what plugins showed while loading,
     # once, as soon as the owner can show it (the worker's Bridge is up, the
-    # REPL renders events): the guardrail and plugin warnings, then the
+    # REPL renders events): the guardrail and plugin warnings, an orphaned
+    # project memory folder (label: "memory", MemoryOrphans), then the
     # held notices (between_turns) and cards (in_turn: false, so late
     # joiners get them). Without this call the first turn announces them
     # (#announce_guardrail_failures).
@@ -997,6 +1000,8 @@ module Samagotchi
         announce({ type: :guardrail_warning, message: message }) if message
         plugins = @plugin_failures.message
         announce({ type: :guardrail_warning, message: plugins, label: "plugins" }) if plugins
+        memory = MemoryOrphans.message
+        announce({ type: :guardrail_warning, message: memory, label: "memory" }) if memory
         @extension_load.held_events.each do |event|
           announce(event[:type] == :card ? event.merge(in_turn: false) : event.merge(between_turns: true))
         end
@@ -1448,8 +1453,8 @@ module Samagotchi
 
     # Once per Engine, on its first turn: what failed to load, so every UI
     # (REPL, attached TUI, web) shows it: the guardrails, then the plugins
-    # (label: "plugins"; the UIs say guardrails without one), then the
-    # notices and cards plugins showed as they loaded.
+    # (label: "plugins"; the UIs say guardrails without one), an orphaned
+    # project memory folder (label: "memory"), then the notices and cards plugins showed as they loaded.
     def announce_guardrail_failures(on_event)
       return if @guardrail_failures_announced
 
@@ -1458,6 +1463,8 @@ module Samagotchi
       emit_event(on_event, { type: :guardrail_warning, message: message }) if message
       plugins = @plugin_failures.message
       emit_event(on_event, { type: :guardrail_warning, message: plugins, label: "plugins" }) if plugins
+      memory = MemoryOrphans.message
+      emit_event(on_event, { type: :guardrail_warning, message: memory, label: "memory" }) if memory
       @extension_load.held_events.each { |event| emit_event(on_event, event) }
     end
     private :announce_guardrail_failures
@@ -1494,14 +1501,14 @@ module Samagotchi
     # @param limit [Integer, nil] the turn ran out of iterations at this
     #   limit: "exhausted" => true, "limit" => N, so a wait with nobody to
     #   answer the continue offer says so (ReplyWait, ParentReport "limit")
+    # @param origin [TurnOrigin] the turn's (TurnOrigin::NONE for no sender)
     # @param event [Hash] the turn's end event (#stop_facts)
     def record_last_turn(session, outcome, seconds, origin, event, limit: nil)
-      source = ClientId.origin(origin.is_a?(Hash) ? origin[:client_id] : nil)
-      enqueued_id = origin.is_a?(Hash) ? origin[:enqueued_id] : nil
+      enqueued_id = origin.enqueued_id
       session.last_turn = LastTurn.new(outcome: outcome, ended_at: Time.now.iso8601(3), seconds: seconds.round(1),
-                                       origin: source, exhausted: limit ? true : nil, limit: limit,
+                                       origin: origin.source, exhausted: limit ? true : nil, limit: limit,
                                        enqueued_id: enqueued_id.to_s.empty? ? nil : enqueued_id.to_s,
-                                       author: Steer.sender_author(origin.is_a?(Hash) ? origin[:author] : nil),
+                                       author: origin.participant_author,
                                        **stop_facts(event))
     end
 
@@ -1532,10 +1539,9 @@ module Samagotchi
     # author:, and author_name: from participants.json), {} for the owner.
     # The worker's drain names a participant's merged lines with it, and
     # its running save a participant's prompt.
-    # @param origin [Hash, String, nil] a turn's origin, or an author
+    # @param author [String, nil] a turn's or a line's author (TurnOrigin#author)
     # @param session [Session, nil] the session it is for (the turn's)
-    def author_fields(origin, session: @session)
-      author = origin.is_a?(Hash) ? origin[:author] : origin
+    def author_fields(author, session: @session)
       return {} unless Steer.participant_author?(author)
 
       Steer.author_fields(author, @participants.name_for(author, session: session))
@@ -1995,9 +2001,11 @@ module Samagotchi
                       :settings, :id, :limit, :resumed, :resume_from) do
       def resumed? = resumed ? true : false
 
-      # The turn's boundary events carry the origin only when there is one,
-      # so payloads stay unchanged for callers that don't pass it.
-      def tag(event) = origin ? event.merge(origin: origin) : event
+      # The turn's boundary events carry the origin only when it names a
+      # sender (not TurnOrigin::NONE), so payloads stay unchanged for callers
+      # that don't pass one; as its wire Hash (TurnOrigin#to_h), which the
+      # Bridge and the UIs read.
+      def tag(event) = origin.empty? ? event : event.merge(origin: origin.to_h)
 
       # Seconds since the turn started (the cancel note says how long it ran).
       def elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
@@ -2032,11 +2040,13 @@ 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:},
-    #   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 origin [TurnOrigin, 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; none for the owner; a Hash is read as
+    #   one, TurnOrigin.of; TurnOrigin::NONE, the default, names no sender
+    #   and so does nil or {}); when it names one, the turn's boundary events
+    #   (:turn_started, :turn_completed, :turn_canceled, :turn_failed) carry
+    #   it as `origin:` (its wire Hash), 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
@@ -2056,8 +2066,8 @@ module Samagotchi
     # other error (e.g. an LLM::ProviderError) emits :turn_failed and
     # re-raises; a provider error adds error_kind:, retryable:, host: and a
     # one-line summary:.
-    def run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
-                 images: [], id: nil, resumed: false, resume_from: nil)
+    def run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false,
+                 origin: TurnOrigin::NONE, images: [], id: nil, resumed: false, resume_from: nil)
       turn = begin_turn(session, prompt, on_event: on_event, cancel_controller: cancel_controller, origin: origin,
                                          continue: continue, id: id)
       if continue
@@ -2108,6 +2118,7 @@ module Samagotchi
     # the turn flag, its cancel controller and sink. The cross-thread state
     # is set here and cleared in #release_turn only.
     def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id: nil)
+      origin = TurnOrigin.of(origin)
       # Track the active session for recap and status snapshot.
       @session = session
       # status is turn state: running now, idle again before the turn's end
@@ -2151,7 +2162,7 @@ module Samagotchi
       turn_started[:cut_after] = steer_cut_after
       # A participant's turn names them (author, author_name) for the UIs'
       # badge; the owner's turn_started stays as it was.
-      turn_started.merge!(author_fields(turn.origin, session: session))
+      turn_started.merge!(author_fields(turn.origin.author, session: session))
       emit_event(turn.on_event, turn.tag(turn_started))
       raise image_error if image_error
 
@@ -2305,7 +2316,7 @@ module Samagotchi
       # system prompt invalidates cache for the entire prefix.
       # Not into a participant's turn: the owner's reminders are the owner's,
       # and would be used up there under the review boundary.
-      due_reminders = Steer.participant_author?(turn.origin&.dig(:author)) ? [] : @reminder_queue.inject!(turn.messages)
+      due_reminders = turn.origin.participant? ? [] : @reminder_queue.inject!(turn.messages)
       if due_reminders.any?
         emit_event(turn.on_event, {
           type: :reminder_injected,
@@ -2314,7 +2325,7 @@ module Samagotchi
       end
 
       unless turn.continue
-        user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin) }
+        user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author) }
         user_message[:images] = image_refs unless image_refs.empty?
         turn.messages << user_message
         session.last_prompt = turn.prompt

data/lib/samagotchi/guardrail_wiring.rb

@@ -11,6 +11,7 @@ require_relative "version"
 require_relative "hooks"
 require_relative "edit_preview"
 require_relative "tool_activity"
+require_relative "turn_origin"
 
 module Samagotchi
   # An Engine's tool guardrails: who can approve (the interface), the YAML
@@ -55,6 +56,7 @@ module Samagotchi
       @failures = Guardrails::LoadFailures.new
       @rules_mutex = Mutex.new
       @git = Guardrails::GitInfo.new
+      @origin = TurnOrigin::NONE
     end
 
     # Who can answer an approval: :repl, :worker or :non_interactive (the
@@ -83,17 +85,18 @@ module Samagotchi
       @protected = nil
     end
 
-    # A turn starts: its origin (Engine#run_turn's: {client_id:,
-    # enqueued_id:, author:}, each optional), and the git facts read afresh.
+    # A turn starts: its origin (Engine#run_turn's TurnOrigin; nil or a
+    # Hash is read as one, TurnOrigin.of), and the git facts read afresh.
     def begin_turn(origin)
-      @origin = origin
+      @origin = TurnOrigin.of(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.
+    # origin's participant author); nil for the owner's turns and every
+    # other origin.
     # @return [String, nil]
-    def turn_author = @origin.is_a?(Hash) ? @origin[:author] : nil
+    def turn_author = @origin.participant_author
 
     # The gate every tool call asks first.
     # @return [Guardrails::Gate]
@@ -229,7 +232,7 @@ module Samagotchi
     # @return [Guardrails::Context]
     def context
       Guardrails::Context.new(cwd: Dir.pwd, session_id: @session_lookup.call&.id, interface: interface,
-                              origin: @origin, git: @git)
+                              origin: @origin.wire, git: @git)
     end
 
     # Ask the user to approve a call the gate voted `ask` on, through the

data/lib/samagotchi/guardrails/review_boundary.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "protected_paths"
-require_relative "shell_paths"
-require_relative "../paths"
+require_relative "review_paths"
 require_relative "../toolkit"
 require_relative "../steer"
 
@@ -18,7 +16,7 @@ module Samagotchi
     # (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
+    #   read: ReviewPaths: only under the session's project root, 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);
@@ -35,19 +33,6 @@ module Samagotchi
       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"
@@ -55,6 +40,7 @@ module Samagotchi
       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"
+      READ_REFUSALS = { ReviewPaths::OUTSIDE => OUTSIDE, ReviewPaths::SECRET => SECRET, ReviewPaths::HOME_ROOT => HOME_ROOT }.freeze
       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
@@ -66,16 +52,13 @@ module Samagotchi
       #   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 })
+      def initialize(author:, root:, denied_dirs: -> { ReviewPaths.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)
@@ -106,42 +89,8 @@ module Samagotchi
       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") }
+        paths_check = ReviewPaths.new(root: @root.call, denied_dirs: @denied_dirs.call, home: @home.call)
+        READ_REFUSALS[paths_check.refusal(paths)]
       end
     end
   end