samagotchi 0.149.0 → 0.150.0

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

@@ -1,10 +1,10 @@
 ---
 name: dev
-version: 0.7.5
+version: 0.7.6
 scope: system
 description: "Developer tools"
 trust_level: reviewed
-requires_chi: ">= 0.149.0"
+requires_chi: ">= 0.150.0"
 includes:
 - known-names
 - mcp

data/lib/samagotchi/bundles/github-pr/manifest.yml

@@ -1,17 +1,17 @@
 ---
 name: github-pr
-version: 0.6.2
+version: 0.6.3
 scope: system
 description: Proposes the branch's open GitHub pull request to a session, attached once you mention it (#N, the branch or its URL), and attaches any PR URL with chi context add or the web's "+ URL"; the agent gets a note when reviews, comments, checks or its state change; in the web, a path:line in an answer links to that line of the PR; the auto_attach setting can attach the PR at once instead, or do nothing
 trust_level: reviewed
-requires_chi: ">= 0.140.0"
+requires_chi: ">= 0.150.0"
 needs:
 - command: gh
   why: reads the pull request
   hint: brew install gh, then gh auth login
 plugin:
   file: plugin.rb
-  sha256: sha256:114e999c49d4d427b7570e3f4bec8db5565ee0dd1a99f2f5ec3000748a1aec3a
+  sha256: sha256:82f8c76d38f314c3503eef3a5de0f8c0b20d0bb5bf4a3daebca43b60d00f8c7a
 scripts:
   pr_context.rb: sha256:a883d2780e89c68c0d7b6d5e0fcb22c273f17bb167e79064e0e99db6bd2ee6f0
 context_providers:

data/lib/samagotchi/bundles/github-pr/plugin.rb

@@ -5,6 +5,7 @@ require "json"
 require "open3"
 require "time"
 require "tmpdir"
+require "samagotchi/git_env"
 
 # github-pr: a session on a branch with an open GitHub PR gets the PR
 # proposed as a candidate (docs/context.md, Candidates) when its worker
@@ -334,7 +335,7 @@ class Plugin
 
   # stdout of a command that succeeded within COMMAND_SECONDS, else nil.
   def run(ctx, *command, chdir: ctx.cwd)
-    Open3.popen2(*command, chdir: chdir, err: File::NULL, pgroup: true) do |stdin, stdout, wait|
+    Open3.popen2(Samagotchi::GitEnv::UNSET, *command, chdir: chdir, err: File::NULL, pgroup: true) do |stdin, stdout, wait|
       stdin.close
       reader = Thread.new { stdout.read }
       unless wait.join(COMMAND_SECONDS)

data/lib/samagotchi/bundles/known-names/hooks/known_names.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "samagotchi/git_env"
+
 # A before_tool_call guard against near-misses of protected identifiers in
 # a tool call's command or paths: the user's home folder name, login, git
 # name and email, the repo name, and any names from config. A local model
@@ -187,7 +189,7 @@ class KnownNames
   end
 
   def git_config(root, key)
-    IO.popen(["git", "-C", root, "config", "--get", key], err: File::NULL, &:read).to_s.strip
+    IO.popen(Samagotchi::GitEnv::UNSET, ["git", "-C", root, "config", "--get", key], err: File::NULL, &:read).to_s.strip
   rescue StandardError
     ""
   end

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

@@ -1,6 +1,7 @@
 ---
 name: known-names
-version: 0.1.8
+version: 0.1.9
+requires_chi: ">= 0.150.0"
 scope: system
 description: Catches a near-miss of a protected name (home folder, login, git name, repo name, names from config) in a tool call and rejects it with the right spelling; mode ask / correct optional
 trust_level: reviewed
@@ -8,7 +9,7 @@ files:
   known_names.md: sha256:d5348b95b6c655017b541910b36e384220da280818160201f6ec9a50e1e4287c
 hooks:
   known_names.rb:
-    sha256: sha256:a851637e9292f825dc5b8877cd060184de976aa4297b114dab412a89fa3cf091
+    sha256: sha256:d7eed0dd0f418d8099a147ed124c6e6062b8c752035dd6b5aa5e926e29941c8b
     event: before_tool_call
     on_error: log
     priority: 50

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -2,6 +2,7 @@
 
 # Loaded through module_eval: it requires what it uses.
 require "open3"
+require "samagotchi/git_env"
 require "samagotchi/ref"
 
 # An after_turn (and question_asked) hook that links the source refs the
@@ -621,8 +622,7 @@ class SourceLinks
   end
 
   def read_remote(dir, name)
-    out, status = Open3.capture2({ "GIT_DIR" => nil, "GIT_WORK_TREE" => nil },
-                                 "git", "-C", dir, "remote", "get-url", name, err: File::NULL)
+    out, status = Open3.capture2(Samagotchi::GitEnv::UNSET, "git", "-C", dir, "remote", "get-url", name, err: File::NULL)
     unless status.success?
       Samagotchi::Log.debug(:hooks, "source_links_no_remote", remote: name, exit: status.exitstatus)
       return nil

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

@@ -1,15 +1,15 @@
 ---
 name: source-links
-version: 0.6.2
+version: 0.6.3
 scope: system
 description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, refs in a waiting question's reply, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
-requires_chi: ">= 0.98.0"
+requires_chi: ">= 0.150.0"
 files:
   source_links.md: sha256:ace01a0f7c308a0ae54ece714c31c0e6d7a49c372d98111030e6d268320bed3a
 hooks:
   source_links.rb:
-    sha256: sha256:7e3fafb843f1a9006b1a42f4ec647b41a358d814515cd0be73b60eb08b898992
+    sha256: sha256:21d7a9f7c381c653b126b625feed0e0b6422eaa84c8dfe716b6c5b41644a33b3
     events: [after_turn, question_asked]
     on_error: log
     priority: 90

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.149.0
+version: 0.150.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
-  self_map.md: sha256:c9ece2d56c63fb0f9842963cb0b123e89abadec888645d7a765a2578ceefee3a
+  self_map.md: sha256:e695f78f858c29ccfef2ed6f9d6dd86d0ec067ed704a5a1956c01e53617948a1
   config_modification_protocol.md: sha256:8896d1d364ce835040f69b504518d43dbdf959b93fdd9b10f87a8de61cae84a8
-  memory_guide.md: sha256:64c3fa0703a3bdd8ae33b9e7cb341caa88a205c289d767f4877b38dfa6629fda
+  memory_guide.md: sha256:bfe9f13e8a6c929056fe531c4c74c7e05d0f17f025191c1a111c8e7dfd224fd6
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

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

@@ -114,9 +114,9 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 | Command | Purpose |
 |---------|---------|
 | `install <source> [--scope system\|project] [--force]` | Install from dir/zip/tar.gz/git URL. `--force` overwrites existing entries, otherwise skips them; a skipped file stays the user's (not recorded, never upgraded or removed by the bundle). Writes provenance to `.bundles/<name>/` (base snapshots + `manifest.json`) and updates `index.md`. Warns on double-brace placeholders and checksum mismatches (strict mode). |
-| `upgrade <source> [--force] [--dry-run] [--agent]` | 3-way merge upgrade (base vs current vs incoming) per `Merger.classify`: `install` (new file), `noop` (current==incoming), `fast_forward` (current==base, not edited → auto-update), `keep` (incoming==base → preserve local edits), `conflict` (both edited → warn, needs `--force` or interactive `memory_write` resolution). Pruned files (removed from new bundle) are kept if locally edited, otherwise warned. |
+| `upgrade <source> [--force] [--dry-run] [--agent]` | 3-way merge upgrade (base vs current vs incoming) per `Merger::Upgrade#outcome` (`Merger.classify`, then a text merge where both sides changed): `install` (new file), `noop` (current==incoming), `fast_forward` (current==base, not edited → auto-update), `keep` (incoming==base → preserve local edits), `merged` (both edited, a text merge with `git` comes out clean → the file takes it, the old one goes to the bundle trash, and entries both sides added under a `Changelog` heading are kept), `conflict` (both edited, a real conflict, or no `git` or base → the file stays untouched and marked, reported as `X stays behind 0.8.0: …` with why and what it missed, needs a retry, `--force`, which copies it to the trash first, or interactive `memory_write` resolution). A marked file is retried at the same version: the system bundle's at each chi start and on `chi update`, another shipped bundle's on `chi update`, any other bundle's on `chi bundle upgrade`. A file marked by an older chi merges normally when its recorded base is a version chi shipped (an installed samagotchi gem still has it); otherwise it merges only if the bundle takes out or rewords no line it still holds, and if it does, it stays behind until resolved by hand, with `--agent` or with `--force`, and the retry can't fix that. Pruned files (removed from new bundle) are kept if locally edited, otherwise warned. |
 | `uninstall <bundle> [--force]` | Moves the bundle's memory files to `.bundles/.trash/<bundle>-<time>/` (refuses locally edited ones unless `--force`; keeps a file another installed bundle also lists), removes their `index.md` lines, deletes the provenance dir. |
-| `status [<bundle>]` | Provenance + per-file `ok|modified|missing|no-index` vs stored checksum and base snapshot; a model overlay (`<name>.<key>.md`) has no index line and reads `ok (model overlay)`. |
+| `status [<bundle>]` | Provenance + per-file `ok|modified|missing|unreadable|no-index` vs stored checksum and base snapshot, and what stays behind or merged at a chi start; `issues=` counts files behind, missing or unreadable, not edits; a model overlay (`<name>.<key>.md`) has no index line and reads `ok (model overlay)`. |
 | `diff <bundle> [file]` | Prints `base` (provenance snapshot) vs `current` (on-disk) for each file. |
 | `list` | Lists installed bundles (`name v<version> scope files installed_at`, plus the shipped version when newer) and the bundles shipped with chi that are not installed (`install <name>` installs one), grouped under their profile; an installed profile shows `includes=` and `left out=`. |
 | `build [--scope system\|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]` | **Inverse of install** — builds a shareable bundle from local memories and installed hooks. Infers `zip` vs `dir`/`tar.gz` from `--out` extension; default `chi_system_memories.zip` (system) or `chi_<repo>_memories.zip` (project, named after the project root) v`1.0.0` in `Dir.pwd`. `FILES...` is an optional allowlist of memory basenames (`identity` or `identity.md`); if omitted, all `*.md` except `index.md`/hidden/non-md and the memories other installed bundles own (each named in a `Left out` line) are included. Installed hooks are copied to `hooks/` with their manifest metadata. Computes `sha256:` checksums and writes `manifest.yml` via `Manifest.write`. No provenance write. |
@@ -138,7 +138,7 @@ chi bundle install https://github.com/org/bundle.git#v1.2.0 --scope system --for
 
 # check what would change and upgrade
 chi bundle upgrade ./my-bundle --dry-run
-chi bundle upgrade ./my-bundle  # auto-merges, warns on conflicts
+chi bundle upgrade ./my-bundle  # merges your edits, warns on a real conflict
 
 # share again after editing
 chi bundle build --scope system --out updated.zip
@@ -155,9 +155,9 @@ chi bundle build --scope system --out updated.zip
 2. **Prefer project scope** for repo decisions; `system` for cross-project identity/preferences.
 3. **One concept per file:** small files merge and share better than monoliths.
 4. **Use bundles for sharing:** `build` → zip → share → `install`. Do not copy raw `~/.config` paths in docs — give `chi bundle install <url>` instructions.
-5. **Respect local edits:** installs skip existing files by default; use `--force` only when the user explicitly wants overwrite. Upgrades preserve edits (`keep`) or report `conflict` — guide the user to resolve via `memory_read`/`memory_write` or `chi bundle diff <bundle>` + `--force`.
+5. **Respect local edits:** installs skip existing files by default; use `--force` only when the user explicitly wants overwrite. Upgrades preserve edits (`keep`, `merged`) or report `conflict`, leaving the file behind — guide the user to resolve via `memory_read`/`memory_write` or `chi bundle diff <bundle>` + `--force`.
 6. **Keep secrets out:** never write tokens/keys to memories — they are plain files and go into bundles.
 
 ## Current system bundle
 
-`samagotchi-system` (`lib/samagotchi/bundles/system/manifest.yml`) ships `identity.md` + `self_map.md` + `config_modification_protocol.md` + `delegated.md` + this guide itself. It is auto-installed/upgraded on first `Engine` creation (`SystemBundle.ensure!`) — no manual install needed. Its files are managed by chi: a newer chi upgrades them (a 3-way merge keeps local edits and reports conflicts), so put your own preferences in separate memories rather than editing these.
+`samagotchi-system` (`lib/samagotchi/bundles/system/manifest.yml`) ships `identity.md` + `self_map.md` + `config_modification_protocol.md` + `delegated.md` + this guide itself. It is auto-installed/upgraded on first `Engine` creation (`SystemBundle.ensure!`) — no manual install needed. Its files are managed by chi: a newer chi upgrades them (a text merge keeps local edits, and a real conflict leaves the file behind), so put your own preferences in separate memories rather than editing these.

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

@@ -83,7 +83,7 @@
   `file:line`. Read the source `chi self` reports, not some other checkout on disk.
 - Installed gem files and bundled memories (`identity`, `memory_guide`,
   `config_modification_protocol`, `self_map`, `delegated`) are managed: don't edit them
-  (local edits conflict on upgrade).
+  (an upgrade merges local edits when it can, and a real conflict leaves the file behind).
   Put notes in my own memories. Guidance for some models only is a model note
   (`model_notes_<name>`, first line `models: <glob>`; memory_guide); a model-only
   addition to one memory is an overlay on it (`current_model_only: true`), and it

data/lib/samagotchi/chi_home.rb

@@ -6,6 +6,7 @@ require "open3"
 require "rbconfig"
 require "time"
 require_relative "atomic_file"
+require_relative "bundler_env"
 require_relative "installed_gem"
 require_relative "log"
 require_relative "paths"
@@ -33,8 +34,9 @@ module Samagotchi
     # Where `mise` usually is when PATH doesn't have it (launchd's bare PATH).
     MISE_DIRS = ["/opt/homebrew/bin", "/usr/local/bin", File.join(Dir.home, ".local", "bin")].freeze
     # What a probe of another Ruby must not inherit: they would move it off
-    # its own gems.
-    PROBE_UNSET = %w[GEM_HOME GEM_PATH RUBYOPT RUBYLIB BUNDLE_GEMFILE BUNDLE_BIN_PATH].freeze
+    # its own gems. BUNDLER_SETUP alone does: RubyGems requires what it names at
+    # boot, and a bundle with a path then replaces GEM_HOME and GEM_PATH.
+    PROBE_UNSET = (%w[GEM_HOME GEM_PATH] + BundlerEnv::CHILD_RUBY).freeze
     PROBE = "require 'json'; print JSON.generate('ruby' => RbConfig.ruby, 'gem_home' => Gem.dir, " \
             "'gem_path' => Gem.path.join(File::PATH_SEPARATOR))"
     GEMSPEC = /\Asamagotchi-(#{Gem::Version::VERSION_PATTERN})\.gemspec\z/

data/lib/samagotchi/chi_shim.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "shellwords"
 require_relative "atomic_file"
+require_relative "bundler_env"
 require_relative "chi_home"
 require_relative "log"
 require_relative "paths"
@@ -25,7 +26,7 @@ module Samagotchi
     # ruby: unset before the exec.
     UNSET = "unset RUBYOPT RUBYLIB RUBYGEMS_GEMDEPS GEMRC LD_PRELOAD LD_LIBRARY_PATH DYLD_INSERT_LIBRARIES " \
             "DYLD_LIBRARY_PATH\n" \
-            "for v in $(/usr/bin/env | /usr/bin/sed -n 's/^\\(BUNDLE[A-Za-z0-9_]*\\)=.*/\\1/p'); do unset \"$v\"; done\n"
+            "for v in $(/usr/bin/env | /usr/bin/sed -n 's/^\\(#{BundlerEnv::PREFIX}[A-Za-z0-9_]*\\)=.*/\\1/p'); do unset \"$v\"; done\n"
 
     module_function
 

data/lib/samagotchi/child_env.rb

@@ -20,16 +20,23 @@ module Samagotchi
     # (Tools::Builtins.parent_env): that session's, not a child chi's.
     SESSION_MARKERS = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL SAMAGOTCHI_SESSION_THINKING
                          SAMAGOTCHI_SESSION_REASONING_HISTORY].freeze
+    # "1" in the chi update an automatic run starts (Web::UpdateOps): no person
+    # reads its rows. An env marker, so it reaches the chi a hand-over or the home
+    # execs, and an older chi that doesn't know it simply ignores it.
+    UNATTENDED_UPDATE = "SAMAGOTCHI_UPDATE_UNATTENDED"
 
     module_function
 
     # The keys of +env+ a child chi must not inherit: the guardrails
     # settings, the session markers, a smoke's fake "newest installed"
-    # (InstalledVersions::ENV_KEY, for the spawner's notices only) and the
-    # worker's project env marker and record (a child worker applies its own).
+    # (InstalledVersions::ENV_KEY, for the spawner's notices only), the
+    # worker's project env marker and record (a child worker applies its own) and
+    # an automatic update's marker (a session someone starts from one isn't it; the
+    # update's own hand-over execs, which this doesn't touch).
     # @return [Array<String>]
     def spawner_keys(env = ENV)
-      env.each_key.select { |key| key.start_with?(GUARDRAILS_PREFIX) } + SESSION_MARKERS + [InstalledVersions::ENV_KEY, ProjectEnv::MARKER_ENV, ProjectEnv::ORIG_ENV]
+      env.each_key.select { |key| key.start_with?(GUARDRAILS_PREFIX) } + SESSION_MARKERS +
+        [InstalledVersions::ENV_KEY, ProjectEnv::MARKER_ENV, ProjectEnv::ORIG_ENV, UNATTENDED_UPDATE]
     end
 
     # #spawner_keys mapped to nil: Process.spawn unsets a key mapped to nil.

data/lib/samagotchi/engine.rb

@@ -961,7 +961,7 @@ module Samagotchi
     ANNOUNCEABLE_EVENTS = %i[turn_enqueued turn_dequeued input_merged prompt_restored continue_offered continue_resolved
                              command_queued command_ran context_added card hook_notice guardrail_warning
                              plugin_init_started plugin_init_finished working_set_updated participants_changed
-                             verdict_recorded objectives_updated].freeze
+                             verdict_recorded objectives_updated turn_rolled_back].freeze
 
     # Put a transport-level event into the ordered event log. Unlike turn
     # events it reaches only persistent observers (no turn sink, no memory

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)
@@ -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?
 

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