samagotchi 0.156.0 → 0.157.0

data/lib/samagotchi/bridge/turn_drawings.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require_relative "../log"
+require_relative "../message_time"
+require_relative "../steer"
+
+module Samagotchi
+  class Bridge
+    # A finished turn as live drew it (its drawing), one JSON line per turn in
+    # the session's folder (FILE), so a reload or a reconnect draws the turn
+    # the way the live page did: the TurnAccumulator's final fold of the turn
+    # (its parts in order: steps, rows, notices, steers, merged lines,
+    # reminders, in-turn cards) and the end event's display keys (END_KEYS).
+    # Display-side only: no request, message, strategy, recap, --resume or
+    # continue reads it.
+    #
+    # A line names the turn's own messages by the range the Engine put on
+    # the end event (`kept_from`/`kept_to`: the turn's messages are
+    # `kept[from...to]`) and digests both ends (#digest). It holds while the
+    # messages still reach `to` and both ends digest the same: a rollback, a
+    # rolled-back failure or a prompt handed back drops it. Of two valid
+    # lines that overlap (a rollback, then a re-run that said the same at the
+    # same boundaries), and of several for one turn id, the newest wins
+    # (.valid). A turn with no range (an older worker, a turn that kept
+    # nothing) or an empty one writes no line, and draws as before.
+    #
+    # Written by the accumulator's on_turn_end hook (#append), inside the
+    # SessionObserver's delivery: the line is on disk before any stream gets
+    # the end frame. That departs from SessionObserver's "enqueue-only" note,
+    # as CardStore's save does: one append per turn end.
+    class TurnDrawings
+      FILE = "turn_drawings.jsonl"
+      # In the sidecar's features (Bridge::FEATURES): this worker's CardStore
+      # lists an in-turn entry's of_turn, which a page drawing the turn needs
+      # to leave that entry to the drawing. chi web draws no drawings for a
+      # live worker without it (an older one: its rows would show twice).
+      FEATURE = "turn_drawings"
+      # A show draws at most this many turns from their drawings, the newest
+      # (the payload and the page's offscreen render stay bounded in a long
+      # session); older turns draw as before, from their messages.
+      SHOWN_MAX = 100
+      VERSION = 1
+      # The end event's keys the page draws a finished turn's end from (not
+      # the answer: its text, html and refs stay the message's; not the range:
+      # the line's from/to).
+      END_KEYS = %i[type turn_id duration_ms revises verify cancellation_reason cancelled_by summary message error_class
+                    kept_steps].freeze
+      # What a line keeps of the accumulator's turn.
+      DRAWING_KEYS = (%i[prompt turn_id origin continue at images parts] + Steer::AUTHOR_KEYS).uniq.freeze
+      KINDS = { "turn_completed" => "completed", "turn_canceled" => "canceled", "turn_failed" => "failed" }.freeze
+
+      # One line of the file (string-keyed drawing and end, as JSON has them).
+      Line = Data.define(:v, :turn_id, :kind, :from, :to, :from_digest, :to_digest, :drawing, :end) do
+        # @return [Line, nil] nil for a line this chi can't draw (another
+        #   version, a missing field)
+        def self.from_h(raw)
+          return nil unless raw.is_a?(Hash) && raw["v"] == VERSION
+          return nil unless raw["turn_id"].is_a?(String) && !raw["turn_id"].empty?
+          return nil unless raw["from"].is_a?(Integer) && raw["to"].is_a?(Integer) && raw["from"] < raw["to"] && raw["from"] >= 0
+          return nil unless raw["from_digest"].is_a?(String) && raw["to_digest"].is_a?(String)
+          return nil unless raw["drawing"].is_a?(Hash) && raw["end"].is_a?(Hash)
+
+          new(v: raw["v"], turn_id: raw["turn_id"], kind: raw["kind"].to_s, from: raw["from"], to: raw["to"],
+              from_digest: raw["from_digest"], to_digest: raw["to_digest"], drawing: raw["drawing"], end: raw["end"])
+        end
+
+        def to_h = super.transform_keys(&:to_s)
+
+        def range = (from...to)
+      end
+
+      # @param path [String, nil] the file (nil: nothing is written)
+      # @param messages [#call] the session's messages now (the Engine's,
+      #   as CardStore's): the end step replaced them before the end event, so
+      #   they hold the turn's range when #append runs
+      def initialize(path:, messages:)
+        @path = path
+        @messages = messages
+        @last = path ? self.class.tail_line(path) : nil
+      end
+
+      # The newest line this store wrote or started from (P3's snapshot).
+      # @return [Line, nil]
+      attr_reader :last
+
+      # The accumulator's hook: the turn's line, when its end event names a
+      # range. Never raises (a turn that can't be drawn still ended).
+      # @param turn [Hash] the accumulator's final fold (symbol keys)
+      # @param end_event [Hash] the end event
+      def append(turn, end_event)
+        line = line_for(turn, end_event)
+        return unless line
+
+        write(line)
+        @last = line
+      rescue StandardError => e
+        Log.warn(:bridge, "turn_drawing_failed", error: "#{e.class}: #{e.message}")
+      end
+
+      def line_for(turn, end_event)
+        from = end_event[:kept_from]
+        to = end_event[:kept_to]
+        return nil unless @path && turn && from.is_a?(Integer) && to.is_a?(Integer) && from < to && from >= 0
+
+        messages = @messages.call || []
+        return nil if messages.size < to
+
+        id = end_event[:turn_id] || turn[:turn_id]
+        return nil unless id
+
+        Line.new(v: VERSION, turn_id: id.to_s, kind: KINDS[end_event[:type].to_s] || end_event[:type].to_s, from: from, to: to,
+                 from_digest: self.class.digest(messages[from]), to_digest: self.class.digest(messages[to - 1]),
+                 drawing: JSON.parse(JSON.generate(scrubbed(turn.slice(*DRAWING_KEYS)))),
+                 end: JSON.parse(JSON.generate(scrubbed(self.class.end_of(end_event)))))
+      end
+      private :line_for
+
+      # Newline-first: a torn last line (a crash mid-write) ends before this
+      # one starts, so both parse apart; then one write.
+      def write(line)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.open(@path, File::RDWR | File::CREAT | File::APPEND, 0o600) do |file|
+          size = file.size
+          torn = size.positive? && (file.pread(1, size - 1) != "\n")
+          file.write("#{"\n" if torn}#{JSON.generate(line.to_h)}\n")
+        end
+      end
+      private :write
+
+      def scrubbed(value) = self.class.scrub(value)
+      private :scrubbed
+
+      class << self
+        # The end event's display keys (END_KEYS), with an empty answer's
+        # notice from its summary.
+        # @return [Hash]
+        def end_of(event)
+          out = event.slice(*END_KEYS).compact
+          out[:type] = out[:type].to_s if out[:type]
+          empty = event.dig(:turn_summary, :empty_answer)
+          out[:turn_summary] = { empty_answer: empty } if empty
+          out
+        end
+
+        # A message's digest in one form for the live (symbol keys, raw
+        # strings) and the saved (string keys, scrubbed as Session#to_h does)
+        # messages: role, content and time, each read from either key.
+        # @return [String]
+        def digest(message)
+          return "" unless message.is_a?(Hash)
+
+          role = fetch(message, :role)
+          time = fetch(message, MessageTime::KEY)
+          Digest::SHA1.hexdigest(JSON.generate(scrub([role&.to_s, fetch(message, :content), time&.to_s])))
+        end
+
+        # Every String in +value+ as Session#to_h saves it (UTF-8, invalid
+        # bytes as "?"); symbol keys stay symbols (JSON writes them alike).
+        def scrub(value)
+          case value
+          when String
+            text = value.encoding == Encoding::UTF_8 ? value : value.dup.force_encoding(Encoding::UTF_8)
+            text.valid_encoding? ? text : text.scrub("?")
+          when Array then value.map { |item| scrub(item) }
+          when Hash then value.to_h { |key, item| [key, scrub(item)] }
+          when Symbol then value.to_s
+          else value
+          end
+        end
+
+        # The session folder's lines, oldest first (unreadable, torn and
+        # unknown lines skipped), cached by the file's path, size and mtime
+        # (chi web reads it on each full show).
+        # @return [Array<Line>]
+        def read(session_dir)
+          path = File.join(session_dir, FILE)
+          stat = File.stat(path)
+          key = [stat.size, stat.mtime.to_r]
+          cached = cache_mutex.synchronize { cache[path] }
+          return cached[1] if cached && cached[0] == key
+
+          lines = parse(File.binread(path))
+          cache_mutex.synchronize do
+            cache.shift while cache.size >= CACHE_SIZE
+            cache[path] = [key, lines]
+          end
+          lines
+        rescue SystemCallError, IOError
+          []
+        end
+
+        # @return [Array<Line>]
+        def parse(text)
+          text.dup.force_encoding(Encoding::UTF_8).scrub("?").each_line.filter_map do |raw|
+            Line.from_h(JSON.parse(raw))
+          rescue JSON::ParserError
+            nil
+          end
+        end
+
+        # The lines that hold against +messages+ (Session messages, symbol
+        # or string keys): each one's range still in them with both ends the
+        # same; of overlapping ranges and of one turn's lines the newest
+        # (last in the file) wins. Ordered by their range.
+        # @return [Array<Line>]
+        def valid(lines, messages)
+          messages = Array(messages)
+          kept = []
+          lines.reverse_each do |line|
+            next unless holds?(line, messages)
+            next if kept.any? { |other| other.turn_id == line.turn_id || overlap?(other, line) }
+
+            kept << line
+          end
+          kept.sort_by(&:from)
+        end
+
+        # The last parseable line of +path+, or nil.
+        # @return [Line, nil]
+        def tail_line(path)
+          return nil unless File.file?(path)
+
+          File.open(path, "rb") do |file|
+            size = file.size
+            chunk = file.pread([size, TAIL_BYTES].min, [size - TAIL_BYTES, 0].max)
+            parse(chunk.to_s).last
+          end
+        rescue SystemCallError, IOError
+          nil
+        end
+
+        # Whether +line+ is small enough to send in a snapshot: within what
+        # #tail_line reads back after a restart (TAIL_BYTES), so a join draws
+        # a turn the same before and after one (a bigger line: rebuilt).
+        def sendable?(line) = JSON.generate(line.to_h).bytesize <= TAIL_BYTES
+
+        def holds?(line, messages)
+          messages.size >= line.to && digest(messages[line.from]) == line.from_digest &&
+            digest(messages[line.to - 1]) == line.to_digest
+        end
+
+        def overlap?(one, other) = one.from < other.to && other.from < one.to
+
+        private
+
+        def fetch(message, key)
+          message.key?(key) ? message[key] : message[key.to_s]
+        end
+
+        def cache = (@cache ||= {})
+        def cache_mutex = (@cache_mutex ||= Mutex.new)
+      end
+
+      # Sessions whose parsed file chi web keeps (a long one's is tens of MB
+      # of objects; the mtime moves at every turn end anyway).
+      CACHE_SIZE = 8
+      # Read from the end at start (#last): a drawing is a few KB, its outputs cut.
+      TAIL_BYTES = 1024 * 1024
+      private_constant :CACHE_SIZE, :TAIL_BYTES
+    end
+  end
+end

data/lib/samagotchi/bridge.rb

@@ -21,6 +21,7 @@ require_relative "bridge/pending_card"
 require_relative "bridge/ring_buffer"
 require_relative "bridge/sse_writer"
 require_relative "bridge/turn_accumulator"
+require_relative "bridge/turn_drawings"
 require_relative "session"
 require_relative "engine"
 require_relative "system_one/log"
@@ -134,7 +135,10 @@ module Samagotchi
       @bind = bind
       @port = port
       @ring = RingBuffer.new(capacity: ring_capacity)
-      @accumulator = TurnAccumulator.new
+      # A finished turn's drawing (TurnDrawings), written by the accumulator
+      # at the end event, before any stream gets it.
+      @drawings = TurnDrawings.new(path: File.join(session_dir, TurnDrawings::FILE), messages: -> { @engine.session&.messages })
+      @accumulator = TurnAccumulator.new(on_turn_end: @drawings.method(:append))
       # Saved in the session's folder: a later worker, and the web without
       # one, show the cards where they were.
       @cards = CardStore.new(path: File.join(session_dir, CardStore::FILE), messages: -> { @engine.session&.messages })
@@ -300,7 +304,7 @@ module Samagotchi
     # the event log: the Engine's messages (not the lagging copy on disk),
     # the turn in progress, turns queued behind it, the idle recap since the
     # last turn, the recap saved with the session (also from before the last
-    # turns: {text:, covered:, turns_since:, created_at:}), a pending continue offer, the guardrail and plugin load warnings,
+    # turns: {text:, covered:, turns_since:, opening_id:, created_at:}), a pending continue offer, the guardrail and plugin load warnings,
     # the plugins' init tasks still running (Engine#init_tasks), the
     # last cards and between-turns notices (CardStore#list), the session's commands (Commands::Registry#listing:
     # what an attached TUI routes and completes, the web's autocomplete), and the event_seq it all covers.
@@ -315,13 +319,20 @@ module Samagotchi
     # working_set: the running turn's last :working_set_updated ({items:,
     # at:}, TurnAccumulator#working_set), which the messages lag; nil
     # between turns and before the turn emitted one.
+    # last_turn_drawing: the last exchange's turn as live drew it
+    # ({drawing:, end:}, TurnDrawings#last, not unfolded: an attaching TUI
+    # unfolds it, TurnAccumulator.replay_events), only while it holds against
+    # these messages and ends at their end; absent otherwise (a rollback, a
+    # later Continue or note, an older worker's file).
     # @return [Hash] {messages:, current_turn:, working_set:, queued:, queued_commands:, recap:, saved_recap:, continue_offer:, pending_question:,
-    #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, chi_version:, event_seq:, event_id:}
+    #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, chi_version:, event_seq:, event_id:, last_turn_drawing:}
     def snapshot
       @engine.synchronize_events do
         seq = @engine.event_count
+        messages = @engine.messages_checkpoint
+        drawing = last_turn_drawing(messages)
         {
-          messages: @engine.messages_checkpoint,
+          messages: messages,
           current_turn: current_turn_with_generation,
           working_set: @accumulator.working_set,
           queued: @accumulator.queued,
@@ -338,10 +349,24 @@ module Samagotchi
           chi_version: Samagotchi::VERSION,
           event_seq: seq,
           event_id: event_id(seq)
-        }
+        }.merge(drawing ? { last_turn_drawing: drawing } : {})
       end
     end
 
+    # The newest drawing (TurnDrawings#last) as the snapshot sends it, when
+    # it is the last exchange's: its range still holds against +messages+
+    # and ends at their end, and is no bigger than a restart reads back
+    # (TurnDrawings.sendable?). nil otherwise.
+    # @return [Hash, nil] {drawing:, end:} (string keys inside, as the file)
+    def last_turn_drawing(messages)
+      line = @drawings.last
+      return nil unless line && line.to == messages.size && TurnDrawings.holds?(line, messages)
+      return nil unless TurnDrawings.sendable?(line)
+
+      { drawing: line.drawing, end: line.end }
+    end
+    private :last_turn_drawing
+
     # The snapshot and the session state (status, pending question, ...) as
     # one step of the event log, both as of the same event_seq: what a
     # snapshot or reset frame (SSEWriter) and GET snapshot carry.
@@ -664,7 +689,7 @@ module Samagotchi
     # review turn, and chi web says so (Delivery::PAIR_FEATURE).
     FEATURES = ["restart", "task_stop", "reparent", Delivery::QUEUE_FEATURE, ReplyWait::TURN_IDS_FEATURE,
                 VerifyAnchor::FEATURE, ReviseAnchor::FEATURE,
-                SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE, Delivery::PAIR_FEATURE].freeze
+                SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE, Delivery::PAIR_FEATURE, TurnDrawings::FEATURE].freeze
 
     # The routes, by method and what follows /session/:id/: a handler takes
     # the session id and the request body and returns [headers, status, body].

data/lib/samagotchi/broadcast/recipients.rb

@@ -29,12 +29,12 @@ module Samagotchi
       # @return [Array<Recipient>] newest first
       def list(state_dir:, active_hours:, include_tests: Session.test_session_env?, now: Time.now)
         cutoff = now - (active_hours.to_f * 3600)
-        SessionManager.session_summaries(include_tests: include_tests, state_dir: state_dir).filter_map do |row|
-          next if row[:delegate] || row[:scratch]
-          next unless row[:live] || row[:owner] == "tui" || active_since?(row, cutoff, state_dir)
+        SessionManager.session_rows(include_tests: include_tests, state_dir: state_dir).filter_map do |row|
+          next if row.delegate || row.scratch
+          next unless row.live || row.owner == "tui" || active_since?(row, cutoff, state_dir)
 
-          Recipient.new(id: row[:id], short_id: row[:short_id], project: row[:project], cwd: row[:cwd],
-                        desc: row[:desc], live: row[:live], owner: row[:owner])
+          Recipient.new(id: row.id, short_id: row.short_id, project: row.project, cwd: row.cwd,
+                        desc: row.desc, live: row.live, owner: row.owner)
         end
       end
 
@@ -43,11 +43,11 @@ module Samagotchi
       # session with no turn recorded; it is never older than the last
       # turn's end, so an older one rules the session out unread.
       def active_since?(row, cutoff, state_dir)
-        return false unless (time(row[:updated_at]) || Time.at(0)) >= cutoff
+        return false unless (time(row.updated_at) || Time.at(0)) >= cutoff
 
-        session = Session.summary_from_file(Session.session_file(row[:id], state_dir: state_dir))
+        session = Session.summary_from_file(Session.session_file(row.id, state_dir: state_dir))
         ended = time(session&.last_turn&.ended_at)
-        (ended || time(row[:updated_at])) >= cutoff
+        (ended || time(row.updated_at)) >= cutoff
       end
       private_class_method :active_since?
 

data/lib/samagotchi/broadcast/triage_model.rb

@@ -29,7 +29,7 @@ module Samagotchi
       # @param get [#call] a Config key → its value
       # @return [Choice]
       def resolve(host_registry: nil, get: ->(key) { Config.get(key) })
-        registry = host_registry || HostRegistry.new
+        registry = host_registry || HostRegistry.current
         SETTINGS.each do |model, host_ref, base_url|
           target = IdleTarget.resolve(model: get.call(model), host_ref: get.call(host_ref), base_url: get.call(base_url),
                                       host_registry: registry)

data/lib/samagotchi/bundle_command/check.rb

@@ -91,6 +91,7 @@ module Samagotchi
           check_settings(manifest) unless @installed
           check_install(manifest) unless missing || placeholders? || manifest.session_settings_clash
           check_api(manifest)
+          check_fail_closed(manifest) unless @installed
           check_boundary(manifest)
           check_tests unless @installed
         end
@@ -439,6 +440,23 @@ module Samagotchi
         end
       end
 
+      # A chi.on(..., on_error: :fail_closed) guard denies the call it raises
+      # on; only the manifest's plugin: required: true makes its failing to
+      # load deny every call (chi knows it before the plugin registers).
+      FAIL_CLOSED = /on_error:\s*(?::fail_closed\b|["']fail_closed["'])/
+
+      def check_fail_closed(manifest)
+        file = manifest.plugin && manifest.plugin[:file]
+        return if !file || manifest.plugin[:required] || !File.file?(path(file))
+
+        source = File.read(path(file))
+        return unless (index = source =~ FAIL_CLOSED)
+
+        add(:warn, :"fail-closed", file, "a fail-closed chi.on hook, but the manifest's plugin: has no required: true: " \
+                                         "if the plugin fails to load, tool calls still run",
+            line: source[0, index].count("\n") + 1, fix: "add required: true under plugin: in manifest.yml")
+      end
+
       def check_boundary(manifest)
         require_relative "../testing/boundary"
         known = shipped? ? Testing::Boundary::EXCEPTIONS.fetch(manifest.name, {}) : {}

data/lib/samagotchi/bundle_command/try/sandbox.rb

@@ -186,7 +186,7 @@ module Samagotchi
         end
 
         def leftover_workers
-          sessions = File.join(state_home, Session::STATE_SUBDIR)
+          sessions = File.join(state_home, SessionPaths::STATE_SUBDIR)
           Dir.glob(File.join(sessions, "*", OwnerLock::FILE)).filter_map do |lock|
             pid = OwnerLock.owner(File.dirname(lock))&.pid
             pid if ProcessGroup.leader?(pid)

data/lib/samagotchi/bundle_command/try/trace.rb

@@ -28,7 +28,7 @@ module Samagotchi
         def read(exit_code:, answer:, stderr:, sandbox:, timed_out: false)
           return empty_trace(exit_code, answer, stderr, sandbox, timed_out) unless @session_id
 
-          sessions_dir = File.join(@state_home, Session::STATE_SUBDIR)
+          sessions_dir = File.join(@state_home, SessionPaths::STATE_SUBDIR)
           session_dir = Session.session_dir(@session_id, state_dir: sessions_dir)
           session = json_file(Session.session_file(@session_id, state_dir: sessions_dir)) || {}
           messages = Array(session["messages"]).select { |message| message.is_a?(Hash) }

data/lib/samagotchi/bundle_command.rb

@@ -639,9 +639,12 @@ module Samagotchi
       0
     end
 
+    # The base and the file; a marked one also the bundle's text it stays
+    # behind (its source-less FileState says which).
     def diff_memory(prov, target_dir, key)
-      print_base_and_current(key, prov.base_path(key), File.join(target_dir, key))
-      print_incoming(prov, key)
+      state = Samagotchi::MemoryBundle::FileState.of(key, record: prov.record, provenance: prov, target_dir: target_dir, source_dir: nil)
+      print_base_and_current(key, state.paths[:base], state.paths[:current])
+      print_incoming(prov, key) if state.marked?
     end
 
     # The bundle's text a file stays behind (Provenance#incoming_path), so the

data/lib/samagotchi/bundles/known-names/manifest.yml

@@ -1,17 +1,14 @@
 ---
 name: known-names
-version: 0.1.9
+version: 0.2.0
 requires_chi: ">= 0.150.0"
 scope: system
 description: Catches a near-miss of a protected name (home folder, login, git name, repo name, names from config) in a tool call and rejects it with the right spelling; mode ask / correct optional
 trust_level: reviewed
 files:
   known_names.md: sha256:d5348b95b6c655017b541910b36e384220da280818160201f6ec9a50e1e4287c
-hooks:
-  known_names.rb:
-    sha256: sha256:d7eed0dd0f418d8099a147ed124c6e6062b8c752035dd6b5aa5e926e29941c8b
-    event: before_tool_call
-    on_error: log
-    priority: 50
+plugin:
+  file: plugin.rb
+  sha256: sha256:d140612e6c34a9d2d205bf818a2a0797ad1e133829481f354aaa9e56698017e3
 # config.yml bundles: known-names: (another key warns; an older chi ignores this)
 settings: [names, ignore, mode, derive, min_length, max_distance]

data/lib/samagotchi/bundles/known-names/{hooks/known_names.rb → plugin.rb}

@@ -243,3 +243,20 @@ class KnownNames
     Array(value).map { |name| name.to_s.strip }.reject(&:empty?)
   end
 end
+
+# What chi loads: one KnownNames, built once from config.yml
+# `bundles: known-names:` when the plugin loads, on before_tool_call at
+# priority 50. A raise in the handler is logged and the call goes on
+# (chi.on's log policy); KnownNames#call turns its own errors into a
+# notice first.
+class Plugin
+  PRIORITY = 50
+
+  def initialize(settings = {})
+    @names = KnownNames.new(settings)
+  end
+
+  def register(chi)
+    chi.on(:before_tool_call, priority: PRIORITY) { |event, _ctx| @names.call(event) }
+  end
+end

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,17 +1,14 @@
 ---
 name: source-links
-version: 0.6.3
+version: 0.7.0
 scope: system
 description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, refs in a waiting question's reply, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
 requires_chi: ">= 0.150.0"
 files:
   source_links.md: sha256:ace01a0f7c308a0ae54ece714c31c0e6d7a49c372d98111030e6d268320bed3a
-hooks:
-  source_links.rb:
-    sha256: sha256:21d7a9f7c381c653b126b625feed0e0b6422eaa84c8dfe716b6c5b41644a33b3
-    events: [after_turn, question_asked]
-    on_error: log
-    priority: 90
+plugin:
+  file: plugin.rb
+  sha256: sha256:b4a777d8b6135f80e248dd21b5370c91dfcf2aea17057734e77241eb9cc4afe4
 # config.yml bundles: source-links: (another key warns; an older chi ignores this)
 settings: [sources, max, note]

data/lib/samagotchi/bundles/source-links/{hooks/source_links.rb → plugin.rb}

@@ -59,10 +59,10 @@ require "samagotchi/ref"
 # action, "Open in <name>", the ref's URL. A URL that isn't http(s) stays a
 # markdown link only. The web's ref menu shows the action.
 #
-# The hook is on :question_asked too (the manifest's events:, chi newer than
-# 0.97.0): while a question of the model's (or an approval of its call)
-# waits, the refs in the reply that asks it, and in the question's text and
-# options, are refs on that reply, the same as an answer's. The web pairs
+# The hook is on :question_asked too (Plugin below hooks both events): while
+# a question of the model's (or an approval of its call) waits, the refs in
+# the reply that asks it, and in the question's text and options, are refs
+# on that reply, the same as an answer's. The web pairs
 # them in the stage's asking slot, on the question's card and on that step
 # in the history (a ref only in the question's text pairs there alone). No
 # links in the text and no note line for it: the turn's end has those.
@@ -657,3 +657,22 @@ class SourceLinks
     value.to_s.gsub(/[^A-Za-z0-9\-._~]/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join }
   end
 end
+
+# What chi loads: one SourceLinks, built once from config.yml
+# `bundles: source-links:` when the plugin loads, on after_turn and
+# question_asked at priority 90 (its state, the remotes it asked git for,
+# is shared). A raise in the handler is logged and the turn goes on
+# (chi.on's log policy).
+class Plugin
+  PRIORITY = 90
+
+  def initialize(settings = {})
+    @links = SourceLinks.new(settings)
+  end
+
+  def register(chi)
+    %i[after_turn question_asked].each do |event|
+      chi.on(event, priority: PRIORITY) { |payload, _ctx| @links.call(payload) }
+    end
+  end
+end

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.156.0
+version: 0.157.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:709bd52710bf6c50334a89a10742ea1554c5985cc2d7c4e7571e526cc4479526
   config_modification_protocol.md: sha256:25ed2d4901f00eeea226db5eb2b75a05d6cdee4015ac8daa4bed624f745c3922
-  memory_guide.md: sha256:8b7727b939b9c04486ca59859561023dcc319a73e0f5b47b3fcf5741edaa69e2
+  memory_guide.md: sha256:fe4dbb25ce4c9f9b51507a6130fa7bf992a2cc41af2453830eacd27c09a65d1e
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -114,7 +114,7 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 | Command | Purpose |
 |---------|---------|
 | `install <source> [--scope system\|project] [--force]` | Install from dir/zip/tar.gz/git URL. `--force` overwrites existing entries, otherwise skips them; a skipped file stays the user's (not recorded, never upgraded or removed by the bundle). It also installs a bundle whose `requires_chi` this chi doesn't meet: without `--force` that install is refused (`NAME can't be installed: it requires chi …`). Writes provenance to `.bundles/<name>/` (base snapshots + `manifest.json`) and updates `index.md`. Warns on double-brace placeholders and checksum mismatches (strict mode). |
-| `upgrade <source\|name> [--force] [--dry-run] [--agent]` | A bare `name` is an installed bundle: chi upgrades it from the source its record keeps (its git URL with the `#ref` it recorded, its folder, or the archive it came from) — a dev install is refused, and a record whose source is gone says so and asks for the path or URL. Otherwise 3-way merge upgrade (base vs current vs incoming) per `Merger::Upgrade#outcome` (`Merger.classify`, then a text merge where both sides changed): `install` (new file), `noop` (current==incoming), `fast_forward` (current==base, not edited → auto-update), `keep` (incoming==base → preserve local edits), `merged` (both edited, a text merge with `git` comes out clean → the file takes it, the old one goes to the bundle trash, and entries both sides added under a `Changelog` heading are kept), `conflict` (both edited, a real conflict, or no `git` or base → the file stays untouched and marked, reported as `X stays behind 0.8.0: …` with why and what it missed, needs a retry, `--force`, which copies it to the trash first, or interactive `memory_write` resolution). A marked file is retried at the same version: the system bundle's at each chi start and on `chi update`, another shipped bundle's on `chi update`, any other bundle's on `chi bundle upgrade`. A file marked by an older chi merges normally when its recorded base is a version chi shipped (an installed samagotchi gem still has it); otherwise it merges only if the bundle takes out or rewords no line it still holds, and if it does, it stays behind until resolved by hand, with `--agent` or with `--force`, and the retry can't fix that. Pruned files (removed from new bundle) are kept if locally edited, otherwise warned. |
+| `upgrade <source\|name> [--force] [--dry-run] [--agent]` | A bare `name` is an installed bundle: chi upgrades it from the source its record keeps (its git URL with the `#ref` it recorded, its folder, or the archive it came from) — a dev install is refused, and a record whose source is gone says so and asks for the path or URL. Otherwise 3-way merge upgrade (base vs current vs incoming) per `Merger::Upgrade#decision` (the file's `FileState` and its `FileActions` row, then a text merge where both sides changed): `install` (new file), `noop` (current==incoming), `fast_forward` (current==base, not edited → auto-update), `keep` (incoming==base → preserve local edits), `merged` (both edited, a text merge with `git` comes out clean → the file takes it, the old one goes to the bundle trash, and entries both sides added under a `Changelog` heading are kept), `conflict` (both edited, a real conflict, or no `git` or base → the file stays untouched and marked, reported as `X stays behind 0.8.0: …` with why and what it missed, needs a retry, `--force`, which copies it to the trash first, or interactive `memory_write` resolution). A marked file is retried at the same version: the system bundle's at each chi start and on `chi update`, another shipped bundle's on `chi update`, any other bundle's on `chi bundle upgrade`. A file marked by an older chi merges normally when its recorded base is a version chi shipped (an installed samagotchi gem still has it); otherwise it merges only if the bundle takes out or rewords no line it still holds, and if it does, it stays behind until resolved by hand, with `--agent` or with `--force`, and the retry can't fix that. Pruned files (removed from new bundle) are kept if locally edited, otherwise warned. |
 | `uninstall <bundle> [--force]` | Moves the bundle's memory files to `.bundles/.trash/<bundle>-<time>/` (refuses locally edited ones unless `--force`; keeps a file another installed bundle also lists), removes their `index.md` lines, deletes the provenance dir. |
 | `status [<bundle>]` | Provenance + per-file `ok|modified|missing|unreadable|no-index` vs stored checksum and base snapshot, and what stays behind or merged at a chi start; `issues=` counts files behind, missing or unreadable, not edits; a model overlay (`<name>.<key>.md`) has no index line and reads `ok (model overlay)`. |
 | `diff <bundle> [file]` | Prints `base` (provenance snapshot) vs `current` (on-disk) for each file. |

data/lib/samagotchi/child_move.rb

@@ -60,23 +60,23 @@ module Samagotchi
       move = []
       refuse = []
       SessionManager.children_of(prev_id, state_dir: state_dir).each do |row|
-        subtree = [row[:id], *SessionManager.descendant_ids(row[:id], state_dir)]
+        subtree = [row.id, *SessionManager.descendant_ids(row.id, state_dir)]
         next if (subtree & open_ids).empty?
 
-        if row[:archived]
+        if row.archived
           # An open delegate below an archived one: the archive's cascade
           # would take it, the move doesn't (only unarchived ones move).
           refuse.concat(open.select { |c| subtree.include?(c.id) }.map do |c|
-            c.with(why: "under archived #{row[:id][0, 8]}; unarchive that one or archive this one")
+            c.with(why: "under archived #{row.short_id}; unarchive that one or archive this one")
           end)
           next
         end
 
-        why = unmovable(row[:id], state_dir: state_dir)
+        why = unmovable(row.id, state_dir: state_dir)
         if why
-          refuse << SessionContinue::OpenChild.new(id: row[:id], short_id: row[:id][0, 8], why: why)
+          refuse << SessionContinue::OpenChild.new(id: row.id, short_id: row.short_id, why: why)
         else
-          move << row[:id]
+          move << row.id
         end
       end
       Plan.new(move: move, refuse: refuse)

data/lib/samagotchi/child_reports.rb

@@ -335,8 +335,8 @@ module Samagotchi
       before = kept ? kept.after : current
       # A follow-up's turn (DelegateCursor#turn) is reported by its own
       # reply, as delegate_result takes it, not a newer queued turn's.
-      wait = ReplyWait.call(child_id, state_dir: @state_dir, cursor: before.reply_file, baseline: before.baseline,
-                                      timeout: 0, turn: before.turn)
+      wait = ReplyWait.call(child_id, state_dir: @state_dir, **ReplyWait::Target.from_cursor(before, child: child).to_h,
+                                      timeout: 0)
       return nil unless reportable?(wait)
 
       claim_id = before.report_claim&.id || SecureRandom.hex(16)