samagotchi 0.156.0 → 0.158.0

data/lib/samagotchi/bridge/turn_drawings.rb

@@ -0,0 +1,271 @@
+# 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, parts that aren't rows: .rows?)
+        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)
+          return nil unless TurnDrawings.rows?(raw["drawing"]["parts"])
+
+          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
+        # Whether a drawing's +parts+ are rows TurnAccumulator.replay_events
+        # can unfold: none, or a list of Hashes (a hand-edited line's may be
+        # anything, and the unfold would raise).
+        def rows?(parts) = parts.nil? || (parts.is_a?(Array) && parts.all?(Hash))
+
+        # 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

@@ -21,7 +21,7 @@ module Samagotchi
     #
     # It installs and loads the bundle in a Testing::Sandbox (temp HOME and
     # XDG dirs), not in the user's config or state, but in this process: the
-    # plugin's and hooks' own code runs as written; --fix rewrites stale
+    # plugin's own code runs as written; --fix rewrites stale
     # sha256 lines (MemoryBundle::Shas). #run returns 0 without errors, 1
     # with any.
     #
@@ -34,8 +34,8 @@ module Samagotchi
 
           Check the bundle at PATH (default: .) as an install would take it, one finding per line:
             error|warn|info CODE file[:line]: message (fix: hint)
-          It installs and loads the bundle in a sandbox (temp HOME, config and state), not in yours, but its plugin and
-          hooks run in this process as written: run it on code you'd install.
+          It installs and loads the bundle in a sandbox (temp HOME, config and state), not in yours, but its plugin
+          runs in this process as written: run it on code you'd install.
           --fix            rewrite stale and placeholder sha256 lines in manifest.yml
           --set KEY=VALUE  a setting for the load (config.yml bundles: <name>: KEY), repeatable
           Exit status: 0 no errors, 1 errors, 2 usage.
@@ -81,6 +81,7 @@ module Samagotchi
       # @return [Integer] exit status
       def run
         manifest = read_manifest
+        manifest = nil if manifest && hooks_retired?
         if manifest
           missing = check_files(manifest)
           check_source_tree(manifest, missing) unless @installed
@@ -91,6 +92,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
@@ -135,12 +137,27 @@ module Samagotchi
         Dir.mktmpdir("chi-bundle-check-") do |tmp|
           File.write(File.join(tmp, "manifest.yml"), MemoryBundle::Shas.parseable(@text))
           MemoryBundle::Manifest.read(dir: tmp)
+        rescue MemoryBundle::Manifest::HooksRetired => e
+          add(:error, :"hooks-retired", "manifest.yml", e.message, line: manifest_line("hooks"), fix: hooks_fix)
+          nil
         rescue MemoryBundle::Manifest::ValidationError => e
           add(:error, :manifest, "manifest.yml", e.message.gsub(tmp, display(@dir)))
           nil
         end
       end
 
+      # A source with hooks/*.rb (listed or not) can't be installed: the run
+      # stops there, as after a manifest error (Installer#refuse_hooks).
+      def hooks_retired?
+        files = MemoryBundle::Manifest::HooksRetired.files_in(@dir)
+        return false if files.empty?
+
+        add(:error, :"hooks-retired", "hooks/", MemoryBundle::Manifest::HooksRetired.for_files(files).message, fix: hooks_fix)
+        true
+      end
+
+      def hooks_fix = "hook the events from plugin.rb with chi.on, then remove hooks/ and the manifest's hooks:"
+
       # The line of manifest.yml naming +file+ (its entry), or nil.
       def manifest_line(file)
         base = File.basename(file)
@@ -191,7 +208,7 @@ module Samagotchi
       # @return [Boolean] whether a listed file is missing
       def check_files(manifest)
         listed = manifest.files.keys + Array(manifest.plugin && manifest.plugin[:file]) +
-                 manifest.hooks.keys.map { |h| File.join("hooks", h) } + manifest.scripts.keys.map { |s| File.join("scripts", s) }
+                 manifest.scripts.keys.map { |s| File.join("scripts", s) }
         missing = listed.reject { |rel| File.file?(path(rel)) }
         missing.each do |rel|
           add(:error, :"missing-file", "manifest.yml", "lists #{rel}, which isn't in the bundle", line: manifest_line(rel),
@@ -201,7 +218,7 @@ module Samagotchi
       end
 
       # What an install leaves out: a memory files: doesn't list (by
-      # MemoryFiles' rules), a plugin, hook or script the manifest doesn't name.
+      # MemoryFiles' rules), a plugin or script the manifest doesn't name.
       def check_unlisted(manifest)
         memories = MemoryBundle::MemoryFiles.select(@dir, manifest)
         loose = Dir.glob(path("*.md")).map { |f| File.basename(f) }.sort.reject do |name|
@@ -210,9 +227,6 @@ module Samagotchi
         loose.each { |name| unlisted(name, "files:") }
         plugin = manifest.plugin && manifest.plugin[:file]
         unlisted("plugin.rb", "plugin:") if File.file?(path("plugin.rb")) && plugin != "plugin.rb"
-        Dir.glob(path("hooks/*.rb")).sort.each do |file|
-          unlisted("hooks/#{File.basename(file)}", "hooks:") unless manifest.hooks.key?(File.basename(file))
-        end
         Dir.glob(path("scripts/*")).sort.each do |file|
           unlisted("scripts/#{File.basename(file)}", "scripts:") unless manifest.scripts.key?(File.basename(file))
         end
@@ -250,7 +264,7 @@ module Samagotchi
 
       # ── requires_chi ──────────────────────────────────────────────────
 
-      def code?(manifest) = manifest.plugin || manifest.hooks.any? || manifest.scripts.any?
+      def code?(manifest) = manifest.plugin || manifest.scripts.any?
 
       def check_requires_chi(manifest)
         line = manifest_line("requires_chi")
@@ -413,7 +427,7 @@ module Samagotchi
         registered.tools.each { |name| add(:info, :registered, plugin, "tool #{name}") }
         registered.hooks.each do |event, hooks|
           hooks.each do |hook|
-            file = manifest.hooks.key?(hook.hook) ? "hooks/#{hook.hook}" : plugin
+            file = plugin
             next add(:info, :registered, file, "hook #{event} (priority #{hook.priority})") if Hooks::EVENTS.include?(event)
 
             add(:warn, :"hook-event", file, "hook on #{event.inspect}, which chi never fires",
@@ -439,6 +453,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/installed_check.rb

@@ -59,8 +59,9 @@ module Samagotchi
 
       # What the child sends: an edited file, which the copy's own shas can't
       # tell, a manifest key that doesn't parse (the copy holds the mirror's
-      # value or none: InstalledManifest#key_problems), and Check's warnings
-      # and errors, naming the installed bundle's folder rather than the copy's.
+      # value or none: InstalledManifest#key_problems), the class-file hooks
+      # the record still has (they don't load), and Check's warnings and
+      # errors, naming the installed bundle's folder rather than the copy's.
       def answer_of(bundle)
         edited = MemoryBundle::ShippedUpdate.edited_executables(bundle.name, bundle).map do |file|
           Check::Finding.new(level: :warn, code: :edited, file: file, line: nil, fix: "chi bundle upgrade #{bundle.name}, or reinstall it",
@@ -69,6 +70,7 @@ module Samagotchi
         edited += bundle.manifest.key_problems.values.map do |message|
           Check::Finding.new(level: :error, code: :manifest, file: "manifest.yml", line: nil, message: message, fix: nil)
         end
+        edited << retired_hooks(bundle) unless bundle.hooks.empty?
         edited = edited.map { |finding| { level: finding.level, text: finding.to_s } }
         installed_dir = MemoryBundle::Provenance.new(name: bundle.name).bundle_dir
         edited + MemoryBundle::InstalledCopy.with(bundle) do |dir|
@@ -80,6 +82,15 @@ module Samagotchi
       end
       private_class_method :answer_of
 
+      # A 0.157 record's class-file hooks: they no longer load, and only an
+      # upgrade from a source that has moved them (or an uninstall) clears it.
+      def retired_hooks(bundle)
+        Check::Finding.new(level: :warn, code: :"hooks-retired", file: "hooks/", line: nil,
+                           message: MemoryBundle::Manifest::HooksRetired::WORDS,
+                           fix: "chi bundle upgrade #{bundle.name} once its source hooks from plugin.rb, or chi bundle uninstall #{bundle.name}")
+      end
+      private_class_method :retired_hooks
+
       def died(why, prefix: true) = Found.new(level: "error", text: check_line(prefix ? "the check died: #{why}" : why))
       private_class_method :died
 

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

@@ -163,7 +163,10 @@ module Samagotchi
             reader.join(0.1) if reader.alive?
             reader.kill if reader.alive?
           end
-          readers.map { |reader| reader.value.to_s }
+          # readpartial gives raw bytes: the child writes UTF-8 (the answer,
+          # the trace), so each stream is read as that, a bad byte as "?",
+          # here once, for the text and the --json report alike.
+          readers.map { |reader| reader.value.to_s.dup.force_encoding(Encoding::UTF_8).scrub("?") }
         end
 
         def close_streams(streams)

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) }