samagotchi 0.33.0 → 0.35.0

data/lib/samagotchi/guardrails/child_boundary.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "outside"
+require_relative "protected_paths"
+require_relative "shell_lex"
+require_relative "shell_paths"
+require_relative "shared_git"
+
+module Samagotchi
+  module Guardrails
+    # A delegate child asks before it changes anything outside its folder
+    # (+root+: the work tree top of its working_directory, never Dir.pwd,
+    # so a child whose worktree is gone still has one). A core check, on in
+    # every guardrails mode and with guardrails.enabled: false, for delegate
+    # sessions only (GuardrailWiring#checks), so ordinary sessions and a
+    # parent's own flows never get it. It asks, once or for the session
+    # (a repo or rule answer would hold in every worktree, for every child),
+    # when:
+    #   write, edit: a path is outside root (Outside: tmp dirs and memory
+    #     files never are);
+    #   execute, task_create: mutating git runs in a dir outside root
+    #     (ShellGitDirs), or a command that isn't read-only starts outside
+    #     root (its cwd:, else Dir.pwd) or names a path in the repository's
+    #     other checkouts (the main one and sibling worktrees) or its
+    #     common git dir; or it runs git that changes what all checkouts
+    #     share, from anywhere (SharedGit: config, update-ref, worktree add,
+    #     stash clear, tags, another branch's delete).
+    # Paths elsewhere in a command (/usr/bin, ~/.gem) don't count, and
+    # read-only commands never ask. Text heuristics: sh -c bodies, scripts
+    # and $(…) aren't looked into.
+    class ChildBoundary
+      RULE = "child-boundary"
+      SOURCE = "core"
+      SCOPES = %w[once session].freeze
+      SHELL_TOOLS = %w[execute task_create].freeze
+
+      # @param root [#call] → String, nil: the child's folder (nil: no check)
+      # @param worktrees [#call] → Array<String>: every checkout of root's
+      #   repository (GitInfo#worktrees); root's own is left out here
+      # @param common_dir [#call] → String, nil: root's common git dir (in
+      #   a bare layout it is in no checkout)
+      # @param branch [#call] → String, nil: the branch checked out in root
+      def initialize(root:, worktrees: -> { [] }, common_dir: -> {}, branch: -> {})
+        @root = root
+        @worktrees = worktrees
+        @common_dir = common_dir
+        @branch = branch
+      end
+
+      # Vote on +verdict+ (its targets).
+      def check(verdict)
+        targets = verdict.targets
+        root = targets && @root.call
+        return verdict unless root && !root.to_s.empty?
+
+        crossing = crosses?(targets, root) or return verdict
+
+        what = crossing == :shared ? "git state every checkout of the repository shares, from its folder" : "something outside its folder"
+        verdict.ask!("a delegate child changes #{what} #{root}: ask the user",
+                     scopes: SCOPES, rule: RULE, source: SOURCE, decided_by: "core")
+      end
+
+      private
+
+      def crosses?(targets, root)
+        case targets.tool
+        when "write", "edit" then targets.paths.any? { |path| Outside.outside?(path, root: root) }
+        when *SHELL_TOOLS then shell_crosses?(targets, root)
+        else false
+        end
+      end
+
+      def shell_crosses?(targets, root)
+        return true if targets.git_dirs.any? { |dir| dir.is_a?(String) && Outside.outside?(dir, root: root) }
+        return :shared if SharedGit.changes?(targets.command, own_branch: @branch.call)
+        return false if targets.read_only?
+        return true if targets.cwd && Outside.outside?(targets.cwd, root: root)
+
+        names_other_checkout?(targets.command, targets.cwd, root)
+      end
+
+      # Whether a word of +command+ resolves into another checkout of the
+      # repository (and not into root, which may sit inside the main one).
+      def names_other_checkout?(command, cwd, root)
+        real_root = ProtectedPaths.real(root)
+        others = [*@worktrees.call, @common_dir.call].compact.map { |dir| ProtectedPaths.real(dir) } - [real_root]
+        return false if others.empty?
+
+        walk = ShellPaths::Walk.new(cwd, Dir.home, ENV)
+        ShellLex.simple_commands(ShellLex.lex(command.to_s)).any? do |words|
+          walk.step(words).any? do |_word, path|
+            next false unless path
+
+            real = ProtectedPaths.real(path)
+            !ShellPaths.within?(real, real_root) && others.any? { |dir| ShellPaths.within?(real, dir) }
+          end
+        end
+      rescue ArgumentError, EncodingError
+        false
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/context.rb

@@ -50,6 +50,38 @@ module Samagotchi
       def common_dir(dir) = info(dir)[:common_dir]
       def branch(dir) = info(dir)[:branch]
 
+      # Every checkout of +dir+'s repository that is still there: the main
+      # one (the folder holding a common .git dir that isn't bare) and each
+      # linked worktree (<common dir>/worktrees/*/gitdir names its .git
+      # file; a relative one is relative to that admin dir). Read from the
+      # files, no git process, on every call (not memoized: a worktree
+      # added mid-turn counts at once); [] outside a repo.
+      # @return [Array<String>] absolute folders
+      def worktrees(dir)
+        common = common_dir(dir) or return []
+        self.class.checkouts(common)
+      end
+
+      # @param common [String] an absolute common git dir
+      def self.checkouts(common)
+        main = File.basename(common) == ".git" && !bare?(common) ? [File.dirname(common)] : []
+        linked = Dir[File.join(common, "worktrees", "*", "gitdir")].sort.filter_map do |file|
+          gitdir = File.read(file).strip
+          next if gitdir.empty?
+
+          File.dirname(File.expand_path(gitdir, File.dirname(file)))
+        rescue SystemCallError
+          nil
+        end
+        (main + linked).select { |folder| File.directory?(folder) }.uniq
+      end
+
+      def self.bare?(common)
+        File.read(File.join(common, "config")).match?(/^\s*bare\s*=\s*true\s*$/i)
+      rescue SystemCallError
+        false
+      end
+
       private
 
       def info(dir)

data/lib/samagotchi/guardrails/shared_git.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "shell_lex"
+require_relative "shell_git_dirs"
+
+module Samagotchi
+  module Guardrails
+    # Whether a shell command runs git that changes what every checkout of
+    # the repository shares (its common git dir), wherever it runs: from a
+    # worktree these reach the main checkout and the siblings too.
+    #   config     a write without --worktree (or --file/--blob, whose
+    #              path the caller checks); --get, --list, `config get`
+    #              and a lone key only read
+    #   update-ref always
+    #   worktree   add, remove, move, prune, lock, unlock, repair
+    #   stash      drop, clear, pop (one stash list for all)
+    #   tag        creating or deleting one (not listing or verifying)
+    #   branch     delete, force or a forced move/copy, of a branch other
+    #              than +own_branch+ (any, when that is unknown)
+    # Pure text, as ShellGitDirs: sh -c, aliases and $(…) get through.
+    module SharedGit
+      WORKTREE_CHANGES = %w[add remove move prune lock unlock repair].freeze
+      STASH_CHANGES = %w[drop clear pop].freeze
+      CONFIG_READS = %w[--get --get-all --get-regexp --get-urlmatch --list -l --get-color --get-colorbool].freeze
+      CONFIG_WRITES = %w[--unset --unset-all --add --replace-all --rename-section --remove-section -e --edit].freeze
+      CONFIG_OWN_FILE = %w[--worktree -f --file --blob].freeze
+      # config options that take the next word as their value.
+      CONFIG_VALUES = %w[--type --default --comment -f --file --blob].freeze
+      TAG_READS = %w[-l --list -n -v --verify --contains --no-contains --points-at --merged --no-merged].freeze
+      TAG_WRITES = %w[-d --delete -f --force -a --annotate -s --sign -u -m -F].freeze
+      BRANCH_DELETE = %w[-d -D --delete].freeze
+      BRANCH_MOVE = %w[-m --move -c --copy].freeze
+      BRANCH_FORCED_MOVE = %w[-M -C].freeze
+
+      module_function
+
+      # @param command [String]
+      # @param own_branch [String, nil] the branch checked out where the
+      #   session works
+      def changes?(command, own_branch: nil)
+        ShellLex.simple_commands(ShellLex.lex(command.to_s)).any? do |words|
+          next false unless words.is_a?(Array)
+
+          sub, args = git_call(words)
+          sub && changes_shared?(sub, args, own_branch)
+        end
+      rescue ArgumentError, EncodingError
+        false
+      end
+
+      # [subcommand, its args] of a git simple command, or nil.
+      def git_call(words)
+        words = words.drop_while { |w| w.match?(/\A[A-Za-z_]\w*=/) || ShellGitDirs::PREFIXES.include?(w) }
+        verb = words.first
+        return nil unless verb == "git" || verb.to_s.end_with?("/git")
+
+        args = words.drop(1).grep_v(ShellLex::REDIRECT)
+        until args.empty?
+          arg = args.shift
+          if ShellGitDirs::VALUE_OPTIONS.include?(arg) then args.shift
+          elsif !arg.start_with?("-") then return [arg, args]
+          end
+        end
+        nil
+      end
+
+      def changes_shared?(sub, args, own_branch)
+        case sub
+        when "config" then config_writes?(args)
+        when "update-ref" then true
+        when "worktree" then WORKTREE_CHANGES.include?(args.first)
+        when "stash" then STASH_CHANGES.include?(args.first)
+        when "tag" then tag_changes?(args)
+        when "branch" then branch_changes?(args, own_branch)
+        else false
+        end
+      end
+
+      def config_writes?(args)
+        return false if args.any? { |a| CONFIG_OWN_FILE.include?(a) || a.start_with?("--file=", "--blob=") }
+        return false if %w[get list].include?(args.first)
+        return true if %w[set unset rename-section remove-section edit].include?(args.first)
+        return false if args.any? { |a| CONFIG_READS.include?(a) }
+        return true if args.any? { |a| CONFIG_WRITES.include?(a) }
+
+        operands(args, CONFIG_VALUES).size >= 2
+      end
+
+      def tag_changes?(args)
+        return true if args.any? { |a| TAG_WRITES.include?(a) }
+        return false if args.empty? || args.any? { |a| TAG_READS.include?(a) || a.start_with?("--list=", "--contains=", "--points-at=") }
+
+        !operands(args, []).empty?
+      end
+
+      # The branches a branch command deletes or overwrites (a plain -m/-c
+      # only moves its source; its new name doesn't exist yet).
+      def branch_changes?(args, own_branch)
+        names = operands(args, %w[-u --set-upstream-to -t --track])
+        targets = if args.any? { |a| BRANCH_DELETE.include?(a) } then names
+                  elsif args.any? { |a| BRANCH_FORCED_MOVE.include?(a) } then names.size >= 2 ? names : [own_branch, *names]
+                  elsif args.any? { |a| BRANCH_MOVE.include?(a) } then names.size >= 2 ? [names.first] : []
+                  elsif args.any? { |a| %w[-f --force].include?(a) } then names.first(1)
+                  else []
+                  end
+        targets.any? { |name| own_branch.nil? || name != own_branch }
+      end
+
+      def operands(args, value_options)
+        rest = args.dup
+        found = []
+        until rest.empty?
+          arg = rest.shift
+          if value_options.include?(arg) then rest.shift
+          elsif arg == "--" then found.concat(rest)
+                                 break
+          elsif !arg.start_with?("-") then found << arg
+          end
+        end
+        found
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/verdict.rb

@@ -13,9 +13,10 @@ module Samagotchi
       STRICTNESS = { allow: 0, ask: 1, deny: 2 }.freeze
       # Rules that ask about chi's own config and hooks: the core
       # ProtectedPaths asks and the guardrails bundle's shell rule; and a
-      # command source for attached context (it runs later, ungated). Only
-      # the user may allow them (ParentApprovals).
-      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd].freeze
+      # command source for attached context (it runs later, ungated); chi
+      # broadcast, which is the user's. Only the user may allow them
+      # (ParentApprovals).
+      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd chi-broadcast].freeze
       SCOPES = %w[once session repo rule].freeze
       DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."
 

data/lib/samagotchi/guardrails.rb

@@ -12,6 +12,7 @@ require_relative "guardrails/approval"
 require_relative "guardrails/approvals"
 require_relative "guardrails/protected_paths"
 require_relative "guardrails/scratch_writes"
+require_relative "guardrails/child_boundary"
 require_relative "guardrails/load_failures"
 require_relative "guardrails/rules"
 require_relative "guardrails/gate"

data/lib/samagotchi/hooks/registry.rb

@@ -83,8 +83,9 @@ module Samagotchi
 
     # What a hook can do beyond reading its event: the Engine's
     # callables, each given the hook's label. +notify+ takes
-    # (text:, level:, hook:) and shows one line to the user; +ask_user+
-    # takes (question:, options:, header:, allow_freeform:, hook:) and
+    # (text:, level:, hook:, and fallback_for: when the hook gave one: what
+    # the line stands in for, Engine#hook_notify) and shows one line to the
+    # user; +ask_user+ takes (question:, options:, header:, allow_freeform:, hook:) and
     # returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
     # cancels the running turn (true when it did); +steer+ takes (text:,
     # hook:) and puts the text into the running turn (Engine#steer, true
@@ -239,7 +240,10 @@ module Samagotchi
       #
       # All procs get the same hash, so event[:hook] is set before each one;
       # the helpers are set once per fire and read event[:hook] when called:
-      #   event[:notify].call(text, level: :info)   one line to the user
+      #   event[:notify].call(text, level: :info, fallback_for: nil)   one line
+      #     to the user; fallback_for: :display marks a line that stands in
+      #     for the answer's display (event[:present]), which a UI that
+      #     renders the display's links leaves out (Engine#hook_notify)
       #   event[:ask_user].call(question:, options:, header: nil, allow_freeform: false)
       #     -> {selected:, freeform:, selected_indices:} or nil (no one to
       #     ask, cancelled, bad options)
@@ -330,8 +334,10 @@ module Samagotchi
       def with_runtime(event)
         return unless event.is_a?(Hash)
 
-        event[:notify] ||= lambda { |text, level: :info|
-          @runtime&.notify&.call(text: text.to_s, level: level, hook: event[:hook])
+        event[:notify] ||= lambda { |text, level: :info, fallback_for: nil|
+          notice = { text: text.to_s, level: level, hook: event[:hook] }
+          notice[:fallback_for] = fallback_for unless fallback_for.nil?
+          @runtime&.notify&.call(**notice)
           nil
         }
         event[:ask_user] ||= lambda { |question:, options:, header: nil, allow_freeform: false|

data/lib/samagotchi/kernel_loop.rb

@@ -13,6 +13,7 @@ require_relative "client"
 require_relative "llm/errors"
 require_relative "log"
 require_relative "empty_answer_retry"
+require_relative "cut_policy"
 require_relative "thinking"
 require_relative "hooks"
 require_relative "pending_input_queue"
@@ -444,31 +445,17 @@ module Samagotchi
                                      messages: AnswerDisplay.strip_all(turn.conversation).map(&:dup).freeze })
     end
 
-    # A generation a plugin cut is an empty answer made early. Queued input
-    # (a user's line, a plugin's steer) goes in first, with or without a
-    # retry left, and spends no attempt: the model answers it. A steer's cut
-    # (Engine#cut_for_steer) with nothing queued (its message was taken at
-    # a boundary already) is asked again as is. Else it is asked again with
-    # its own nudge while the retry budget lasts, else the turn ends as
-    # cancelled (hook), with nothing salvaged and without the spent nudge.
-    # A Stop that came right after the cut is a plain cancel. Returns :next
-    # or the turn's result.
+    # A cut generation (CutPolicy): a Stop after it raises as any cancel,
+    # the turn going on is :next, the hook ending is the turn's result.
     def after_cut(turn, generation)
       cut = generation.cut
-      raise Client::RequestCancelled, turn.cancel_controller.reason if turn.cancel_controller.cancelled?
+      outcome = CutPolicy.decide(cut: cut, cancel_controller: turn.cancel_controller, empty_retry: turn.empty_retry,
+                                 conversation: turn.conversation, iteration: turn.iteration, emit: turn.emit,
+                                 inject: -> { inject_pending_input!(turn) },
+                                 finish_reason: "stopped", thinking_chars: generation.streamed_thinking)
+      raise Client::RequestCancelled, turn.cancel_controller.reason if outcome.stopped?
+      return :next if outcome.again?
 
-      # The row under the cut step, above the message it was cut for.
-      emit(turn, type: :steer_cut, iteration: turn.iteration, source: cut[:source].to_s) if cut[:steer]
-      return :next if inject_pending_input!(turn) || cut[:steer]
-
-      if turn.empty_retry.left?
-        turn.empty_retry.nudge!(turn.conversation, TurnNote.cut_retry(cut[:by], cut[:reason]),
-                                emit: turn.emit, iteration: turn.iteration, finish_reason: "stopped",
-                                thinking_chars: generation.streamed_thinking, stopped_by: cut[:by])
-        return :next
-      end
-      turn.empty_retry.drop_nudge!(turn.conversation)
-      turn.cancel_controller.cancel!(:hook, cut)
       emit(turn, type: :generation_cancelled, iteration: turn.iteration, reason: :hook, stopped_by: cut[:by])
       cancelled_result(turn.conversation, tool_activity: turn.tool_activity, reason: :hook, partial_assistant_text: "")
     end

data/lib/samagotchi/llm/chat_loop.rb

@@ -10,6 +10,7 @@ require_relative "openai_chat"
 require_relative "native_tool_normalizer"
 require_relative "../kernel_loop"
 require_relative "../answer_display"
+require_relative "../cut_policy"
 require_relative "../context_status"
 require_relative "../context_window"
 require_relative "../context_note"
@@ -396,30 +397,18 @@ module Samagotchi
                               thinking_chars: response.reasoning.to_s.length)
         end
 
-        # A generation a plugin cut (stop_generation) is an empty answer made
-        # early. Queued input (a user's line, a plugin's steer) goes in
-        # first, with or without a retry left, and spends no attempt. A
-        # steer's cut (Engine#cut_for_steer) with nothing queued is asked
-        # again as is. Else it is asked again with its own nudge while the
-        # retry budget lasts, else the turn ends as cancelled (hook), with
-        # nothing salvaged and without a spent nudge. A Stop that came right
-        # after the cut is a plain cancel. Returns :retry, or the turn's
-        # result.
+        # A cut generation (CutPolicy): a Stop after it ends the turn as
+        # any cancel, the turn going on is :retry, the hook ending is the
+        # turn's result.
         def after_cut(iteration, response)
-          return canceled(iteration, @cancel_controller.reason) if @cancel_controller.cancelled?
+          outcome = CutPolicy.decide(cut: response.cut, cancel_controller: @cancel_controller, empty_retry: @empty_retry,
+                                     conversation: @conversation, iteration: iteration, emit: method(:emit),
+                                     inject: -> { inject_pending_input(iteration) },
+                                     finish_reason: response.finish_reason,
+                                     thinking_chars: response.reasoning.to_s.length)
+          return canceled(iteration, @cancel_controller.reason) if outcome.stopped?
+          return :retry if outcome.again?
 
-          # The row under the cut step, above the message it was cut for.
-          emit(type: :steer_cut, iteration: iteration, source: response.cut[:source].to_s) if response.cut[:steer]
-          return :retry if inject_pending_input(iteration) || response.cut[:steer]
-
-          if @empty_retry.left?
-            @empty_retry.nudge!(@conversation, TurnNote.cut_retry(response.cut[:by], response.cut[:reason]),
-                                emit: method(:emit), iteration: iteration, finish_reason: response.finish_reason,
-                                thinking_chars: response.reasoning.to_s.length, stopped_by: response.cut[:by])
-            return :retry
-          end
-          @empty_retry.drop_nudge!(@conversation)
-          @cancel_controller.cancel!(:hook, response.cut)
           canceled(iteration, :hook)
         end
 

data/lib/samagotchi/log_subscriber.rb

@@ -147,7 +147,7 @@ module Samagotchi
     # hook's, not the user's or the model's).
     def on_hook_notice(event)
       level = event[:level].to_s == "warn" ? :warn : :info
-      log(level, :hook_notice, hook: event[:hook], msg: event[:text].to_s[0, 300])
+      log(level, :hook_notice, hook: event[:hook], fallback_for: event[:fallback_for], msg: event[:text].to_s[0, 300])
     end
 
     # after_turn hooks presented the answer (AnswerDisplay): its size only

data/lib/samagotchi/memory_bundle/builder.rb

@@ -208,7 +208,8 @@ module Samagotchi
             requires_chi: requires_chi,
             needs: needs,
             scripts: scripts_to_copy.transform_values { |src| "sha256:#{Digest::SHA256.hexdigest(File.binread(src))}" },
-            context_providers: context_providers
+            context_providers: context_providers,
+            file_descriptions: file_descriptions(prov_data, files_map)
           )
 
           case format
@@ -276,6 +277,18 @@ module Samagotchi
                            .select { |_, path| File.file?(path) }
       end
 
+      # The descriptions the installed bundle's record keeps for the files
+      # being built (its manifest's files: mappings), so a rebuild writes
+      # them back; {} without a record.
+      def file_descriptions(prov_data, files_map)
+        return {} unless prov_data && prov_data[:files].is_a?(Hash)
+
+        prov_data[:files].each_with_object({}) do |(key, entry), acc|
+          text = entry.is_a?(Hash) ? entry[:description].to_s : ""
+          acc[key.to_s] = text if files_map.key?(key.to_s) && !text.empty?
+        end
+      end
+
       # Without an allowlist, a memory another installed bundle owns (its
       # record lists it) isn't the user's to share: left out, one line
       # each. The bundle being built (same name) keeps its own.

data/lib/samagotchi/memory_bundle/installer.rb

@@ -92,6 +92,7 @@ module Samagotchi
         FileUtils.mkdir_p(target_dir)
 
         # Copy .md files and update index for each.
+        @file_descriptions = manifest&.file_descriptions || {}
         all_files_in_bundle = []
         provenance = Provenance.new(name: @name)
         existing_provenance = provenance.read
@@ -421,7 +422,8 @@ module Samagotchi
             needs: manifest.needs,
             conflicts: @conflicts.keys,
             scripts_files: scripts_for_provenance,
-            context_providers: manifest.context_providers
+            context_providers: manifest.context_providers,
+            file_descriptions: manifest.file_descriptions
           )
         end
 
@@ -695,7 +697,9 @@ module Samagotchi
           # Index lines use the entry name (as memory_write does); drop the
           # legacy "name.md" line older installs wrote.
           IndexUpdater.remove_index(scope, file_key) unless entry_name == file_key
-          IndexUpdater.update_index(scope, entry_name, byte_count, source: owned ? @name : nil)
+          # A manifest's description: for the file; nil keeps the line's.
+          description = owned ? @file_descriptions&.[](file_key) : nil
+          IndexUpdater.update_index(scope, entry_name, byte_count, description, source: owned ? @name : nil)
         rescue StandardError => e
           # Not fatal (the file is in place): a warning says so.
           @warnings << "index.md: line for #{entry_name} not updated (#{e.message})"

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -16,7 +16,9 @@ module Samagotchi
     #   description: "…"       # optional
     #   files:
     #     identity.md: sha256:abc123...
-    #     commit_preferences.md: sha256:def456...
+    #     skill_x.md:          # or a mapping: the description is the
+    #       sha256: sha256:def456...   #   memory's index.md line
+    #       description: "Use when …"
     #   plugin:                # optional — the bundle's plugin.rb (docs/plugins.md)
     #     file: plugin.rb
     #     sha256: sha256:0a1b...
@@ -50,7 +52,9 @@ module Samagotchi
       # A bundle name, as `chi bundle install <name>` takes a shipped one.
       BUNDLE_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
 
-      attr_reader :name, :version, :scope, :description, :files, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes,
+      # files: name → "sha256:<hex>" (both forms); file_descriptions: name →
+      # the description a mapping gave, for the files that have one.
+      attr_reader :name, :version, :scope, :description, :files, :file_descriptions, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes,
                   :scripts, :context_providers
 
       def initialize(path:)
@@ -62,6 +66,7 @@ module Samagotchi
         @description = (raw["description"] || "").to_s
         @files    = parse_files(raw["files"] || {})
         @hooks    = parse_hooks(raw["hooks"] || {})
+        @file_descriptions = parse_file_descriptions(raw["files"])
         @trust_level = (raw["trust_level"] || "experimental").to_s
         @plugin = parse_plugin(raw["plugin"])
         @requires_chi = parse_requires_chi(raw["requires_chi"])
@@ -123,8 +128,9 @@ module Samagotchi
       end
 
       # Writes a fresh manifest.yml from computed checksums at `dir`.
+      # +file_descriptions+ (name → text) writes those files as mappings.
       def self.write(dir:, name:, version:, files:, scope: nil, description: "", hooks: nil, trust_level: nil,
-                     plugin: nil, requires_chi: nil, needs: nil, scripts: {}, context_providers: [])
+                     plugin: nil, requires_chi: nil, needs: nil, scripts: {}, context_providers: [], file_descriptions: {})
         FileUtils.mkdir_p(dir)
         manifest = {
           "name" => name,
@@ -132,7 +138,10 @@ module Samagotchi
           "description" => description
         }
         manifest["scope"] = scope if scope
-        manifest["files"] = files # { "file.md" => "sha256:abc..." }
+        manifest["files"] = files.to_h do |key, sha| # { "file.md" => "sha256:abc..." }
+          text = file_descriptions[key].to_s.strip
+          [key, text.empty? ? sha : { "sha256" => sha, "description" => text }]
+        end
         if hooks && !hooks.empty?
           # Normalize hooks to string-keyed with sha256 prefix preserved
           manifest["hooks"] = hooks.transform_keys(&:to_s).transform_values do |v|
@@ -205,7 +214,7 @@ module Samagotchi
         raw.each_with_object({}) do |(k, v), acc|
           next unless k.is_a?(String) && !k.empty?
 
-          str = v.to_s
+          str = (v.is_a?(Hash) ? v["sha256"] : v).to_s
           acc[k] = if str.start_with?("sha256:")
                      str
                    else
@@ -214,6 +223,18 @@ module Samagotchi
         end
       end
 
+      # The descriptions of the files: entries given as a mapping.
+      def parse_file_descriptions(raw)
+        return {} unless raw.is_a?(Hash)
+
+        raw.each_with_object({}) do |(k, v), acc|
+          next unless k.is_a?(String) && v.is_a?(Hash)
+
+          text = v["description"].to_s.strip
+          acc[k] = text unless text.empty?
+        end
+      end
+
       # plugin: {file:, sha256:} → {file:, sha256:} (sha "" when not given),
       # or nil; a file that isn't a plain .rb name is a validation error.
       def parse_plugin(raw)

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -140,7 +140,7 @@ module Samagotchi
       # @param context_providers [Array<ContextProviders::Provider>]
       def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
                 guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil,
-                scripts_files: {}, context_providers: [])
+                scripts_files: {}, context_providers: [], file_descriptions: {})
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -158,6 +158,7 @@ module Samagotchi
           File.write(File.join(bases_dir, file_key), content)
           merged_entries[file_key] = { checksum: checksum }
           merged_entries[file_key][:conflict] = true if conflicts.include?(file_key.to_s)
+          merged_entries[file_key][:description] = file_descriptions[file_key.to_s] if file_descriptions[file_key.to_s]
         end
 
         # Prune stale base snapshots for files no longer in the bundle.

data/lib/samagotchi/memory_paths.rb

@@ -59,6 +59,16 @@ module Samagotchi
       dot_git && File.dirname(dot_git)
     end
 
+    # The git dir of the work tree holding +cwd+: .git itself in a main
+    # checkout, the worktree's own dir under .git/worktrees in a linked one
+    # (where HEAD is that worktree's); nil outside any repository.
+    def git_dir(cwd = Dir.pwd)
+      dot_git = find_dot_git(cwd)
+      return nil unless dot_git
+
+      File.directory?(dot_git) ? dot_git : gitdir_from_file(dot_git)
+    end
+
     # Is +cwd+ inside a git repository (a .git somewhere above it)?
     def in_repo?(cwd = Dir.pwd)
       !find_dot_git(cwd).nil?