samagotchi 0.145.0 → 0.147.0

data/lib/samagotchi/memory_command.rb

@@ -5,42 +5,59 @@ require_relative "cli/command"
 require_relative "cli/exit"
 require_relative "cli/flags"
 require_relative "memory_paths"
+require_relative "system_prompt"
 require_relative "tools/memory"
 require_relative "memory_bundle/index_updater"
 require_relative "memory_bundle/provenance"
+require_relative "memory_usage"
 
 module Samagotchi
   # `chi memory`: the user's side of the memories (docs/memory.md). ls lists
   # both scopes' entries from their index.md lines and files, as memory_read
   # and the prompt see them; rm removes one as memory_write remove: true does
   # (Tools::MemoryWrite.remove: the file and its model overlays into the
-  # bundle trash, the index line dropped, a bundle's memory refused).
+  # bundle trash, the index line dropped, a bundle's memory refused); usage
+  # reports what the memories cost and what the saved sessions read
+  # (MemoryUsage, docs/memory.md "What the memories cost").
   class MemoryCommand
     include CLI::Command
 
     USAGE = <<~TEXT
-      Usage: chi memory <ls|rm> [options]
+      Usage: chi memory <ls|rm|usage> [options]
         ls [--scope project|system] [--format text|json]   the memories: both scopes (this folder's project
              first), or one; each with its size, date, the bundle it came from and its index description
         rm NAME [--scope project|system]   remove a memory: its file and its model overlays (NAME.<key>.md)
              move to the bundle trash (chi bundle trash lists and empties it) and its index line is dropped.
              Without --scope NAME must be in one scope only. A bundle's memory is refused: chi bundle
              uninstall removes it. NAME.<key> removes one model overlay alone.
+        usage [--scope project|system] [--top N] [--format text|json]   what the memories cost, counted from
+             the saved sessions: each scope's index tokens, the memories read most (by tokens), and the ones
+             no saved session read. --top is the rows per section (10, at most 1000); no sessions says so and exits 0.
     TEXT
 
-    SUBCOMMANDS = %w[ls rm].freeze
+    SUBCOMMANDS = %w[ls rm usage].freeze
     SCOPES = Tools::VALID_SCOPES
     # The description column's width in ls's text form (json has it all).
     DESCRIPTION_WIDTH = 60
     # ls's size column, right-aligned.
     SIZE_COLUMN = 2
+    # usage's rows per section, when --top is not given.
+    DEFAULT_TOP = 10
+    # The most rows --top may ask for: a report of more is unreadable, and a
+    # huge number used to raise out of Array#first.
+    TOP_LIMIT = 1000
 
     FLAGS = {
       "ls" => CLI::Flags.new(help: HELP_WORDS) do |f|
         f.value "--scope"
         f.value "--format"
       end,
-      "rm" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--scope" }
+      "rm" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--scope" },
+      "usage" => CLI::Flags.new(help: HELP_WORDS) do |f|
+        f.value "--scope"
+        f.value "--top"
+        f.value "--format"
+      end
     }.freeze
 
     # One memory of a scope. +date+ is the index line's (the file's mtime
@@ -94,7 +111,7 @@ module Samagotchi
       return [] unless File.directory?(dir)
 
       index_path = File.join(dir, "#{Tools::MEMORY_INDEX}.md")
-      index_text = File.file?(index_path) ? File.read(index_path, encoding: "UTF-8") : ""
+      index_text = Tools::MemoryRead.read_text(index_path)
       # name => its line; the first one when a name has two. A name rm
       # would refuse (a path: "../x") isn't listed.
       lines = {}
@@ -191,6 +208,118 @@ module Samagotchi
 
     def clip(text) = text.length > DESCRIPTION_WIDTH ? "#{text[0, DESCRIPTION_WIDTH - 1]}…" : text
 
+    def run_usage(options, args)
+      return usage_error("usage takes no NAME (unexpected #{args.first})") unless args.empty?
+
+      format = options[:format]
+      return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
+      return usage_error("--top must be a positive integer") unless options[:top].nil? || options[:top].to_s.match?(/\A[1-9]\d*\z/)
+      return usage_error("--top must be at most #{TOP_LIMIT}") if options[:top].to_i > TOP_LIMIT
+
+      sessions, unreadable = MemoryUsage.load_sessions
+      report = MemoryUsage.new(
+        sessions: sessions, entries: self.class.entries(options[:scope]),
+        scopes: options[:scope] ? [options[:scope]] : SCOPES, unreadable: unreadable, root: Dir.pwd,
+        # config.yml's memories: plus the system memories every prompt carries
+        # (SystemPrompt::DEFAULT_SYSTEM_MEMORIES): both are in the prompt from
+        # the start, so no read is needed for them.
+        baseline: ConfigFile.preloaded_memories + SystemPrompt::DEFAULT_SYSTEM_MEMORIES
+      ).report(top: (options[:top] || DEFAULT_TOP).to_i)
+
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(report.to_h))
+      else
+        print_usage(report)
+      end
+      CLI::Exit::OK
+    end
+
+    def print_usage(report)
+      if report.sessions.zero?
+        why = []
+        why << "#{report.unreadable} #{report.unreadable == 1 ? "file" : "files"} that could not be read" if report.unreadable.positive?
+        why << "#{report.skipped} #{report.skipped == 1 ? "session" : "sessions"} not counted (test runs or no user message)" if report.skipped.positive?
+        @stdout.puts(why.empty? ? "no sessions to count: nothing saved in #{Session.default_state_dir}" : "no sessions to count: #{why.join(" and ")} in #{Session.default_state_dir}")
+        return
+      end
+
+      header = "#{report.sessions} #{report.sessions == 1 ? "session" : "sessions"} over " \
+               "#{report.days} #{report.days == 1 ? "day" : "days"}"
+      header += ", #{report.unreadable} unreadable #{report.unreadable == 1 ? "file" : "files"} skipped" if report.unreadable.positive?
+      header += ", #{report.skipped} #{report.skipped == 1 ? "session" : "sessions"} not counted (test run or no user message)" if report.skipped.positive?
+      @stdout.puts(header)
+      @stdout.puts
+
+      # The index comes first: it is paid on every prompt, reads only on a read.
+      print_table(["Indexes", "tokens", "limit", "index lines naming a memory no session read"],
+                  report.indexes.map do |index|
+                    [indent(index.scope), token_text(index.tokens), index.limit.positive? ? index.limit.to_s : "off",
+                     "#{index.unread_lines} of #{index.lines} (#{index.unread_percent}%)"]
+                  end, right: [1, 2])
+      @stdout.puts
+
+      if report.read_count.zero?
+        @stdout.puts("No memory reads in these sessions.")
+      elsif report.top.empty?
+        # Every read is of a name with no memory behind it: no rows to show.
+        @stdout.puts("Most read, by tokens: none of these reads names a memory still there " \
+                     "(#{report.unknown_names} #{report.unknown_names == 1 ? "name" : "names"} read, " \
+                     "#{token_text(report.read_tokens)} tokens)")
+      else
+        share = report.read_tokens.positive? ? (100.0 * report.top.sum(&:tokens) / report.read_tokens).round : 0
+        @stdout.puts("Most read, by tokens (these #{report.top.size} of #{report.read_names}: " \
+                     "#{share}% of #{token_text(report.read_tokens)} read tokens)")
+        print_table(%w[Memory tokens reads size scope from],
+                    report.top.map do |use|
+                      [indent(use.name), token_text(use.tokens), use.reads.to_s,
+                       size_text(use.size_tokens), use.scope, use.source.to_s]
+                    end, right: [1, 2])
+        if report.cut_reads.positive?
+          @stdout.puts(indent("note: #{report.cut_reads} of these reads came back cut (reads used to be cut), " \
+                              "so a big memory may cost more per read now than these numbers show"))
+        end
+      end
+      @stdout.puts
+
+      if report.not_read_total.zero?
+        @stdout.puts("Not read in saved sessions: nothing of your own to count (a bundle's memories are not listed)")
+      else
+        @stdout.puts("Not read in saved sessions: #{report.not_read_count} of #{report.not_read_total} of your own " \
+                     "memories (a bundle's are not listed)")
+        print_table(["", "size", "scope"], report.not_read.map { |entry| [indent(entry.name), size_text(entry.tokens), entry.scope] }, right: [1]) if report.not_read.any?
+        @stdout.puts(indent("An index line is paid whatever a session reads: a memory nobody opens still costs its line in every prompt."))
+      end
+
+      @stdout.puts(indent("Names read that have no memory now: #{report.unknown_names}")) if report.unknown_names.positive?
+    end
+
+    def indent(text) = "  #{text}"
+
+    # A token count as usage's columns show it: "450", "1.9k", "2.0M".
+    def token_text(value)
+      number = value.to_i
+      return number.to_s if number < 1000
+      return format("%.1fk", number / 1000.0) if number < 1_000_000
+
+      format("%.1fM", number / 1_000_000.0)
+    end
+
+    # A size column: "-" when the memory has no file to measure.
+    def size_text(tokens) = tokens.nil? ? "-" : token_text(tokens)
+
+    # A header row and its rows, two spaces apart; the +right+ columns align on
+    # their numbers.
+    def print_table(header, rows, right: [])
+      table = [header, *rows]
+      widths = table.transpose.map { |column| column.map { |cell| cell.to_s.length }.max }
+      table.each do |cells|
+        line = cells.each_with_index.map do |cell, index|
+          right.include?(index) ? cell.to_s.rjust(widths[index]) : cell.to_s.ljust(widths[index])
+        end
+        @stdout.puts(line.reject.with_index { |_, index| widths[index].zero? }.join("  ").rstrip)
+      end
+    end
+
     def run_rm(options, args)
       name = args.shift
       return usage_error("give the memory's NAME") unless name
@@ -229,9 +358,8 @@ module Samagotchi
 
     def present?(name, scope)
       dir = MemoryPaths.scope_dir(scope)
-      index = File.join(dir, "#{Tools::MEMORY_INDEX}.md")
       File.file?(File.join(dir, "#{name}.md")) ||
-        (File.file?(index) && File.read(index, encoding: "UTF-8").match?(Tools::MemoryWrite.managed_pattern(name)))
+        Tools::MemoryRead.read_text(File.join(dir, "#{Tools::MEMORY_INDEX}.md")).match?(Tools::MemoryWrite.managed_pattern(name))
     end
   end
 end

data/lib/samagotchi/memory_paths.rb

@@ -51,6 +51,15 @@ module Samagotchi
       File.basename(common) == ".git" ? File.dirname(common) : common
     end
 
+    # The repository's common git dir of +cwd+ as an absolute real path (the
+    # same for every worktree of it), or nil outside any repository. Reads
+    # files only, no git process; #project_root turns it into a checkout
+    # folder, which a bare layout's container is not.
+    def common_git_dir(cwd = Dir.pwd)
+      gitdir = git_dir(cwd)
+      gitdir && File.realpath(common_dir(gitdir))
+    end
+
     # The top of the git work tree holding +cwd+: the directory with the
     # nearest .git (a linked worktree's own checkout, unlike #project_root);
     # nil outside any repository.

data/lib/samagotchi/memory_usage.rb

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "memory_paths"
+require_relative "memory_bundle/index_size"
+require_relative "model_notes"
+require_relative "session"
+require_relative "llm_context_stale"
+require_relative "working_set"
+require_relative "file_ref"
+require_relative "tool_response"
+require_relative "tool_output_cut"
+require_relative "model_overlay"
+require_relative "tools/memory"
+
+module Samagotchi
+  # `chi memory usage` (docs/memory.md): what the memories cost and what the
+  # saved sessions really read. Reading only: no writes, no model call, no
+  # grades and no advice. It is given the entries (MemoryCommand.entries) and
+  # the sessions to count, and returns Data values the command prints.
+  #
+  # A read is a tool run that pairs with its call (LLMContextStale.paired_runs,
+  # so both loops' saved shapes count: the chat loop's tool_calls with their
+  # tool_call_id, the native loop's call markup with one joined result), of
+  # `memory_read` or of `read` on a memory's file. Its cost is the size of the
+  # result as it was saved - a cut result counts as it happened, an overlay
+  # too - in tokens the way the prompt's own estimate does (characters /
+  # context.chars_per_token). A `memory_read` of a comma list splits that one
+  # result by share, as WorkingSet.item does.
+  #
+  # A project memory is credited only with the reads of sessions of this
+  # folder's project (MemoryPaths.project_root: worktrees of one repository
+  # share it); a system memory with every session's. Sessions are the saved
+  # files, so retention limits what can be seen: that is why the header says
+  # how many sessions and how many days.
+  class MemoryUsage
+    # The memory scopes, project first, as `chi memory ls` reports them.
+    SCOPES = Tools::VALID_SCOPES
+    MEMORY_READ = Tools::MemoryRead::NAME
+    FILE_READ = Tools::Read::NAME
+
+    # One memory read at least once in the sessions counted: its tokens (the
+    # results' size) and reads, +cut_reads+ of them returned a cut result,
+    # +bytes+ its file now (nil: no file) and +size_tokens+ that size (nil
+    # when there is no file), +source+ the bundle that owns it.
+    Use = Data.define(:name, :scope, :tokens, :reads, :cut_reads, :bytes, :size_tokens, :source) do
+      def to_h = super.transform_keys(&:to_s)
+    end
+
+    # One scope's index as every prompt pays it: its tokens, the warning
+    # limit (0: off), its memory lines, and those naming a memory no counted
+    # session read.
+    Index = Data.define(:scope, :tokens, :limit, :lines, :unread_lines) do
+      def unread_percent = lines.zero? ? 0 : (100.0 * unread_lines / lines).round
+
+      def to_h = { "scope" => scope, "tokens" => tokens, "limit" => limit,
+                   "lines" => lines, "unread_lines" => unread_lines, "unread_percent" => unread_percent }
+    end
+
+    # A memory of the user's own no counted session read: +bytes+ its file,
+    # +tokens+ that size. A candidate, not a verdict.
+    Unread = Data.define(:name, :scope, :bytes, :tokens) do
+      def to_h = super.transform_keys(&:to_s)
+    end
+
+    # Everything the command prints. +sessions+ are the ones counted (no test
+    # runs, none without a user message, archived ones included), +skipped+
+    # the saved files not counted for that reason, +unreadable+ the files that
+    # could not be read; +top+ and +not_read+ are limited to +top+ rows each.
+    Report = Data.define(:sessions, :skipped, :unreadable, :days, :indexes, :read_count, :read_tokens, :cut_reads,
+                         :read_names, :unknown_names, :top, :not_read, :not_read_count, :not_read_total) do
+      def to_h
+        {
+          "sessions" => sessions, "skipped" => skipped, "unreadable" => unreadable, "days" => days,
+          "indexes" => indexes.map(&:to_h),
+          "reads" => { "count" => read_count, "tokens" => read_tokens, "cut_reads" => cut_reads,
+                       "names" => read_names },
+          "top" => top.map(&:to_h),
+          "not_read" => { "count" => not_read_count, "total" => not_read_total, "largest" => not_read.map(&:to_h) },
+          "unknown_names" => unknown_names
+        }
+      end
+    end
+
+    # The saved sessions to count, each file parsed once (Session.list then
+    # Session.load would parse twice and drop corrupt files silently).
+    # @return [Array(Array<Session>, Integer)] the sessions and the files that could not be read
+    def self.load_sessions(state_dir: Session.default_state_dir)
+      sessions = []
+      unreadable = 0
+      Dir.glob(File.join(state_dir, "*#{Session::FILE_EXT}")).sort.each do |path|
+        data = JSON.parse(File.read(path, encoding: "UTF-8"))
+        # A project_root that is not a path (a hand-edited file) makes every
+        # later step raise, so the file counts as unreadable rather than
+        # taking the whole report down.
+        raise ArgumentError, "project_root is not a path" unless data["project_root"].nil? || data["project_root"].is_a?(String)
+
+        sessions << Session.from_h(data)
+      rescue StandardError
+        unreadable += 1
+      end
+      [sessions, unreadable]
+    end
+
+    # @param sessions [Array<Session>] the saved sessions (load_sessions, or a spec's)
+    # @param entries [Array<MemoryCommand::Entry>] the memories to report on
+    # @param scopes [Array<String>] the scopes to measure their indexes for
+    # @param unreadable [Integer] session files that could not be read
+    # @param baseline [Array<String>] memories no read is needed for: config.yml's
+    #   `memories:` and the system memories every prompt carries
+    #   (SystemPrompt::DEFAULT_SYSTEM_MEMORIES). They are in the prompt from the
+    #   start, so they are never saved as used or preloaded in the session file.
+    # @param root [String] the folder whose project's memories are the project scope
+    # @param env [Hash] the XDG env the memories dirs resolve from
+    def initialize(sessions:, entries:, scopes: SCOPES, unreadable: 0, baseline: [], root: Dir.pwd, env: ENV,
+                   chars_per_token: MemoryBundle::IndexSize.chars_per_token,
+                   warn_limit: MemoryBundle::IndexSize.warn_limit)
+      @sessions = Array(sessions)
+      @entries = Array(entries)
+      @scopes = Array(scopes).map(&:to_s)
+      @unreadable = unreadable.to_i
+      @baseline = Array(baseline).map { |raw| name_of(raw) }
+      # The project the report is for, as MemoryPaths keys it (a worktree
+      # resolves to its repository's root; both spellings of a path, /var and
+      # /private/var, mean the same project).
+      @root = expand(MemoryPaths.project_root(File.expand_path(root.to_s)))
+      @env = env
+      @chars_per_token = chars_per_token.positive? ? chars_per_token.to_f : 4.0
+      @warn_limit = warn_limit.to_i
+    end
+
+    # @param top [Integer] the rows the report keeps per section
+    # @return [Report]
+    def report(top: 10)
+      known = {}
+      gone = {}
+      # [scope, name]: a session's used names carry no scope, and another
+      # project's can't vouch for this project's memory of the same name.
+      used = Set.new(@baseline.flat_map { |name| SCOPES.map { |scope| [scope, name] } })
+      times = []
+      sessions = 0
+      skipped = 0
+
+      @sessions.each do |session|
+        if session.test_run || !session.messages.any? { |entry| entry[:role].to_s == "user" }
+          skipped += 1
+          next
+        end
+
+        sessions += 1
+        time = time_of(session.updated_at)
+        times << time if time
+        project = project_session?(session)
+        project_dir = project_dir_of(session)
+
+        (Array(session.used_memory_names) + Array(session.preloaded_memory_names)).each do |raw|
+          used << ["system", name_of(raw)]
+          used << ["project", name_of(raw)] if project
+        end
+
+        reads(session, project, project_dir).each do |scope, name, tokens, cut|
+          next unless @scopes.include?(scope) # --scope system leaves a project's reads out
+
+          used << [scope, name]
+          # A name with no memory behind it (deleted, or a scope nobody asked
+          # for) counts in the totals, but never as a row.
+          bucket = entry_for(scope, name) ? known : gone
+          row = bucket[[scope, name]] ||= { tokens: 0, reads: 0, cut_reads: 0 }
+          row[:tokens] += tokens
+          row[:reads] += 1
+          row[:cut_reads] += 1 if cut
+        end
+      end
+
+      rows = known.map do |(scope, name), acc|
+        entry = entry_for(scope, name)
+        Use.new(name: name, scope: scope, tokens: acc[:tokens], reads: acc[:reads], cut_reads: acc[:cut_reads],
+                bytes: entry.bytes, size_tokens: entry.bytes ? token_count(entry.bytes) : nil, source: entry.source)
+      end.sort_by { |row| [-row.tokens, row.name] }
+
+      unread = @entries.reject { |entry| entry.source || used.include?([entry.scope.to_s, entry.name]) }
+                       .sort_by { |entry| [-entry.bytes.to_i, entry.name] }
+      not_read = unread.first(top).map do |entry|
+        Unread.new(name: entry.name, scope: entry.scope, bytes: entry.bytes, tokens: entry.bytes ? token_count(entry.bytes) : nil)
+      end
+
+      Report.new(
+        sessions: sessions,
+        skipped: skipped,
+        unreadable: @unreadable,
+        days: times.empty? ? 0 : ((times.max - times.min) / 86_400.0).round,
+        indexes: @scopes.map { |scope| index_row(scope, used) },
+        read_count: known.sum { |_, acc| acc[:reads] } + gone.sum { |_, acc| acc[:reads] },
+        read_tokens: known.sum { |_, acc| acc[:tokens] } + gone.sum { |_, acc| acc[:tokens] },
+        cut_reads: known.sum { |_, acc| acc[:cut_reads] } + gone.sum { |_, acc| acc[:cut_reads] },
+        read_names: known.size,
+        unknown_names: gone.size,
+        top: rows.first(top),
+        not_read: not_read,
+        not_read_count: unread.size,
+        not_read_total: @entries.reject(&:source).size
+      )
+    end
+
+    private
+
+    def entries_by_scope
+      @entries_by_scope ||= @entries.to_h { |entry| [entry.scope.to_s, {}] }.tap do |by_scope|
+        @entries.each { |entry| by_scope[entry.scope.to_s][entry.name] ||= entry }
+      end
+    end
+
+    # The entry a counted read's [scope, name] is, nil for a name with no
+    # memory now (a deleted one, a scope no entries were asked for).
+    def entry_for(scope, name)
+      entries_by_scope.fetch(scope, {})[name]
+    end
+
+    # One scope's index: its tokens and lines as the prompt pays them, and how
+    # many of its memory lines name a memory no counted session read. Only the
+    # lines of memories count (MemoryCommand::LINE, and the entries `chi memory
+    # ls` finds behind them): a heading or a bold line of prose is neither the
+    # denominator nor an unread line.
+    def index_row(scope, used)
+      text = index_text(scope)
+      size = MemoryBundle::IndexSize.of_text(scope, text, chars_per_token: @chars_per_token)
+      names = text.each_line.filter_map { |line| (match = MemoryCommand::LINE.match(line)) && match[1] }.uniq
+      entries = names.select { |name| entry_for(scope, name) }
+      unread = entries.count { |name| !used.include?([scope, name]) }
+      Index.new(scope: scope, tokens: size.tokens, limit: @warn_limit, lines: entries.size, unread_lines: unread)
+    end
+
+    def index_text(scope)
+      raw = Tools::MemoryRead.scoped_index(scope, env: @env)
+      ModelNotes.filter_index(raw, scope, env: @env)
+    end
+
+    # The reads of one session: [scope, name, tokens, cut?].
+    def reads(session, project, project_dir)
+      LLMContextStale.paired_runs(session.messages).flat_map do |run|
+        call = run.call
+        name = call[:name].to_s
+        next [] if failed?(run.text)
+
+        if name == MEMORY_READ
+          # index.md is not a memory: the model reads it by name now and then,
+          # and its cost is the Indexes section above - but it is one of the
+          # names the one result is split between, as WorkingSet does.
+          found = WorkingSet.found_names(run)
+          names = found.reject { |memory| memory.casecmp?(Tools::MEMORY_INDEX) }
+          next [] if names.empty?
+
+          tokens = token_count(run.text.length, found.size)
+          cut = cut_result?(run.text)
+          names.filter_map do |memory|
+            scope = scope_of(memory, call[:scope], project_dir)
+            scope == "project" && !project ? nil : [scope, memory, tokens, cut]
+          end
+        elsif name == FILE_READ
+          found = memory_file(FileRef.for(name, call, cwd: session.working_directory)&.path, project_dir)
+          # A project memory is credited only with this project's sessions.
+          next [] if found.nil? || (found.first == "project" && !project)
+
+          [[found.first, found.last, token_count(run.text.length), cut_result?(run.text)]]
+        else
+          []
+        end
+      end
+    end
+
+    # WorkingSet's rule: an errored or interrupted run touched nothing.
+    def failed?(text)
+      ToolResponse.interrupted_text?(text) || text.sub(ToolResponse::LEAD, "").lstrip.start_with?("Error")
+    end
+
+    # A result the runner cut: one of ToolOutputCut's marker lines is its own
+    # line. Reads saved before whole reads hold cut results, so the cut
+    # caveat below is one line, not a section; a memory that only mentions
+    # "[cut: ..." in its body is not one.
+    def cut_result?(text)
+      text.to_s.each_line.any? { |line| ToolOutputCut.cut_marker_line?(line) }
+    end
+
+    # Which scope a name a session read belongs to: the scope the call gave,
+    # else the session's project when its file is there, else system.
+    def scope_of(name, scope, project_dir)
+      given = scope.to_s
+      return given if SCOPES.include?(given)
+
+      project_dir && File.file?(File.join(project_dir, "#{name}.md")) ? "project" : "system"
+    end
+
+    # A read of a memory's file: [scope, name], nil for any other file. The
+    # session's own project folder (MemoryPaths.key_for_root), since
+    # IndexSync.memory_scope knows only the folder chi is running in.
+    def memory_file(path, project_dir)
+      return nil if path.nil? || !path.end_with?(".md")
+
+      dir = expand(File.dirname(path))
+      stem = File.basename(path, ".md")
+      return nil if stem.empty? || stem.casecmp?(Tools::MEMORY_INDEX) || stem.start_with?(".")
+
+      if dir == expand(MemoryPaths.system_dir(env: @env))
+        ["system", base_memory("system", stem)]
+      elsif project_dir && dir == expand(project_dir)
+        ["project", base_memory("project", stem)]
+      end
+    end
+
+    # The memory a file's stem names. A model overlay's file (<base>.<key>.md,
+    # ModelOverlay and Tools::MemoryWrite.overlay_files) is a read of the
+    # memory it overlays - unless the stem is a memory of its own, which
+    # overlay_files also checks: a name with a dot (handoff_x.v2) has an
+    # index line, so it is listed by `chi memory ls`.
+    def base_memory(scope, stem)
+      base = ModelOverlay.base_file_for("#{stem}.md")
+      return stem if base.nil?
+
+      named = File.basename(base, ".md")
+      # A stem that is a memory of its own keeps its own reads; an orphan
+      # overlay (its base is gone) stays the name its file has.
+      return stem if entry_for(scope, stem) || entry_for(scope, named).nil?
+
+      named
+    end
+
+    def expand(dir)
+      File.realpath(dir)
+    rescue SystemCallError
+      File.expand_path(dir)
+    end
+
+    # The project a session belongs to: the root its file stores, or (a file
+    # from before the field, or a folder in no repository) the root of the
+    # folder it works in.
+    def session_project_root(session)
+      root = session.project_root ||
+             (session.working_directory.to_s.empty? ? nil : MemoryPaths.project_root(File.expand_path(session.working_directory.to_s)))
+      root && expand(root)
+    end
+
+    def project_dir_of(session)
+      root = session_project_root(session)
+      root ? File.join(MemoryPaths.projects_dir(env: @env), MemoryPaths.key_for_root(root)) : nil
+    end
+
+    # A session of this folder's project (worktrees of one repository share it).
+    def project_session?(session)
+      session_project_root(session) == @root
+    end
+
+    # "system/delegated" is the memory named delegated.
+    def name_of(raw)
+      File.basename(raw.to_s, ".md").strip
+    end
+
+    def token_count(chars, share = 1)
+      (chars.to_i / @chars_per_token / share).ceil
+    end
+
+    def time_of(value)
+      Time.parse(value.to_s)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/samagotchi/relay.rb

@@ -94,12 +94,12 @@ module Samagotchi
     end
 
     # The child's options, by index: "session" is the child's session, so
-    # it says whose; "once", "repo", "rule" and Deny keep their labels (the
+    # it says whose (one more hop names the longer chain), and keeps what it covers; "once", "repo", "rule" and Deny keep their labels (the
     # approvals store is shared, a session scope keys on the child's id).
     def relabel(options, scopes, who)
       scopes = Array(scopes)
       options.each_with_index.map do |label, index|
-        scopes[index].to_s == "session" ? "Allow this call for delegate #{who}'s session" : label.to_s
+        scopes[index].to_s == "session" ? label.to_s.sub(/for (?:the|delegate .*'s) session\z/, "for delegate #{who}'s session") : label.to_s
       end
     end
 

data/lib/samagotchi/tool_activity.rb

@@ -45,9 +45,9 @@ module Samagotchi
 
     # A call the guardrails denied, as its saved text reads after the
     # "[tool]" lead (ToolRunner#denied, Guardrails::Verdict#deny_text): a
-    # rule's or hook's deny, a legacy hook veto, or the user declining (or
-    # cancelling) the approval.
-    GUARDRAIL_DENIED = /\AError: (?:(?:denied|blocked) by guardrail\b|The (?:user declined this call|approval was cancelled)\b.*? It needed approval \()/m
+    # rule's or hook's deny, a legacy hook veto, or the user or a parent agent
+    # declining (or cancelling) the approval.
+    GUARDRAIL_DENIED = /\AError: (?:(?:denied|blocked) by guardrail\b|The (?:(?:user|parent agent) declined this call|approval was cancelled)\b.*? It needed approval \()/m
 
     # Whether a saved result text (#saved_result_text) is a guardrail's
     # deny: "blocked" as live (its activity's status), not "error", for a

data/lib/samagotchi/tool_output_cut.rb

@@ -35,9 +35,20 @@ module Samagotchi
     REF_WHAT = { "task_wait" => "the task's whole output", "delegate" => "the child's whole reply",
                  "delegate_result" => "the child's whole reply" }.freeze
 
+    # How every cut marker line opens: "[cut: N of M chars" or "[cut: N
+    # chars" - head_line, memory_line and the gap lines all end the result
+    # with one of these.
+    CUT_OPEN = /\[cut: \d+(?: of \d+)? chars/
+
     # A head cut's last line (head_line), as LLMContextStale recognizes a
     # partial read by it. Kept in sync with head_line by its spec.
-    HEAD_CUT = /\[cut: \d+ of \d+ chars; read it in parts\]\z/
+    HEAD_CUT = /#{CUT_OPEN}; read it in parts\]\z/
+
+    # Is +line+ one of those markers on its own line? A body that only
+    # mentions "[cut: ..." is not a cut result.
+    def self.cut_marker_line?(line)
+      line.to_s.strip.match?(/\A#{CUT_OPEN}[^\n]*\]\z/)
+    end
 
     # What a web row keeps of a tool's output, on a reload
     # (MessageParts) and a mid-turn join (Bridge::TurnAccumulator): the