samagotchi 0.149.0 → 0.151.0

data/lib/samagotchi/git_env.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The variables that tell a git which repo to act on. A process started by
+  # git (`rebase --exec`, `bisect run`, a hook) inherits them, and then its
+  # `git -C dir ...`, or a clone into a temp dir, reads or writes that repo
+  # instead of dir. chi's own git calls on a path chi chose spawn with UNSET;
+  # git then finds the repo from its cwd or -C. A model's and a user's commands
+  # (execute, tasks, !cmd) are theirs: they keep what chi was given.
+  module GitEnv
+    # `git rev-parse --local-env-vars` (git_env_spec checks it) less
+    # GIT_CONFIG_COUNT, which only adds settings and which git never sets for
+    # a child: like ~/.gitconfig it is the user's (a CI's clone credentials),
+    # and the suite's own (spec_helper). spec/e2e/support/env.js asks git for
+    # the same list.
+    VARS = %w[
+      GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_CONFIG GIT_CONFIG_PARAMETERS GIT_DIR GIT_GRAFT_FILE
+      GIT_IMPLICIT_WORK_TREE GIT_INDEX_FILE GIT_NO_REPLACE_OBJECTS GIT_OBJECT_DIRECTORY GIT_PREFIX
+      GIT_REPLACE_REF_BASE GIT_SHALLOW_FILE GIT_WORK_TREE
+    ].freeze
+
+    # What a spawn takes as its env: Process.spawn unsets a key mapped to nil.
+    # Not GIT_CONFIG_PARAMETERS, GIT_CONFIG_COUNT's older form (`git -c ...` around
+    # chi): settings for this git, not a repo, like a url.insteadOf for a clone.
+    # A test run clears it (VARS); what wants no config at all says so (TextMerge).
+    UNSET = (VARS - ["GIT_CONFIG_PARAMETERS"]).to_h { |name| [name, nil] }.freeze
+
+    module_function
+
+    # For a test run, as spec_helper and the kit's adapters load: its specs'
+    # `git -C tmp init` must not reach the real repo. Clears them for this
+    # process and all it starts, also from the copy Bundler keeps of the
+    # environment it started in: Bundler.with_unbundled_env and
+    # InstalledGem.unbundled_env_changes would put them back in a child.
+    def scrub!
+      clear(ENV)
+      clear(::Bundler::ORIGINAL_ENV) if defined?(::Bundler::ORIGINAL_ENV)
+    end
+
+    # @param env [#delete] ENV or a Hash
+    def clear(env) = VARS.each { |name| env.delete(name) }
+  end
+end

data/lib/samagotchi/guardrails/context.rb

@@ -93,6 +93,8 @@ module Samagotchi
         return {} unless File.directory?(dir)
 
         paths = ["--show-toplevel", "--git-path", "hooks", "--git-common-dir"]
+        # In chi's own environment, on purpose: a tool's git inherits it, and a
+        # card or a rule must judge the repo that git acts on (GIT_DIR around chi too).
         out, status = Open3.capture2e("git", "-C", dir, "rev-parse", *paths, "--abbrev-ref", "HEAD")
         # A repo with no commits yet has no HEAD: only the paths answer.
         out, status = Open3.capture2e("git", "-C", dir, "rev-parse", *paths) unless status.success?

data/lib/samagotchi/guardrails/targets.rb

@@ -401,7 +401,10 @@ module Samagotchi
       # :unknown for one the text doesn't tell); [] for other tools.
       def git_dirs
         @git_dirs ||= if shell?
-                        # chi's own GIT_DIR is not the command's concern
+                        # The text's and the call's env: only. chi's own GIT_DIR and
+                        # GIT_WORK_TREE aren't counted here, though execute inherits
+                        # them and the command does act on that repo; GitInfo (the
+                        # repo root and common dir this is compared with) follows them.
                         shell_envs.each_with_index.flat_map do |(home, vars), i|
                           ShellGitDirs.for(@command, cwd: @cwd, home: home, env: i.zero? ? {} : @env, vars: vars)
                         end.uniq

data/lib/samagotchi/memory_bundle/asset_installer.rb

@@ -19,6 +19,8 @@ module Samagotchi
     # warnings, and #run returns what the record (Provenance#write) keeps.
     # A dev install (+dev+, `chi bundle install --dev`) links each file to
     # the source instead of copying it, and warns of no checksum mismatch.
+    # An edited file it replaces or removes is copied to the trash first,
+    # under its subfolder (Trash#copy_edit); a link never is.
     class AssetInstaller
       # What was installed: the paths Provenance#write records (each
       # empty / nil on a dry run).
@@ -33,7 +35,8 @@ module Samagotchi
       # @param existing [InstalledBundle, nil] the record before this install
       # @param results, warnings, conflicts the Installer's (results and
       #   warnings are added to)
-      def initialize(name:, source_dir:, manifest:, provenance:, existing:, results:, warnings:, conflicts:,
+      # @param trash [Trash] the Installer's
+      def initialize(name:, source_dir:, manifest:, provenance:, existing:, results:, warnings:, conflicts:, trash:,
                      force: false, strict: true, upgrade: false, dry_run: false, dev: false)
         @name = name
         @bundle_dir = source_dir
@@ -43,6 +46,7 @@ module Samagotchi
         @results = results
         @warnings = warnings
         @conflicts = conflicts
+        @trash = trash
         @force = force
         @strict = strict
         @upgrade = upgrade
@@ -112,6 +116,7 @@ module Samagotchi
 
         FileUtils.mkdir_p(@provenance.hooks_dir)
         unchanged = File.exist?(dest) && FileUtils.identical?(src, dest)
+        @trash.copy_edit(dest, as: "hooks/#{basename}", recorded: prev_sha, incoming: src)
         place(src, dest)
         @results[basename] = if unchanged
                                { status: "skipped", reason: "already up to date" }
@@ -135,6 +140,7 @@ module Samagotchi
           else
             FileUtils.mkdir_p(@provenance.hooks_dir)
             dest = File.join(@provenance.hooks_dir, basename)
+            @trash.copy_edit(dest, as: "hooks/#{basename}", recorded: @existing&.hooks&.dig(basename)&.sha256, incoming: src)
             place(src, dest)
             @results[basename] = { status: "installed" }
             @hook_files[basename] = dest
@@ -152,6 +158,7 @@ module Samagotchi
           if File.exist?(old_dest) && !@force && !File.symlink?(old_dest)
             @warnings << "Bundle no longer includes hook #{old_key_str} but local file exists — removing"
           end
+          @trash.copy_edit(old_dest, as: "hooks/#{old_key_str}", recorded: @existing.hooks[old_key_str]&.sha256)
           FileUtils.rm_f(old_dest)
         end
       end
@@ -190,6 +197,7 @@ module Samagotchi
           dest = File.join(target, File.basename(src))
           File.file?(dest) && FileUtils.identical?(src, dest)
         end
+        @trash.copy_edits(target, "guardrails", @existing&.guardrails, incoming_rules.to_h { |src| [File.basename(src), src] })
         FileUtils.rm_rf(target)
         return {} if incoming_rules.empty?
 
@@ -210,7 +218,10 @@ module Samagotchi
       def install_plugin
         plugin = @manifest&.plugin
         unless plugin
-          FileUtils.rm_rf(@provenance.plugin_dir) unless @dry_run
+          unless @dry_run
+            @trash.copy_edits(@provenance.plugin_dir, "plugin", @existing&.plugin_shas)
+            FileUtils.rm_rf(@provenance.plugin_dir)
+          end
           return nil
         end
 
@@ -228,6 +239,7 @@ module Samagotchi
 
         dest = File.join(@provenance.plugin_dir, plugin[:file])
         unchanged = File.file?(dest) && FileUtils.identical?(src, dest)
+        @trash.copy_edits(@provenance.plugin_dir, "plugin", @existing&.plugin_shas, { plugin[:file] => src })
         FileUtils.rm_rf(@provenance.plugin_dir)
         FileUtils.mkdir_p(@provenance.plugin_dir)
         place(src, dest)
@@ -257,7 +269,7 @@ module Samagotchi
           raise Installer::InstallError, "the manifest names scripts/#{file}, which the bundle doesn't have" unless File.file?(src)
           raise Installer::InstallError, "scripts/#{file} is a symlink (not installed)" if linked?(src)
 
-          @warnings << "scripts/#{file} is not executable; chmod +x #{src}" if @dev && !File.executable?(src)
+          @warnings << "scripts/#{file} is not executable; chmod +x #{src}" if @dev && !File.executable?(src) && !page_only?(file)
         end
         return {} if @dry_run
 
@@ -265,6 +277,8 @@ module Samagotchi
           dest = File.join(@provenance.scripts_dir, file)
           File.file?(dest) && FileUtils.identical?(File.join(@bundle_dir, "scripts", file), dest)
         end
+        @trash.copy_edits(@provenance.scripts_dir, "scripts", @existing&.scripts,
+                          scripts.keys.to_h { |file| [file, File.join(@bundle_dir, "scripts", file)] })
         FileUtils.rm_rf(@provenance.scripts_dir)
         return {} if scripts.empty?
 
@@ -286,6 +300,12 @@ module Samagotchi
         end
       end
 
+      # A file only a block renderer's load names: the page loads it, nothing runs it.
+      def page_only?(file)
+        @manifest.block_renderers.any? { |renderer| renderer.load.include?(file) } &&
+          @manifest.context_providers.none? { |provider| provider.cmd.include?(file) }
+      end
+
       # Copies +src+ to +dest+, or (a dev install) links +dest+ to it. An
       # existing link goes first: a copy over it would write into the source.
       def place(src, dest)

data/lib/samagotchi/memory_bundle/builder.rb

@@ -30,8 +30,8 @@ module Samagotchi
       #   hooks       basename => BundleHook; hook_files basename => path
       #   rules       guardrails/*.yml paths
       #   plugin      the installed plugin file, nil without one
-      #   scripts     file name => path; context_providers the parsed list
-      InstalledParts = Data.define(:record, :hooks, :hook_files, :rules, :plugin, :scripts, :context_providers)
+      #   scripts     file name => path; context_providers, block_renderers the parsed lists
+      InstalledParts = Data.define(:record, :hooks, :hook_files, :rules, :plugin, :scripts, :context_providers, :block_renderers)
 
       attr_reader :built_files, :warnings, :placeholder_warnings, :out_path, :staging_dir
 
@@ -179,7 +179,8 @@ module Samagotchi
           rules: Dir.exist?(rules_dir) ? Dir.glob(File.join(rules_dir, "*.yml")).sort : [],
           plugin: plugin && File.file?(plugin) ? plugin : nil,
           scripts: installed_scripts(prov, record),
-          context_providers: record ? ContextProviders.parse_list(record.context_providers) : []
+          context_providers: record ? ContextProviders.parse_list(record.context_providers) : [],
+          block_renderers: record ? BlockRenderers.parse_list(record.block_renderers) : []
         )
       end
 
@@ -223,6 +224,7 @@ module Samagotchi
           needs: record&.needs,
           scripts: parts.scripts.transform_values { |src| "sha256:#{Digest::SHA256.hexdigest(File.binread(src))}" },
           context_providers: parts.context_providers,
+          block_renderers: parts.block_renderers,
           file_descriptions: file_descriptions(record, files_map),
           session_settings: record&.session_settings || [],
           session_setting_types: record&.session_setting_types || {},

data/lib/samagotchi/memory_bundle/file_standing.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Samagotchi
+  module MemoryBundle
+    # What chi says of an edited bundle file, everywhere it reports one: the one
+    # owner of these words (chi update's row and --json, chi bundle list and
+    # status, chi self, chi bootstrap, SystemBundle.ensure!'s echo, the Installer's
+    # summary, the phone's push).
+    #
+    # A file is merged (it took the update) or behind: marked conflict on its
+    # record, with bytes other than the bundle's text it speaks of. A marked file
+    # brought level by hand isn't behind, and a missing one is a missing file.
+    module FileStanding
+      # Why a merge of a mark from an older chi didn't go ahead (Merger.merge_outcome).
+      LEGACY_BASE = "an older chi may have taken your text as the base, and the merge would remove lines from your file"
+      # A real conflict on such a mark: its base can't say what the bundle changed.
+      LEGACY_CONFLICT = "it conflicts with the bundle's text, and an older chi's base can't say what it missed"
+      # A marked file Remerge leaves for the next upgrade or restore.
+      WAITS_FOR_UPGRADE = "it matches its old base, and the bundle's next version replaces it"
+      FILE_MISSING = "the file is missing, and the bundle's next version puts it back"
+      UNSURE = "an older chi marked it, and the next upgrade checks it"
+      NOT_SHIPPED = "not in the bundle now, nothing to merge"
+
+      # What --force does to a file that stays behind, and to an edited one being removed.
+      FORCE_TAKES = "--force takes the bundle's version, your file copied to the trash first"
+      FORCE_MOVES = "--force moves it to the trash"
+      # Why a file an agent step was given stays behind (BundleCommand#settle_conflicts).
+      STILL_BEHIND = { untouched: "Nothing changed in %s: still behind.",
+                       markers: "%s still holds conflict markers: still behind.",
+                       incoming_gone: "The bundle's copy of %s is gone: still behind." }.freeze
+      # A chi update row's short word for the trash; the path is long for a table.
+      IN_THE_TRASH = "old copies: chi bundle trash"
+      # How many missed headings a line names.
+      SHOWN_MISSED = 3
+
+      # One file that stays behind. why: the clause saying why no merge was tried
+      # (.no_merge, or a plain reason), nil for a real conflict. missed: the
+      # headings of the sections the bundle changed. places: the changes under no
+      # heading. unsure: an older mark that no retry has looked at, with nothing to
+      # compare the file to, so chi can't say it is behind.
+      # What a record gives is read as it is shaped: anything else is nothing known.
+      Behind = Data.define(:file, :version, :why, :missed, :places, :unsure) do
+        def initialize(file:, version: nil, why: nil, missed: [], places: 0, unsure: false)
+          super(file: file, version: version, why: why.is_a?(String) ? FileStanding.text(why) : nil,
+                missed: (missed.is_a?(Array) ? missed : []).grep(String).map { |heading| FileStanding.text(heading) },
+                places: places.is_a?(Integer) && places.positive? ? places : 0, unsure: unsure)
+        end
+
+        # "stays behind 0.8.0: missed ## Objectives"
+        def state(dry_run: false)
+          return "may be behind#{" #{version}" if version}: #{UNSURE}" if unsure
+
+          head = "#{dry_run ? "would stay" : "stays"} behind#{" #{version}" if version}"
+          rest = [why, FileStanding.missed_words(missed, places)].compact.join("; ")
+          rest.empty? ? head : "#{head}: #{rest}"
+        end
+
+        # "x.md stays behind 0.8.0: missed ## Objectives"
+        def line(dry_run: false) = "#{FileStanding.text(file)} #{state(dry_run: dry_run)}"
+      end
+
+      # A merge no report has shown yet, as the file's record keeps it
+      # (Provenance#note_merged). Every merge leaves one: a worker's reaches nothing
+      # but its log, an automatic update's rows no person. It shows in chi bundle
+      # status while it exists. A report someone reads ends it: chi update's row, for
+      # what it printed (this run's merges too), and chi bundle upgrade's output. No
+      # start says it: most sessions never read that file.
+      MergeNote = Data.define(:file, :version, :at, :trash) do
+        # "merged 0.8.0 into your x.md on 2026-11-05 14:03"
+        def line
+          "#{FileStanding.merged_line([file], version)}#{" on #{FileStanding.local_time(at)}" if at}"
+        end
+      end
+
+      module_function
+
+      # +value+ as UTF-8, whatever it was tagged, what isn't valid replaced: a file
+      # name under LC_ALL=C and a heading must join in one line.
+      def text(value) = value.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+
+      # "merged 0.8.0 into your x.md, y.md"
+      def merged_line(files, version, dry_run: false)
+        "#{dry_run ? "would merge" : "merged"}#{" #{version}" if version} into your #{files.map { |file| text(file) }.join(", ")}"
+      end
+
+      # The clause for a merge that couldn't answer: +why+ is TextMerge's reason
+      # or LEGACY_BASE, where chi can't even say the file holds edits.
+      def no_merge(why)
+        why == LEGACY_BASE ? "chi can't tell whether it holds edits of yours (#{why})" : "no merge possible (#{why})"
+      end
+
+      def still_behind(reason, file) = format(STILL_BEHIND.fetch(reason), text(file))
+
+      def left_as_it_is(message) = "left as it is (#{message})"
+
+      # "missed ## A, ## B, ## C and 2 more", "missed 2 places"; nil for nothing known.
+      def missed_words(headings, places)
+        return places.positive? ? "missed #{counted(places, "place")}" : nil if headings.empty?
+
+        more = [headings.size - SHOWN_MISSED, 0].max + places
+        words = "missed #{headings.first(SHOWN_MISSED).join(", ")}"
+        more.positive? ? "#{words} and #{more} more" : words
+      end
+
+      # "1 file behind"; "2 files may be behind" if chi isn't sure of one of them.
+      def behind_count(count, unsure: false) = "#{counted(count, "file")} #{"may be " if unsure}behind"
+
+      # "1 file stays behind", "2 files stay behind"; "1 file may be behind"
+      def stay_behind(count, unsure: false)
+        return behind_count(count, unsure: true) if unsure
+
+        "#{counted(count, "file")} #{count == 1 ? "stays" : "stay"} behind"
+      end
+
+      # The sentence of a push, merged and behind as counts: "" for neither.
+      def counts_sentence(merged:, behind:)
+        parts = []
+        parts << "Merged the update into #{counted(merged, "file")} you edited." if merged.to_i.positive?
+        parts << "#{stay_behind(behind)}." if behind.to_i.positive?
+        parts.join(" ")
+      end
+
+      # A report's clauses for one bundle: what merged, what stays behind with
+      # how to see it, what an earlier merge did.
+      # @param merged [Array<String>] files
+      # @param behind [Array<Behind>]
+      # @param earlier [Array<MergeNote>]
+      # @return [Array<String>]
+      def clauses(bundle, version, merged: [], behind: [], earlier: [], dry_run: false)
+        behind_lines = behind.map { |file| file.line(dry_run: dry_run) }
+        behind_lines[0] += " (#{diff_hint(bundle, behind.first.file)})" unless behind.empty?
+        [*(merged.empty? ? nil : merged_line(merged, version, dry_run: dry_run)), *behind_lines, *earlier.map(&:line)]
+      end
+
+      def diff_hint(bundle, file) = "chi bundle diff #{text(bundle)} #{text(file)}"
+
+      def local_time(stamp)
+        Time.iso8601(stamp.to_s).localtime.strftime("%Y-%m-%d %H:%M")
+      rescue ArgumentError
+        stamp.to_s
+      end
+
+      # The one answer to whether a file stays behind, for a report and a retry
+      # alike: marked, there, and not level with the bundle's text the mark speaks
+      # of. A missing file is a missing file (a project-scope record doesn't even
+      # say which project it means).
+      # @param incoming_sha [String, nil] that text's digest, for a mark with none
+      def behind?(path, entry, incoming_sha: entry[:incoming_sha])
+        entry[:conflict] == true && File.exist?(path) && differs?(path, incoming_sha)
+      end
+
+      # The file's bytes aren't what the mark says the bundle ships. One it can't
+      # read isn't known to be level. No digest (an older mark): it isn't known
+      # either, and a retry would have settled it.
+      def differs?(path, incoming_sha)
+        incoming_sha.nil? || Digest::SHA256.file(path).hexdigest != incoming_sha
+      rescue SystemCallError
+        true
+      end
+
+      def counted(count, noun) = "#{count} #{noun}#{"s" unless count == 1}"
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/installed_bundle.rb

@@ -1,24 +1,34 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json"
+require_relative "../memory_paths"
 require_relative "bundle_hook"
 require_relative "plugin_ref"
 
 module Samagotchi
   module MemoryBundle
+    # Only what reports on an edited file needs it.
+    autoload :FileStanding, File.expand_path("file_standing", __dir__)
+
     # An installed bundle's record, as Provenance#write keeps it in
     # <bundles>/<name>/manifest.json. Reading is tolerant: an older record
     # lacks keys a newer chi writes, and a key that is missing or of the
     # wrong shape reads as empty (nil for the optional strings and lists).
     #
-    #   files       file key ("x.md") => { checksum:, conflict:, description: } (symbol keys)
+    #   files       file key ("x.md") => { checksum:, conflict:, incoming_sha:, legacy_base:, why:, missed:, missed_places:,
+    #               description: } (symbol keys);
+    #               incoming_sha: the bundle text a conflict mark speaks of, nil on an older mark;
+    #               legacy_base: true on an older mark that has since got its incoming_sha (.legacy_mark?);
+    #               why, missed, missed_places: FileStanding::Behind's, nil on an older mark;
+    #               merged_version, merged_at, merged_trash: a merge no report has shown (Provenance#note_merged)
     #   hooks       basename => BundleHook
     #   guardrails  basename => recorded sha256 ("" when none)
     #   scripts     file name => recorded sha256 ("" when none)
     #   plugin      PluginRef, nil without one
-    #   needs, context_providers
-    #               the lists as recorded (nil when absent): Manifest.parse_needs
-    #               and ContextProviders.parse_list check them
+    #   needs, context_providers, block_renderers
+    #               the lists as recorded (nil when absent): Manifest.parse_needs,
+    #               ContextProviders.parse_list and BlockRenderers.parse_list check them
     #   includes    a profile's recorded members, nil for a plain bundle
     #   session_settings
     #               the keys a session may set (chi --set), [] when none
@@ -33,18 +43,24 @@ module Samagotchi
     #   error       why manifest.json couldn't be read (the rest empty), else nil
     class InstalledBundle < Data.define(:name, :version, :scope, :source, :installed_at, :trust_level, :source_commit,
                                         :requires_chi, :files, :hooks, :guardrails, :scripts, :plugin, :needs,
-                                        :includes, :context_providers, :session_settings, :session_setting_types, :settings,
+                                        :includes, :context_providers, :block_renderers, :session_settings, :session_setting_types, :settings,
                                         :setting_types, :dev,
                                         :error)
       OPTIONAL = { version: nil, scope: nil, source: nil, installed_at: nil, trust_level: nil, source_commit: nil,
                    requires_chi: nil, files: {}, hooks: {}, guardrails: {}, scripts: {}, plugin: nil, needs: nil,
-                   includes: nil, context_providers: nil, session_settings: [], session_setting_types: {}, settings: nil, setting_types: {}, dev: false,
+                   includes: nil, context_providers: nil, block_renderers: nil, session_settings: [], session_setting_types: {}, settings: nil, setting_types: {}, dev: false,
                    error: nil }.freeze
 
       def initialize(name:, **fields)
         super(name: name, **OPTIONAL, **fields)
       end
 
+      # Whether a file's entry is a conflict mark from an older chi: no
+      # incoming_sha, or legacy_base. Such a mark's base may be the user's own
+      # text (0.149 took it for a file with no base). Getting its digest later
+      # must not make it look new, so legacy_base stays until the mark goes.
+      def self.legacy_mark?(entry) = !!entry && entry[:conflict] == true && (entry[:legacy_base] == true || !entry[:incoming_sha])
+
       # The record at +path+, nil when there is none.
       # @raise [JSON::ParserError, SystemCallError] it doesn't read
       def self.read(name, path)
@@ -70,6 +86,7 @@ module Samagotchi
             guardrails: mapping(h["guardrails"]) { |meta| sha(meta) },
             scripts: mapping(h["scripts"]) { |meta| sha(meta) },
             plugin: PluginRef.parse(h["plugin"]), needs: h["needs"], context_providers: h["context_providers"],
+            block_renderers: h["block_renderers"],
             includes: h["includes"].is_a?(Array) ? h["includes"].map(&:to_s) : nil,
             session_settings: h["session_settings"].is_a?(Array) ? h["session_settings"].map(&:to_s) : [],
             session_setting_types: mapping(h["session_setting_types"]) { |type| type.to_s },
@@ -100,9 +117,56 @@ module Samagotchi
 
       def owns?(file_key) = files.key?(file_key.to_s)
 
+      # The plugin's file => its recorded sha256, as guardrails and scripts read.
+      def plugin_shas = plugin ? { plugin.file => plugin.sha256 } : {}
+
+      # The marked files that stay behind: one that isn't there is a missing file,
+      # and one with the bundle's bytes has nothing left to miss.
+      # @param target_dir [String, nil] where its files are; a scope this chi can't
+      #   resolve has none, and nothing is known of them
+      # @return [Array<FileStanding::Behind>]
+      def behind_files(target_dir = MemoryPaths.scope_dir(effective_scope))
+        return [] unless target_dir
+
+        files.filter_map { |key, entry| behind_entry(key, entry) if behind_file?(key, File.join(target_dir, key)) }
+      end
+
+      # FileStanding.behind? for this record's file. An older mark names no text,
+      # but a source still on disk holds it: level with that, it has missed nothing.
+      def behind_file?(key, path)
+        entry = files.fetch(key)
+        FileStanding.behind?(path, entry, incoming_sha: entry[:incoming_sha] || source_sha(key))
+      end
+
+      # The merges no chi update has shown yet.
+      # @return [Array<FileStanding::MergeNote>]
+      def merge_notes
+        files.filter_map do |key, entry|
+          next unless entry[:merged_version]
+
+          FileStanding::MergeNote.new(file: key, version: entry[:merged_version], at: entry[:merged_at], trash: entry[:merged_trash])
+        end
+      end
+
+      # The file's mark as a report reads it.
+      def behind_entry(key, entry = files.fetch(key))
+        FileStanding::Behind.new(file: key, version: version, why: entry[:why], missed: entry[:missed], places: entry[:missed_places],
+                                 unsure: !entry[:incoming_sha] && !entry[:why])
+      end
+
+      def source_sha(key)
+        path = File.join(source.to_s, key)
+        File.file?(path) ? Digest::SHA256.file(path).hexdigest : nil
+      rescue SystemCallError
+        nil
+      end
+      private :source_sha
+
       def needs? = needs.is_a?(Array) && !needs.empty?
 
       def context_providers? = context_providers.is_a?(Array) && !context_providers.empty?
+
+      def block_renderers? = block_renderers.is_a?(Array) && !block_renderers.empty?
     end
   end
 end

data/lib/samagotchi/memory_bundle/installed_copy.rb

@@ -42,6 +42,7 @@ module Samagotchi
           requires_chi: bundle.requires_chi, needs: bundle.needs,
           # A record read with symbol keys: back to what a manifest.yml holds.
           context_providers: JSON.parse(JSON.generate(Array(bundle.context_providers))),
+          block_renderers: JSON.parse(JSON.generate(Array(bundle.block_renderers))),
           session_settings: bundle.session_settings, session_setting_types: bundle.session_setting_types,
           settings: bundle.settings, setting_types: bundle.setting_types
         )