samagotchi 0.151.0 → 0.152.0

data/docs/releasing.md

@@ -21,7 +21,9 @@ can run the whole release; the user approves the notes before the tag and the
   - a bundle that uses something new in chi marks it in the same change with
     `requires_chi_next: true` (or a short reason) in its `manifest.yml`, and
     leaves `requires_chi` alone: raising it to a chi that isn't released yet
-    would make chi on main refuse its own bundle. `release:bump` raises a
+    would make chi on main refuse its own bundle outright — an unmet
+    `requires_chi` now stops the install, not just the load (`--force` is the
+    only way past it). `release:bump` raises a
     marked bundle's `requires_chi` to `">= X.Y.Z"` and drops the marker;
     `release:check` fails while a marker is left. chi itself ignores the key,
     and `bundles:check` notes it (and fails a marker that isn't `true` or a
@@ -30,6 +32,9 @@ can run the whole release; the user approves the notes before the tag and the
   - a new `ctx.*` / `chi.*` call a plugin may make gets its release's version in `Plugin::Api::SINCE` once
     released (`chi bundle check`'s `requires-chi-floor` reads it); an unreleased one waits there as an `# Unreleased` comment, and
     `release:check` fails while that comment is left: move each call up with the new version;
+  - a new manifest key or shape gets its release's version in `Manifest::SINCE` the same way (check's
+    `requires-chi-floor` reads it for the manifest too), waits as an `# Unreleased` comment while unreleased,
+    and `release:check` fails while that comment is left;
   - a new shipped bundle joins a profile (`includes:` in `core` or `dev`; a
     spec checks every bundle is in exactly one), and that profile's version
     goes up: `chi update` then installs only the new bundle for those who
@@ -72,7 +77,7 @@ as the GitHub release body.
 | `rake gem:validate`, `gem:build`, `gem:install`, `gem:clean` | Check the gemspec; build the gem into `pkg/`; build and install it locally; remove the built gems. |
 | `rake release:draft_changelog` | A draft Unreleased section from the commit subjects since the last tag, grouped. Stdout only. |
 | `rake release:bump[X.Y.Z]` | VERSION, the system manifest, Gemfile.lock, CHANGELOG, and `requires_chi: ">= X.Y.Z"` for each bundle marked `requires_chi_next` (the marker dropped), then a profile left below a member's `requires_chi` raised to it, with a patch bump of its version (none when it moved since the last tag) and named in the CHANGELOG's "Update with `chi update`" line. No commit. |
-| `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, no `requires_chi_next` left, no `# Unreleased` comment left in `Plugin::Api::SINCE`, `bundles:check`, `rake lint` (RuboCop) + `npm run lint` (the web frontend's ESLint), rspec (both roots: `spec` and the bundles' own `spec/`) + `rake bundles:specs` + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |
+| `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, no `requires_chi_next` left, no `# Unreleased` comment left in `Plugin::Api::SINCE` or `Manifest::SINCE`, `bundles:check`, `rake lint` (RuboCop) + `npm run lint` (the web frontend's ESLint), rspec (both roots: `spec` and the bundles' own `spec/`) + `rake bundles:specs` + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |
 | `rake release:notes[X.Y.Z]` | Prints the CHANGELOG section (default: the current VERSION). |
 
 ## Runbook

data/docs/sessions.md

@@ -495,7 +495,7 @@ mise.toml pins Ruby 3.4 gets that `ruby`, `gem` and `bundle` in its tools while
 The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail above 64 KB (`DelegateWait.cut`); a reply longer than `max_tool_output_chars` keeps its start and its end (the conclusion), with a gap line naming that `output/` file, where the whole reply is (`ToolOutputCut`'s `:head_tail_ref`; see [Tool output guardrails](internals/tool-output-limits.md#the-runners-cut-max_tool_output_chars)). Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `↑ <parent id>` in its info bar, its tooltip `delegated by session …`; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
 
 - `delegate(task, model:, session:, cwd:, wait:, timeout:)`: starts a child and, by default, waits for its reply. `wait: false` is the usual way for work that takes a while, several children side by side, or to keep talking with the user: it returns at once, the parent ends its turn or works on, and the reply comes back by itself as a *delegate report* (below), in a turn of its own if the parent is idle. The tool descriptions tell the model so, and to wait (`wait: true`, `delegate_result`) only when its turn can't go on without the reply. `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting. With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one. The wait (`wait: true`, a later `delegate_result`) and the delegate report are for the reply of the child's turn the follow-up went to: its running turn, which it merges into, or the turn of its own it runs when the child is idle (`turn` in `delegates.json`, set when the child's worker names `turn_ids`), not a newer reply of a turn queued behind it. A follow-up merged as a steer into a turn the child started at that moment (a wake, a reminder, another message) gets that turn's reply or question. A child on its first turn, or with an older worker, gives its next reply, as before.
-- `cwd:` starts the child in another folder of the parent's repository: a linked worktree (`git worktree add ../<repo>-<task> -b <branch>`, which the model runs with `execute` first, under guardrails; chi runs no git here) or a subfolder; a relative path is taken from the parent's folder. The folder must exist, have the parent's project root (the same common git dir, `MemoryPaths.project_root`) and be in a work tree: a git dir (`.git`, `.git/objects`, a bare layout's `.bare`) or a bare layout's container is refused (`git rev-parse --is-inside-work-tree`, read-only, decides). Outside git only a subfolder of the parent's folder is allowed. Otherwise the tool returns `Error: cwd must be a folder of this session's repository …` or `… is not in a work tree …`. A follow-up (`session:`) refuses `cwd:`: the child keeps its folder. The child's guardrails measure from its own worktree, and project memories, `list_sessions` and the web's project are the same as the parent's. With no `cwd:` and a task that names another checkout of the same repository (a path in the task belonging to a linked worktree, read from the files with `Guardrails::GitInfo.checkouts`, no git process), the result carries `Warning: this child runs in <folder>, but its task names <checkout>. If it should work there, stop it (chi sessions stop <id>) and call delegate again without session, with cwd: <checkout>.` One line however many are named; nothing for a path of the child's own checkout, a folder that isn't one, or a path with spaces. The child starts as it would anyway, and with `wait: true` (the default) the line comes after the child ran, so it only helps with `wait: false`. A `Warning:` for an unknown model id comes first, then this one. `Log.info(:worker, "delegate_other_checkout", parent:)` records each line.
+- `cwd:` starts the child in another folder of the parent's repository: a linked worktree (`git worktree add ../<repo>-<task> -b <branch>`, which the model runs with `execute` first, under guardrails; chi runs no git here) or a subfolder; a relative path is taken from the parent's folder. The folder must exist, have the parent's project root (the same common git dir, `MemoryPaths.project_root`) and be in a work tree: a git dir (`.git`, `.git/objects`, a bare layout's `.bare`) or a bare layout's container is refused (`git rev-parse --is-inside-work-tree`, read-only, decides). Outside git only a subfolder of the parent's folder is allowed. Otherwise the tool returns `Error: cwd must be a folder of this session's repository …` or `… is not in a work tree …`. A follow-up (`session:`) refuses `cwd:`: the child keeps its folder. The child's guardrails measure from its own worktree, and project memories, `list_sessions` and the web's project are the same as the parent's. With no `cwd:` and a task that names another checkout of the same repository (a path in the task belonging to a linked worktree, read from the files with `Guardrails::GitInfo.checkouts`, no git process), the result carries `Warning: this child runs in <folder>, but its task names <checkout>. If it should work there, stop it (chi sessions stop <id>) and call delegate again without session, with cwd: <checkout>.` One line however many are named; nothing for a path of the child's own checkout, a folder that isn't one, a path with spaces, or the main checkout when the child runs in a linked worktree of it (the work belongs in the worktree, so naming a main-checkout file is not a forgotten `cwd:`). The child starts as it would anyway, and with `wait: true` (the default) the line comes after the child ran, so it only helps with `wait: false`. A `Warning:` for an unknown model id comes first, then this one. `Log.info(:worker, "delegate_other_checkout", parent:)` records each line.
 - `delegate_result(session:, timeout:)`: waits for a child's next reply: the one named, or the newest running child (`timeout` as for `delegate`: 0 checks once and returns at once). The reply comes back once; a later call waits for the next one. After `wait: false` it isn't needed: the report brings the reply.
 - A wait also ends early when a person's message waits for the parent's turn's next step (the `task_wait` rule: `Engine#input_waiting?`, `SessionInbox.steer_waiting?`, never in a participant's turn): `ReplyWait`'s `message_waiting:` probe gives `:message_waiting`, checked after every outcome the child can arrive at (a reply, a question, an end, a gone worker) and a cancel, before the deadline, and the result says `no reply yet: a message from the user is waiting; the child keeps running. Read the message first.` with the same last line as a timeout's. The child is never touched, the cursor doesn't move (the reply still comes, as a report or at the next `delegate_result`), a relayed approval's outcome line stays in the result, and a reserved report reads as for a timeout. A delegate child's report doesn't end a wait. This holds for `delegate`'s own wait too (both go through `DelegateWait`).
 - A wait that timed out or was canceled still gets its delegate report: neither moves the parent's cursor, so the child's reply comes as a report when its turn ends. The result says so (`chi brings its reply here by itself as a delegate report …`; with `queue`, that it joins the next step or turn) and that `delegate_result` waits again only if the turn needs the reply now. A parent that gets no reports (`session.delegate_reports: off`, a `--no-shared` REPL, `--non-interactive`) is told `delegate_result <id> waits again` instead, and `wait: false`'s result says `delegate_result waits for its reply`.

data/lib/samagotchi/block_renderers.rb

@@ -76,10 +76,10 @@ module Samagotchi
     def for_installed
       taken = {}
       MemoryBundle::Provenance.each_installed do |bundle, record|
-        next unless record.block_renderers?
-        next if MemoryBundle::Manifest.requires_chi_failure(record.requires_chi, VERSION)
+        manifest = record.manifest
+        next if manifest.requires_chi_failure(VERSION)
 
-        renderers(bundle, record).each do |renderer|
+        renderers(bundle, manifest).each do |renderer|
           taken[renderer.lang] ||= Installed.new(lang: renderer.lang, bundle: bundle, files: renderer.load)
         end
       end
@@ -104,11 +104,12 @@ module Samagotchi
       raise Invalid, "bundle #{bundle}'s scripts/#{file} differs from the installed one (reinstall the bundle)"
     end
 
-    def renderers(bundle, record)
-      parse_list(record.block_renderers)
-    rescue ArgumentError => e # Invalid is one; so are a record's bytes that aren't UTF-8
-      Log.warn(:web, "block_renderers_unreadable", bundle: bundle, msg: e.message)
-      []
+    # Its parsed renderers; a list that doesn't parse is none (logged).
+    def renderers(bundle, manifest)
+      if (problem = manifest.problems["block_renderers"])
+        Log.warn(:web, "block_renderers_unreadable", bundle: bundle, msg: problem)
+      end
+      manifest.block_renderers
     end
     private_class_method :renderers
   end

data/lib/samagotchi/bundle_command/check.rb

@@ -84,6 +84,7 @@ module Samagotchi
         if manifest
           missing = check_files(manifest)
           check_source_tree(manifest, missing) unless @installed
+          check_keys(manifest)
           check_requires_chi(manifest)
           check_trust(manifest) unless @installed
           check_clash(manifest)
@@ -147,6 +148,44 @@ module Samagotchi
         index && (index + 1)
       end
 
+      # ── the manifest's own keys ───────────────────────────────────────
+
+      # A key this chi's parser never reads is one it ignores, and a key whose
+      # floor is above what requires_chi admits is one an older chi would
+      # ignore too. The floor is the author's fix, so an installed bundle gets
+      # only the unknown-key line, as check_floor's call floor does today.
+      def check_keys(manifest)
+        manifest.unknown_keys.each do |key|
+          add(:warn, :"unknown-key", "manifest.yml", MemoryBundle::Manifest.unknown_key_line(key), line: manifest_line(key),
+              fix: "update chi, or remove #{key}: if it's a typo")
+        end
+        check_key_floor(manifest) unless @installed
+      end
+
+      # The manifest uses a key the oldest chi requires_chi admits never read.
+      # No plugin needed: the key is the bundle's own claim.
+      def check_key_floor(manifest)
+        key, version = manifest.floor_keys.max_by { |_, floor| Gem::Version.new(floor) }
+        return if key.nil?
+
+        bound = lower_bound(manifest.requires_chi)
+        return if bound && Gem::Version.new(version) <= bound
+
+        add(:warn, :"requires-chi-floor", "manifest.yml",
+            "#{manifest.requires_chi ? "requires_chi #{manifest.requires_chi.inspect} admits chi #{bound}," : "no requires_chi,"} " \
+            "but the manifest uses #{key_label(key)}, which needs chi #{version}",
+            line: manifest_line(key.split(".").first), fix: "requires_chi: \">= #{version}\"")
+      end
+
+      # How to name a SINCE key in a message: a shape is not a key on its own.
+      def key_label(key)
+        case key
+        when "files.description" then "a files: entry given as a mapping"
+        when "session_settings.types", "settings.types" then "#{key.split(".").first}: as a mapping of keys to types"
+        else "#{key}:"
+        end
+      end
+
       # ── files ─────────────────────────────────────────────────────────
 
       # @return [Boolean] whether a listed file is missing
@@ -340,15 +379,16 @@ module Samagotchi
         return if manifest.settings.nil? || @settings.empty?
 
         require_relative "../bundle_settings_check"
-        record = MemoryBundle::InstalledBundle.new(name: manifest.name, settings: manifest.settings, setting_types: manifest.setting_types,
-                                                   session_settings: manifest.session_settings)
-        BundleSettingsCheck.record_warnings(record, @settings).each { |line| add(:warn, :settings, "manifest.yml", line, line: manifest_line("settings")) }
+        BundleSettingsCheck.record_warnings(manifest, @settings).each { |line| add(:warn, :settings, "manifest.yml", line, line: manifest_line("settings")) }
       end
 
       def install_warnings(warnings)
         stale_reported = @findings.any? { |f| f.code == :sha }
         warnings.each do |warning|
           next if stale_reported && warning.start_with?("Checksum mismatch")
+          # An unknown manifest key is check_keys' row, with the fix the install
+          # can't offer; the same condition twice would be two rows.
+          next if warning.include?("doesn't know the manifest key")
           next if @too_new && warning.include?("won't load:")
           # This machine's PATH, said at install; nothing a chi update changed.
           next if @installed && warning.start_with?("needs ")

data/lib/samagotchi/bundle_command/installed_check.rb

@@ -58,13 +58,17 @@ module Samagotchi
       private_class_method :in_child
 
       # What the child sends: an edited file, which the copy's own shas can't
-      # tell, and Check's warnings and errors, naming the installed bundle's
-      # folder rather than the copy's.
+      # tell, a manifest key that doesn't parse (the copy holds the mirror's
+      # value or none: InstalledManifest#key_problems), and Check's warnings
+      # and errors, naming the installed bundle's folder rather than the copy's.
       def answer_of(bundle)
         edited = MemoryBundle::ShippedUpdate.edited_executables(bundle.name, bundle).map do |file|
           Check::Finding.new(level: :warn, code: :edited, file: file, line: nil, fix: "chi bundle upgrade #{bundle.name}, or reinstall it",
                              message: "changed since it was installed, so chi doesn't load it")
         end
+        edited += bundle.manifest.key_problems.values.map do |message|
+          Check::Finding.new(level: :error, code: :manifest, file: "manifest.yml", line: nil, message: message, fix: nil)
+        end
         edited = edited.map { |finding| { level: finding.level, text: finding.to_s } }
         installed_dir = MemoryBundle::Provenance.new(name: bundle.name).bundle_dir
         edited + MemoryBundle::InstalledCopy.with(bundle) do |dir|

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

@@ -101,6 +101,9 @@ module Samagotchi
           raise
         end
 
+        # The environment to spawn a child with: what the sandbox keeps, with
+        # every key it dropped present as nil (ChildEnv.spawn_env), so the
+        # child doesn't inherit it from this process.
         def child_env = @child_env.dup
 
         # Installs the tried bundle, then the shipped guardrails and
@@ -219,7 +222,12 @@ module Samagotchi
         # The user's environment (their hosts and keys) minus what no child
         # chi takes from its spawner (ChildEnv), the worker markers, this
         # chi's log and test settings, and the env forms of the config
-        # sections the sandbox drops.
+        # sections the sandbox drops. ChildEnv.spawn_env makes every dropped
+        # key an unset in the child: a Hash handed to Open3 or Process.spawn
+        # is merged onto this process's environment, so deleting a key from
+        # it alone still passes it on. The Bundler changes come from ENV, not
+        # from this copy: read from the copy, a key dropped above would look
+        # like one Bundler added and come back with its value.
         def build_child_env
           env = ChildEnv.scrub(ENV.to_h)
           env.delete("SAMAGOTCHI_LOG_FILE")
@@ -235,8 +243,8 @@ module Samagotchi
             "SAMAGOTCHI_KEYCHAIN" => "on",
             **@layout.env
           )
-          env.merge!(ChildEnv.unbundled(env))
-          env
+          env.merge!(ChildEnv.unbundled)
+          ChildEnv.spawn_env(env)
         end
       end
     end

data/lib/samagotchi/bundle_command.rb

@@ -16,11 +16,14 @@ module Samagotchi
           Install a memory bundle from a directory, zip, tar archive, or git URL.
           Source is the path/URL to the bundle (dir/zip/tar.gz/git).
           --force overwrites existing entries (one that differs is copied to the trash first); default skips them.
+          A bundle whose requires_chi this chi doesn't meet is refused; --force installs it anyway.
 
-        upgrade <source> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]
+        upgrade <source|name> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]
           Upgrade a bundle (3-way: a file you didn't edit updates; one you edited takes a text
           merge, the old file in the bundle trash; a real conflict leaves it as it is).
+          A bare NAME upgrades the bundle installed under that name from the source it came from.
           --dry-run shows what would change. --agent launches interactive session on conflict.
+          A bundle whose requires_chi this chi doesn't meet is refused; --force installs it anyway.
 
         uninstall <bundle> [--scope system|project] [--force]
           Remove a bundle and its index entries (--force moves a locally edited file to the trash).
@@ -69,13 +72,19 @@ module Samagotchi
           Install a memory bundle from a directory, zip, tar archive, or git URL,
           or a bundle shipped with chi by name (see: chi bundle list).
           --force overwrites existing entries (one that differs is copied to the trash first); default skips them.
+          It also installs a bundle whose requires_chi this chi doesn't meet: without --force that install is
+          refused, and the bundle is not written anywhere.
         install --dev PATH
           Install the bundle in the local directory PATH as a link to it: its plugin, hooks, rules and scripts
           are PATH's own files (an edit applies at the next worker or chi web restart, with no re-install) and
           their sha256 isn't checked, for this bundle only. Its memories are copied; re-install with --force to
           pick up memory edits. Upgrade refuses it; uninstall removes the link, never PATH's files.
     TEXT
-    UPGRADE_HELP = "Usage: chi bundle upgrade <source> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]"
+    UPGRADE_HELP = <<~TEXT
+      Usage: chi bundle upgrade <source|name> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]
+        --force takes the bundle's file over an edited one, and installs a bundle whose requires_chi this chi
+        doesn't meet (without it such a bundle is refused).
+    TEXT
     UNINSTALL_HELP = "Usage: chi bundle uninstall <bundle> [--scope system|project] [--force]"
     BUILD_HELP = <<~TEXT
       Usage: chi bundle build [--scope system|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]
@@ -210,7 +219,13 @@ module Samagotchi
         @stderr.puts UPGRADE_HELP
         return CLI::Exit::USAGE
       end
-      expanded_source = expand_source(source)
+      expanded_source, record = upgrade_source(source)
+      return 1 if expanded_source.nil?
+
+      # The record's source: said once, so it is clear which bundle and where
+      # it comes from when the name alone was given.
+      @stdout.puts "Upgrading #{record.name} from #{expanded_source}" if record
+
       if Samagotchi::MemoryBundle::Profile.shipped_meta?(expanded_source)
         return install_profile(expanded_source, scope: scope, force: force, dry_run: dry_run, word: "Upgrade")
       end
@@ -305,7 +320,11 @@ module Samagotchi
 
     def print_hooks_and_plugin(manifest, plugin: true)
       @stdout.puts "Hooks: #{manifest.hooks.size} hook(s) (#{manifest.hooks.keys.join(", ")})" if manifest&.hooks&.any?
-      @stdout.puts "Plugin: #{manifest.plugin[:file]} (loads at the next chi start)" if plugin && manifest&.plugin
+      return unless plugin && manifest&.plugin
+
+      # Installed with --force past its requires_chi: the Engine won't load it.
+      failure = Samagotchi::MemoryBundle::Manifest.requires_chi_failure(manifest.requires_chi, Samagotchi::VERSION)
+      @stdout.puts "Plugin: #{manifest.plugin[:file]} (#{failure ? "won't load on this chi: #{failure}" : "loads at the next chi start"})"
     end
 
     # @return [Integer] 0
@@ -499,9 +518,11 @@ module Samagotchi
           label += "; #{info[:merge_note].line}#{" (old copy in #{info[:merge_note].trash})" if info[:merge_note].trash}" if info[:merge_note]
           @stdout.puts "  #{k}: #{label}"
         end
+        @stdout.puts "  #{manifest_line(st.provenance)}"
         # Hooks
-        hooks = st.provenance.hooks
-        trust = st.provenance.trust_level || "experimental"
+        manifest = st.provenance.manifest
+        hooks = manifest.hooks
+        trust = manifest.trust_level || "experimental"
         commit = st.provenance.source_commit
         @stdout.puts "  trust_level: #{trust}" if hooks.any? || trust
         @stdout.puts "  source_commit: #{commit}" if commit
@@ -512,7 +533,7 @@ module Samagotchi
             exists = File.exist?(hook_path) ? "ok" : "missing"
             @stdout.puts "    #{hk}: #{hook.events_field} on_error=#{hook.on_error} priority=#{hook.priority} [#{exists}]"
           end
-          @stdout.puts "    requires_chi: #{st.provenance.requires_chi}" if st.hooks_requires_failure
+          @stdout.puts "    requires_chi: #{manifest.requires_chi}" if st.hooks_requires_failure
           @stdout.puts "    not loaded: #{st.hooks_requires_failure}" if st.hooks_requires_failure
         end
         if (plugin = st.plugin)
@@ -534,7 +555,7 @@ module Samagotchi
 
           st = Samagotchi::MemoryBundle::Status.bundle_status(bname)
           mods = st.files.values.count { |v| v[:behind] || v[:missing] || v[:unreadable] }
-          hooks_count = st.provenance.hooks.size
+          hooks_count = st.provenance.manifest.hooks.size
           hook_info = hooks_count > 0 ? " hooks=#{hooks_count}" : ""
           plugin = st.plugin
           mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
@@ -549,6 +570,14 @@ module Samagotchi
       0
     end
 
+    # "Manifest: [kept]", or "[from the install record]", and what its case
+    # says (MemoryBundle::ManifestStanding).
+    def manifest_line(record)
+      require_relative "memory_bundle/manifest_standing"
+      standing = Samagotchi::MemoryBundle::ManifestStanding
+      ["Manifest:", standing.label(record), standing.status_line(record)].compact.join(" ")
+    end
+
     # " dev → /path (missing)" when a dev install's source isn't there, else "".
     def dev_label(record)
       return "" unless record.dev
@@ -577,7 +606,7 @@ module Samagotchi
       rescue ArgumentError => e
         @stderr.puts "Bundle '#{bname}': #{e.message}"; return 1
       end
-      hooks = record.hooks
+      hooks = record.manifest.hooks
       plugin_path = prov.plugin_path(record)
       plugin_file = plugin_path && File.basename(plugin_path)
       if file_arg
@@ -612,6 +641,26 @@ module Samagotchi
 
     def diff_memory(prov, target_dir, key)
       print_base_and_current(key, prov.base_path(key), File.join(target_dir, key))
+      print_incoming(prov, key)
+    end
+
+    # The bundle's text a file stays behind (Provenance#incoming_path), so the
+    # sections the "stays behind" line names can be read. No saved copy: nothing.
+    def print_incoming(prov, key)
+      path = prov.incoming_path(key)
+      return unless File.exist?(path)
+
+      text = begin
+        File.read(path)
+      rescue SystemCallError
+        nil
+      end
+      if text
+        @stdout.puts "--- incoming (the bundle's #{prov.record.version}, which this file stays behind) ---"
+        @stdout.puts text
+      else
+        @stdout.puts "--- incoming: the bundle's saved copy can't be read ---"
+      end
     end
 
     def diff_hook(prov, key, hook)
@@ -622,7 +671,8 @@ module Samagotchi
     def diff_plugin(prov, record, plugin_path)
       file = File.basename(plugin_path)
       print_base_and_current("plugin/#{file}", prov.plugin_base_path(file), plugin_path)
-      @stdout.puts "--- metadata: sha256=#{record.plugin.sha256}#{" requires_chi=#{record.requires_chi}" if record.requires_chi}"
+      requires_chi = record.manifest.requires_chi
+      @stdout.puts "--- metadata: sha256=#{record.plugin.sha256}#{" requires_chi=#{requires_chi}" if requires_chi}"
     end
 
     def print_base_and_current(heading, base, current)
@@ -926,6 +976,34 @@ module Samagotchi
       Samagotchi::MemoryBundle::SourceNormalizer.shipped_bundle_dir(src) || File.expand_path(src)
     end
 
+    # Where an upgrade comes from: the source as given — a git URL, an
+    # existing path, a shipped bundle's name, as install takes them — or,
+    # for the bare name of an installed bundle, the source its record keeps.
+    # A dev install is refused (it already follows its source), and a record
+    # whose source is relative, empty or gone says so. nil after such a
+    # refusal, written to stderr.
+    # @return [Array(String, InstalledBundle, nil), nil] [the source, the
+    #   record that named it (nil for a source as given)]
+    def upgrade_source(source)
+      normalizer = Samagotchi::MemoryBundle::SourceNormalizer
+      given = normalizer.git_url?(source) || normalizer.shipped_bundle_dir(source) || File.exist?(File.expand_path(source))
+      return [expand_source(source), nil] if given
+
+      record = Samagotchi::MemoryBundle::Provenance.new(name: source.to_s.strip).record
+      return [expand_source(source), nil] if record.nil? || record.error?
+
+      if record.dev
+        @stderr.puts "Upgrade failed: #{Samagotchi::MemoryBundle::Installer.dev_install_line(record.name, record.source)}"
+        return nil
+      end
+
+      recorded = record.source.to_s.strip
+      return [recorded, record] if normalizer.git_url?(recorded) || (recorded.start_with?("/") && File.exist?(recorded))
+
+      @stderr.puts "Upgrade failed: #{Samagotchi::MemoryBundle::Installer.source_gone_line(record.name, recorded)}"
+      nil
+    end
+
     def build_conflict_prompt(bundle_name, conflicts, expanded_source)
       lines = []
       lines << "Memory bundle upgrade has conflicts that need interactive resolution."

data/lib/samagotchi/bundle_needs.rb

@@ -66,13 +66,11 @@ module Samagotchi
     # missing need. A manifest.json or needs: that doesn't parse is skipped.
     def self.entry_markers(scope, path:, bundles_dir:)
       MemoryBundle::Provenance.each_installed(dir: bundles_dir).each_with_object({}) do |(_name, bundle), acc|
-        next if bundle.error? || bundle.effective_scope != scope.to_s || !bundle.needs?
+        next if bundle.error? || bundle.effective_scope != scope.to_s
+
+        needs = bundle.manifest.needs
+        next if needs.empty?
 
-        needs = begin
-          MemoryBundle::Manifest.parse_needs(bundle.needs)
-        rescue MemoryBundle::Manifest::ValidationError
-          next
-        end
         marker = marker(missing(needs, path: path))
         next unless marker
 

data/lib/samagotchi/bundle_settings_check.rb

@@ -32,7 +32,7 @@ module Samagotchi
         next ["config.yml bundles: #{name}: #{SessionConfig.no_installed_bundle(name)}#{near(name, installed.keys)}"] unless bundle
         next [] if bundle.error?
 
-        record_warnings(bundle, values)
+        record_warnings(bundle.manifest, values)
       end
     end
 
@@ -62,23 +62,24 @@ module Samagotchi
       lines
     end
 
-    # One bundle's +values+ against its record (or a manifest as one); none
-    # while it declares no settings:.
-    # @param bundle [MemoryBundle::InstalledBundle]
+    # One bundle's +values+ against its manifest (an installed one's or a
+    # source's); none while it declares no settings:.
+    # @param manifest [MemoryBundle::InstalledManifest, MemoryBundle::Manifest]
+    #   name, settings, session_settings, setting_types
     # @return [Array<String>]
-    def record_warnings(bundle, values)
-      return [] if bundle.settings.nil?
+    def record_warnings(manifest, values)
+      return [] if manifest.settings.nil?
 
-      values.flat_map { |key, value| value_warnings(bundle, key.to_s, value) }
+      values.flat_map { |key, value| value_warnings(manifest, key.to_s, value) }
     end
 
-    def value_warnings(bundle, key, value)
-      where = "config.yml bundles: #{bundle.name}.#{key}"
-      known = bundle.settings | bundle.session_settings
-      return ["#{where}: #{SessionConfig.takes_keys(bundle.name, known)}#{near(key, known)}"] unless known.include?(key)
+    def value_warnings(manifest, key, value)
+      where = "config.yml bundles: #{manifest.name}.#{key}"
+      known = manifest.settings | manifest.session_settings
+      return ["#{where}: #{SessionConfig.takes_keys(manifest.name, known)}#{near(key, known)}"] unless known.include?(key)
 
-      takes, what = SessionConfig::TYPES[bundle.setting_types[key]]
-      takes && !takes.call(value) ? ["#{where}: #{SessionConfig.wrong_type(bundle.name, key, what, value)}"] : []
+      takes, what = SessionConfig::TYPES[manifest.setting_types[key]]
+      takes && !takes.call(value) ? ["#{where}: #{SessionConfig.wrong_type(manifest.name, key, what, value)}"] : []
     end
     private_class_method :value_warnings
 

data/lib/samagotchi/bundles/agents-md/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: agents-md
-version: 0.1.1
+version: 0.1.2
 scope: system
 description: "Steers a nested AGENTS.md into the conversation the first time a tool touches a file under its directory"
 trust_level: reviewed
@@ -8,6 +8,6 @@ plugin:
   file: plugin.rb
   sha256: sha256:56527b9d12cb9acd8f57ca00881ab159894ae2fb8def22bce66ac3774bb4187b
 # ctx.prompt_files, read when the plugin loads (0.60.0)
-requires_chi: ">= 0.60.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: agents-md: (another key warns; an older chi ignores this)
 settings: [tools, max_chars]

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

@@ -1,12 +1,12 @@
 ---
 name: btw
-version: 0.1.3
+version: 0.1.4
 scope: system
 description: "/btw <question>: a side answer about the conversation, as a card in every UI, even mid-turn; Keep as session forks it into a child session"
 trust_level: reviewed
 plugin:
   file: plugin.rb
   sha256: sha256:6497129b06d1c3061c1d7d9d7a9c3dfdbcf790e8f2049addad0c26d24771015f
-requires_chi: ">= 0.1.30"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: btw: (another key warns; an older chi ignores this)
 settings: [max_tokens, timeout]

data/lib/samagotchi/bundles/loop-guard/manifest.yml

@@ -1,12 +1,12 @@
 ---
 name: loop-guard
-version: 0.3.9
+version: 0.3.10
 scope: system
 description: "Breaks loops: the same tool call with the same result again and again in one turn is denied with advice (after a few denies the turn stops with a card), and thinking that repeats itself while it streams is cut and the model asked again"
 trust_level: reviewed
 plugin:
   file: plugin.rb
   sha256: sha256:a4ac7c48a903716b7e1c4fa35348439e90ac97d3ad421378ce7d3ac819229a09
-requires_chi: ">= 0.6.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: loop-guard: (another key warns; an older chi ignores this)
 settings: [deny_after, stop_after, ignore_tools, mode, thinking]

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

@@ -1,6 +1,6 @@
 ---
 name: mcp
-version: 0.7.5
+version: 0.7.6
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session; their tools go into chi's tool index: the model searches them with find_tools and calls one with call_tool (<server>/<tool>); /mcp lists them"
 trust_level: reviewed
@@ -9,6 +9,6 @@ plugin:
   file: plugin.rb
   sha256: sha256:718e53db877eacd2714e69427c69cfc6c551aaf3417bb760a27dac3331363db5
 # 0.67.0 is the release with chi.tool_source (the core tool index the bundle publishes into).
-requires_chi: ">= 0.121.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: mcp: (another key warns; an older chi ignores this)
 settings: [servers, timeout, startup_timeout]

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

@@ -1,12 +1,12 @@
 ---
 name: skills
-version: 0.1.8
+version: 0.1.9
 scope: system
 description: "Skills (skill_<name> memories, the steps of a task done together): /skill save, list, show and diff; older versions kept with a short diff line on every update; a nudge when a followed skill's step fails"
 trust_level: reviewed
 plugin:
   file: plugin.rb
   sha256: sha256:781d943749d59ade0e24d04ba774449d31267eb8ca435835c36c67a3e523e632
-requires_chi: ">= 0.11.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: skills: (another key warns; an older chi ignores this)
 settings: [history_keep, nudge]

data/lib/samagotchi/bundles/slow-commands/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: slow-commands
-version: 0.2.4
+version: 0.2.5
 scope: system
 description: "Remembers commands that ran past the execute limit in a project; the next identical execute is denied once a turn with advice to run it with task_create and task_wait; /slow-commands lists and forgets them"
 trust_level: reviewed
@@ -9,6 +9,6 @@ plugin:
   sha256: sha256:e51c099c1552bd0cd1fe46e4fd235a3fe8340693e6ca338eb7ed09d8398a6f0f
 # Execute::HANDED_OVER, read when the plugin loads (0.59.0); after_tool_call's
 # call:, elapsed_ms: and result: (0.57.0)
-requires_chi: ">= 0.59.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: slow-commands: (another key warns; an older chi ignores this)
 settings: [mode, warn_ratio, ttl_days]

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.151.0
+version: 0.152.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:e695f78f858c29ccfef2ed6f9d6dd86d0ec067ed704a5a1956c01e53617948a1
   config_modification_protocol.md: sha256:8896d1d364ce835040f69b504518d43dbdf959b93fdd9b10f87a8de61cae84a8
-  memory_guide.md: sha256:bfe9f13e8a6c929056fe531c4c74c7e05d0f17f025191c1a111c8e7dfd224fd6
+  memory_guide.md: sha256:8b7727b939b9c04486ca59859561023dcc319a73e0f5b47b3fcf5741edaa69e2
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

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

@@ -113,8 +113,8 @@ 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::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. |
+| `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). It also installs a bundle whose `requires_chi` this chi doesn't meet: without `--force` that install is refused (`NAME can't be installed: it requires chi …`). 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\|name> [--force] [--dry-run] [--agent]` | A bare `name` is an installed bundle: chi upgrades it from the source its record keeps (its git URL with the `#ref` it recorded, its folder, or the archive it came from) — a dev install is refused, and a record whose source is gone says so and asks for the path or URL. Otherwise 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|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. |
@@ -146,7 +146,7 @@ chi bundle build --scope system --out updated.zip
 
 ### Provenance internals (for debugging)
 
-- Each installed bundle is recorded at `<system dir>/.bundles/<name>/manifest.json` + `bases/<file>.md` snapshots (`Provenance`). Used only for upgrade `Merger` and `status`/`diff`. Build does **not** write provenance.
+- Each installed bundle is recorded at `<system dir>/.bundles/<name>/manifest.json` + `bases/<file>.md` snapshots (`Provenance`), with the bundle's own `manifest.yml` kept beside it (chi reads the manifest from there at load). Used only for upgrade `Merger` and `status`/`diff`. Build does **not** write provenance.
 - A bundle records only the files it wrote. `index.md` updates aren't fatal: a failed one is a warning in the install/uninstall output.
 
 ## Best practices for the agent