samagotchi 0.16.0 → 0.18.0

data/lib/samagotchi/bundle_command.rb

@@ -10,7 +10,7 @@ module Samagotchi
   # subcommands have their own flags).
   class BundleCommand
     USAGE = <<~TEXT
-      Usage: chi bundle <install|upgrade|uninstall|status|diff|list|build> [options]
+      Usage: chi bundle <install|upgrade|uninstall|status|diff|list|build|trash> [options]
 
         install <source> [--scope system|project] [--force]
           Install a memory bundle from a directory, zip, tar archive, or git URL.
@@ -36,7 +36,11 @@ module Samagotchi
         build [--scope system|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]
           Build local memories and installed hooks (and plugin) into a shareable bundle (dir or zip).
           --scope selects source dir (default: system). --out inferred from extension; default <name>.zip.
-          FILES... optional allowlist of *.md basenames to include (default: all).
+          FILES... optional allowlist of *.md basenames to include (default: all but installed bundles' ones).
+
+        trash [--empty] [--dry-run] [--older-than DAYS]
+          List bundle trash (moved files from uninstalls/upgrades).
+          --empty deletes all trash folders. --older-than DAYS keeps only recent ones.
     TEXT
 
     # Each subcommand's --help (and only --help: -h and help are taken as
@@ -57,13 +61,14 @@ module Samagotchi
         build [--scope system|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]
           Build local memories and installed hooks into a shareable bundle (dir or zip).
           --scope selects source dir (default: system). --out inferred from extension; default <name>.zip.
-          FILES... optional allowlist of *.md basenames to include (default: all).
+          FILES... optional allowlist of *.md basenames to include (default: all but installed bundles' ones).
 
         Examples:
           chi bundle build --scope system
           chi bundle build --scope project --name my-bundle --version 1.0.0 --out bundle.zip
           chi bundle build --scope system --out ./my-bundle/ identity.md work.md
     TEXT
+    TRASH_HELP = "Usage: chi bundle trash [--empty] [--dry-run] [--older-than DAYS]"
 
     # The subcommands' flags: --help only; a word not starting with -- is
     # a positional (install's source, -h included). --scope takes whatever
@@ -83,6 +88,11 @@ module Samagotchi
     BUILD_FLAGS = CLI::Flags.new(help: %w[--help], flag_pattern: /\A--/, dash_values: false) do |f|
       %w[--scope --name --version --description --out].each { |name| f.value name }
     end
+    TRASH_FLAGS = CLI::Flags.new(help: %w[--help], flag_pattern: /\A--/) do |f|
+      f.switch "--empty"
+      f.switch "--dry-run"
+      f.value "--older-than"
+    end
 
     # @param argv [Array<String>] the arguments after "bundle"
     def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr)
@@ -108,8 +118,9 @@ module Samagotchi
       when "diff" then diff(@argv[1..])
       when "list" then list
       when "build" then build(@argv[1..])
+      when "trash" then trash(@argv[1..])
       else
-        @stderr.puts "Unknown bundle subcommand: #{sub}. Use: install, upgrade, uninstall, status, diff, list, build"
+        @stderr.puts "Unknown bundle subcommand: #{sub}. Use: install, upgrade, uninstall, status, diff, list, build, trash"
         return CLI::Exit::USAGE
       end
     end
@@ -272,6 +283,7 @@ module Samagotchi
       begin
         uninstaller.run
         @stdout.puts "Uninstalled bundle '#{bundle_name}'"
+        puts_trashed(uninstaller.trashed_files, uninstaller.trash_dir)
         @stdout.puts "Removed: #{uninstaller.removed_files.join(', ')}" unless uninstaller.removed_files.empty?
         hook_removed = uninstaller.removed_files.count { |f| f.start_with?("hooks/") }
         @stdout.puts "Hooks removed: #{hook_removed}" if hook_removed > 0
@@ -311,9 +323,13 @@ module Samagotchi
       if result.gone
         @stdout.puts "Uninstalled bundle '#{name}'"
         @stdout.puts "Removed: #{result.removed.join(", ")}" unless result.removed.empty?
+        result.trash.each_value { |files, dir| puts_trashed(files, dir) }
+        result.warnings.each { |w| @stdout.puts w }
         return 0
       end
       @stdout.puts "Removed from #{name}: #{result.removed.join(", ")}" unless result.removed.empty?
+      result.trash.each_value { |files, dir| puts_trashed(files, dir) }
+      result.warnings.each { |w| @stdout.puts w }
       result.blocked.each { |member, why| @stdout.puts "Kept #{member}: #{why}" }
       @stderr.puts "Uninstall failed: #{name} stays installed until #{result.blocked.keys.join(", ")} goes " \
                    "(chi bundle uninstall #{name} --force)"
@@ -323,6 +339,11 @@ module Samagotchi
       1
     end
 
+    # Memory files an uninstall moved to the trash (MemoryBundle::Trash).
+    def puts_trashed(files, dir)
+      @stdout.puts "Moved to the trash: #{files.join(", ")} (#{dir})" if dir && !files.empty?
+    end
+
     def status(rest)
       name = rest.find { |a| !a.start_with?("--") }
       require "json"
@@ -557,6 +578,7 @@ module Samagotchi
         @stdout.puts "Built #{result[:files].size} file(s) to #{result[:out_path]}"
         @stdout.puts "Bundle: #{result[:name]} v#{result[:version]} scope=#{result[:scope]}"
         @stdout.puts "Files: #{result[:files].join(', ')}" unless result[:files].empty?
+        builder.warnings.each { |w| @stdout.puts w }
         unless result[:placeholder_warnings].empty?
           @stdout.puts "Placeholders:"
           result[:placeholder_warnings].each { |w| @stdout.puts "  #{w}" }
@@ -568,6 +590,101 @@ module Samagotchi
       end
     end
 
+    def trash(rest)
+      parsed = parse_flags(TRASH_FLAGS, rest, "trash", help: TRASH_HELP)
+      return parsed if parsed.is_a?(Integer)
+
+      opts = parsed.options
+      empty = opts.fetch(:empty, false)
+      dry_run = opts.fetch(:dry_run, false)
+      older_than = opts[:older_than]
+
+      # --older-than and --dry-run without --empty are a usage error
+      if (older_than || dry_run) && !empty
+        @stderr.puts "Usage: chi bundle trash [--empty] [--dry-run] [--older-than DAYS]"
+        return CLI::Exit::USAGE
+      end
+
+      # Validate older_than if given
+      if older_than
+        if older_than.to_s.match?(/\A\d+\z/) && older_than.to_i > 0
+          older_than = older_than.to_i
+        else
+          @stderr.puts "Usage: chi bundle trash [--empty] [--dry-run] [--older-than DAYS]"
+          return CLI::Exit::USAGE
+        end
+      end
+
+      if empty
+        do_empty(older_than_days: older_than, dry_run: dry_run)
+      else
+        do_list
+      end
+    end
+
+    def do_list
+      entries = Samagotchi::MemoryBundle::Trash.entries
+      if entries.empty?
+        @stdout.puts "The bundle trash is empty."
+        return 0
+      end
+
+      entries.each do |e|
+        @stdout.puts "  #{e.name}  #{e.files} file#{'s' unless e.files == 1}  #{format_bytes(e.bytes)}  #{format_age(e.time)}"
+      end
+      @stdout.puts "\nEmpty it with: chi bundle trash --empty [--older-than DAYS]"
+      0
+    end
+
+    def do_empty(older_than_days:, dry_run:)
+      entries = Samagotchi::MemoryBundle::Trash.empty!(
+        older_than_days: older_than_days,
+        dry_run: dry_run,
+      )
+      if entries.empty?
+        @stdout.puts "The bundle trash is empty."
+        return 0
+      end
+
+      total_files = entries.sum(&:files)
+      if dry_run
+        entries.each do |e|
+          @stdout.puts "Would delete: #{e.name} (#{e.files} file#{'s' unless e.files == 1}, #{format_bytes(e.bytes)})"
+        end
+        @stdout.puts "\n(dry-run: #{entries.size} folder#{'s' unless entries.size == 1}, #{total_files} file#{'s' unless total_files == 1})"
+      else
+        @stdout.puts "Deleted #{entries.size} folder#{'s' unless entries.size == 1} (#{total_files} file#{'s' unless total_files == 1}) from the trash."
+      end
+      0
+    end
+
+    # Format bytes as human-readable (B, KB, MB with one decimal)
+    def format_bytes(bytes)
+      return "0 B" if bytes == 0
+      if bytes < 1024
+        "#{bytes} B"
+      elsif bytes < 1_048_576
+        "#{(bytes / 1024.0).round(1)} KB"
+      else
+        "#{(bytes / 1_048_576.0).round(1)} MB"
+      end
+    end
+
+    # Format age as "just now", "N minutes ago", "N hours ago", "N days ago"
+    def format_age(time)
+      now = Time.now
+      diff = now - time
+      if diff < 60
+        "just now"
+      elsif diff < 3600
+        "#{(diff / 60).to_i} minutes ago"
+      elsif diff < 86_400
+        "#{(diff / 3600).to_i} hours ago"
+      else
+        "#{(diff / 86_400).to_i} days ago"
+      end
+    end
+
     # +rest+ through +flags+, stopping at the first --help or error.
     #
     # @return [CLI::Flags::Result, Integer] the result, or the exit status

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -4,7 +4,8 @@
 # earlier or `git -C` variants can get past them.
 #
 # Fields: id, tool (a name, a list, or shell = execute + task_create),
-# command (Ruby regex), path (outside_repo or a glob), verdict (ask|deny),
+# command (Ruby regex), path (outside_repo or a glob), git (outside_repo:
+# a shell call runs commit/add/reset/… in another checkout), verdict (ask|deny),
 # reason, scopes (for an ask: once, session, repo, rule; default all).
 # [^;&|\n]* keeps a match inside one command of a chain; the git rules match
 # the subcommand after optional global options (git -C dir push).
@@ -62,12 +63,26 @@ rules:
     verdict: ask
     reason: runs decoded text as a script
 
-  # ── files outside the repo, and git hooks ──────────────────────────────
+  # ── work outside this session's repo, and git hooks ───────────────────
+  # outside_repo: not in the session's repo (its folder outside a repo);
+  # tmp dirs and memory files don't count.
   - id: write-outside-repo
     tool: [write, edit]
     path: outside_repo
     verdict: ask
-    reason: writes outside the repository
+    reason: writes outside this session's repo
+  # cd/git -C into another checkout, then commit, add, reset, checkout,
+  # switch, rebase, merge, push, stash, rm, mv, cherry-pick, revert, pull,
+  # restore or am. Read-only git (status, log, diff) and tests there run.
+  # "This call in this repo" would never match again (the command holds
+  # the commit message), so it isn't offered: "rule in this repo" is the
+  # always-for-here answer.
+  - id: git-outside-repo
+    tool: shell
+    git: outside_repo
+    verdict: ask
+    scopes: [once, session, rule]
+    reason: runs git that changes another checkout, outside this session's repo
   - id: git-hooks-write
     tool: [write, edit]
     path: '**/.git/hooks/**'

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

@@ -1,10 +1,10 @@
 ---
 name: guardrails
-version: 0.3.0
+version: 0.4.0
 scope: system
-description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, writes outside the repo, git hooks, answering chi around chi answer), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
+description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, writes and git in another checkout outside the session's repo, git hooks, answering chi around chi answer), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed
-# models: in small-models.yml (guardrails.small_models)
-requires_chi: ">= 0.8.1"
+# models: in small-models.yml (guardrails.small_models) needs 0.8.1; git: in rules.yml needs 0.17.0
+requires_chi: ">= 0.18.0"
 files:
   guardrails.md: sha256:04207fd1738aeeeef3b7a8053fc57597565bddd7862f01acaba784419cbd909b

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

@@ -60,7 +60,7 @@ Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_D
 - `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
 - `models:` map of model id or alias → `{profile, vision, sampling, thinking}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: `--thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
-- `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; config.yml only, like every `guardrails` setting: no env variable), `parent_approvals` (`off`, the default: a parent agent's `chi answer` can only deny an approval; `once`: it may give "Allow once" too; a convention for an honest parent, not a security boundary, and the user's choice: set it only when the user asks), `rules:` (list), `disable:` (a rule id or a list of them, `id` or `bundle:id`, switching off a bundle's or config rule without editing it), `small_models` (`auto`, the default: small = 32B or less read from the name; a glob or list of globs; `[]` for none). A rule takes only `id`, `tool`, `command`, `path`, `models`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`); `models` (optional: `small`, a model-name glob, or a list; without it the rule is for every model); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules are read again on the next tool call after config.yml or a bundle's rules change: no restart needed. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
+- `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; config.yml only, like every `guardrails` setting: no env variable), `parent_approvals` (`off`, the default: a parent agent's `chi answer` can only deny an approval; `once`: it may give "Allow once" too; a convention for an honest parent, not a security boundary, and the user's choice: set it only when the user asks), `rules:` (list), `disable:` (a rule id or a list of them, `id` or `bundle:id`, switching off a bundle's or config rule without editing it), `small_models` (`auto`, the default: small = 32B or less read from the name; a glob or list of globs; `[]` for none). A rule takes only `id`, `tool`, `command`, `path`, `git`, `models`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`: outside the session's repo, tmp folders and memory files excepted), `git` (only `outside_repo`: a shell call runs commit/add/reset/… in another checkout); `models` (optional: `small`, a model-name glob, or a list; without it the rule is for every model); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules are read again on the next tool call after config.yml or a bundle's rules change: no restart needed. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
 
 ```yaml
 guardrails:

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.16.0
+version: 0.18.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:0410c2e62716e256a2a6aec73c7801def185cbae9c1db556efcedbbad22d908c
-  config_modification_protocol.md: sha256:d0e9d4a84652bf54ec2fd664f61c536637af9decdd22fcd982f52195bf9f5fb4
-  memory_guide.md: sha256:81b911b9a015f0924c48162b3dc4b6376309e743765074419a99fab46e480858
+  self_map.md: sha256:69bc0ec091fdaeedf6e3aa7365275461fe3eba32b2dedc9cf45044176c356af5
+  config_modification_protocol.md: sha256:8d8921854e616d840b393cdda6fd911b7d5e8172501bb8293c01f734121ccc21
+  memory_guide.md: sha256:e535e31fcf29b4b32c270042851ecdd5f412ef2e3c56b0076963e3e1f1a08ef8
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

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

@@ -16,7 +16,7 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 | `project` | `<system dir>/projects/<basename>_<hash>/` (`MemoryPaths.project_dir`: `basename(root)` + 8-char `MD5(root)`, root = `MemoryPaths.project_root`) | Repo-specific conventions, workflow, stack decisions |
 
 - The project root is the git repository: its common git dir, which every linked worktree shares. All worktrees and subdirectories of one repository share one project folder; the system prompt shows the resolved root and folder. Outside a repository the root is the working directory. A separate clone is a different project.
-- `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write` (and refreshed when `write`/`edit` change a memory's file).
+- `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`; a memory a bundle installed adds `· from <bundle>` before the description. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write` (and refreshed when `write`/`edit` change a memory's file).
 
 ## Tools you have
 
@@ -85,13 +85,13 @@ 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. Writes provenance to `.bundles/<name>/` (base snapshots + `manifest.json`) and updates `index.md`. Warns on double-brace placeholders and checksum mismatches (strict mode). |
+| `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. |
-| `uninstall <bundle> [--force]` | Removes bundle files (skips locally edited files unless `--force`) and `index.md` lines, deletes provenance dir. |
+| `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. |
 | `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 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. |
+| `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. |
 
 **Scope resolution for install/build:**
 - CLI `--scope` wins over `manifest.yml` `scope`. Default is `system` if none given (`Installer#run`). For `project`, target is the project folder `<system dir>/projects/<basename>_<hash>` of the project root (`Installer#resolve_target_dir`).
@@ -119,7 +119,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.
-- `index.md` is best-effort — failures are swallowed (`Installer#update_target_index`).
+- 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
 

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

@@ -3,6 +3,7 @@
 ## Start here
 - `chi self` (via `execute`) prints my version, **source dir**, config path, hooks dir,
   memory dirs, sessions dir, model/host and bundles. Use its source dir; don't hunt via `which`/`gem list`/`find /`.
+  Its `model` row is this session's model (live after `/model`), `model key` my overlay key.
 - My current session id is in the system prompt; resume with `chi --resume <id>`.
 - My debug log is the `log` line of `chi self` (default `$XDG_STATE_HOME/samagotchi/samagotchi.log`,
   next to the sessions dir; not `~/.local/state` when `XDG_STATE_HOME` is set). One record per line,

data/lib/samagotchi/commands/registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "did_you_mean"
+
 module Samagotchi
   module Commands
     # The slash (and bang) commands a session knows, in lookup order: the
@@ -74,6 +76,32 @@ module Samagotchi
 
       def command?(line) = !lookup(line).nil?
 
+      # A line that is one word: a slash and a name, no spaces, no second
+      # slash. `/modle` is one; `/foo bar` and `/usr/bin/env` are not (they
+      # are prompts).
+      UNKNOWN_COMMAND_WORD = /\A\/[A-Za-z][A-Za-z0-9_-]*\z/
+
+      # Whether +line+ is a command word no command answers: a typo like
+      # `/modle`, which a UI must not send to the model as a prompt.
+      def unknown_command_word?(line)
+        text = line.to_s.strip
+        return false unless UNKNOWN_COMMAND_WORD.match?(text)
+
+        lookup(text).nil? && lookup_local(text).nil?
+      end
+
+      # What a UI shows for an unknown command word, or nil when +line+ is
+      # not one: `Unknown command /modle. Did you mean /model? /help lists
+      # the commands.` The "Did you mean" part needs a close name among the
+      # entries (DidYouMean::SpellChecker).
+      def unknown_command_hint(line)
+        return nil unless unknown_command_word?(line)
+
+        text = line.to_s.strip
+        close = DidYouMean::SpellChecker.new(dictionary: @entries.map(&:name)).correct(text).first
+        "Unknown command #{text}. #{close ? "Did you mean #{close}? " : ""}/help lists the commands."
+      end
+
       # @return [Entry, nil] the first entry the UI runs itself (local) that
       #   matches +line+, whatever its uis (a UI answers the others' too:
       #   the REPL's /detach note)

data/lib/samagotchi/config.rb

@@ -142,6 +142,12 @@ module Samagotchi
       # Asks again in the same turn after an empty answer (EmptyAnswerRetry);
       # 0 = off, capped at 3. No CLI flag: workers get no CLI args.
       Entry.new(key: "retry.empty_answer",       yaml_path: %w[retry empty_answer],       type: :integer, default: 1,               expose: %i[env config]),
+      # A turn's step limit: model ↔ tool rounds before it stops and offers to continue (IterationLimit); integer ≥ 1.
+      # --no-interrupt turns get max(1000, this). No CLI flag: --no-interrupt is the flag.
+      Entry.new(key: "turn.max_iterations",      yaml_path: %w[turn max_iterations],      type: :integer, default: 100,             expose: %i[env config]),
+      # Whether a parent agent (chi answer) may answer Continue to a session's step-limit question; false: Stop only.
+      # config.yml only, like guardrails.parent_approvals: a parent must not decide it from its own environment.
+      Entry.new(key: "turn.parent_continue",     yaml_path: %w[turn parent_continue],     type: :bool,    default: true,            expose: %i[config]),
       # What `chi update` touches; its --no-gem/--no-bundles/--no-desktop turn one off for a run.
       Entry.new(key: "update.gem",               yaml_path: %w[update gem],               type: :bool,    default: true,            expose: %i[env config]),
       Entry.new(key: "update.bundles",           yaml_path: %w[update bundles],           type: :bool,    default: true,            expose: %i[env config]),
@@ -161,7 +167,7 @@ module Samagotchi
       Entry.new(key: "execute.preview_bytes",           yaml_path: %w[execute preview_bytes],           type: :integer, default: 12_288, expose: %i[env config cli]),
       Entry.new(key: "execute.telemetry_threshold_pct", yaml_path: %w[execute telemetry_threshold_pct], type: :integer, default: 80,     expose: %i[env config cli]),
       # Seconds one execute command may run before it is stopped (Tools::Execute::TIMEOUT_SEC).
-      Entry.new(key: "execute.timeout_sec",             yaml_path: %w[execute timeout_sec],             type: :integer, default: 30,     expose: %i[env config cli]),
+      Entry.new(key: "execute.timeout_sec",             yaml_path: %w[execute timeout_sec],             type: :integer, default: 120,    expose: %i[env config cli]),
 
       Entry.new(key: "web.port",                 yaml_path: %w[web port],                 type: :integer, default: 4567,            expose: %i[env config cli]),
       Entry.new(key: "web.host",                 yaml_path: %w[web host],                 type: :string, default: "127.0.0.1",     expose: %i[env config cli]),

data/lib/samagotchi/continue_offer.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Samagotchi
+  # A session worker's continue offer: what it announces when a turn runs out
+  # of iterations, when a prompt or a reminder drops the offer, when a
+  # /continue answers it, and the continue turn a yes runs. TurnFlow keeps
+  # the offer itself (its checkpoint and context); this is the worker's side
+  # of it, which every UI hears about.
+  #
+  # The offer is also a question (kind "continue", the step-limit
+  # question), standing on the Engine's question desk between turns, so
+  # everything built on a pending question sees it: chi send --wait (exit
+  # 3), chi answer, the lists' waiting, the web's badge and bell. Its
+  # answer becomes the matching /continue line on the worker's command
+  # queue, which runs it as a typed one (#run_command's path).
+  class ContinueOffer
+    KIND = "continue"
+    HEADER = "Step limit"
+    CONTINUE = "Continue"
+    STOP = "Stop"
+    PROMPT_PREVIEW = 200
+    # last_turn's outcome after a Stop: no turn ran, but the wait of
+    # whoever answered (chi answer) ends on it.
+    NOT_CONTINUED = "not_continued"
+
+    # @param engine [Engine] announces, records activity, holds the question
+    # @param turn_flow [TurnFlow] owns the offer
+    # @param run_turn [#call] (prompt, **turn_args, &block) the worker's
+    #   run_engine_turn
+    # @param max_iterations [#call] (no_interrupt) → Integer
+    # @param queue_command [#call] (line, client_id:) queues a session
+    #   command as a card's (Bridge#queue_command, card: true)
+    def initialize(engine:, turn_flow:, run_turn:, max_iterations:, queue_command: nil)
+      @engine = engine
+      @turn_flow = turn_flow
+      @run_turn = run_turn
+      @max_iterations = max_iterations
+      @queue_command = queue_command
+      # A question was posted since the last close (it may have been
+      # answered or superseded meanwhile).
+      @asked = false
+    end
+
+    attr_writer :queue_command
+
+    def awaiting? = @turn_flow.awaiting_continue?
+
+    # TurnFlow keeps the checkpoint (a cancelled turn's, for !rollback) and
+    # the continue offer of a turn that ran out of iterations; an offer made
+    # (or kept, after a cancelled continue turn) is announced and asked.
+    def after_turn(result, continue: false, no_interrupt: false)
+      outcome = @turn_flow.after_turn(result, continue: continue, no_interrupt: no_interrupt)
+      return unless outcome == :continue_offered || outcome == :continue_cancelled
+
+      open
+    end
+
+    # A prompt (or a reminder turn) taken while a continue is offered
+    # replaces the answer (D2): the offer goes, the partial turn stays.
+    def drop(origin)
+      return unless awaiting?
+
+      close("dropped")
+      @engine.synchronize_events do
+        @turn_flow.drop_offer!
+        @engine.announce(type: :continue_resolved, decision: "dropped", client_id: origin&.dig(:client_id))
+      end
+      @engine.record_activity
+    end
+
+    # Whether a command's +result+ answered the offer that was pending
+    # (+awaiting+) as it started.
+    def resolved?(awaiting, result)
+      awaiting && result.decision && result.decision != :invalid ? true : false
+    end
+
+    # Called with the event log held, before the command's command_ran. A
+    # Stop runs no turn: last_turn says so (not_continued), so a wait on
+    # it ends (chi answer --option Stop).
+    def announce_resolved(result, command)
+      @engine.announce(type: :continue_resolved, decision: result.decision.to_s, client_id: command[:client_id])
+      return if result.resume
+
+      session = @engine.session
+      session.last_turn = { "outcome" => NOT_CONTINUED, "ended_at" => Time.now.iso8601(3) } if session
+    end
+
+    # After a command's command_ran and save: a /continue that answered the
+    # offer closes its question; a command that dropped the offer
+    # otherwise (!rollback) too.
+    # @param resolved [Boolean] it answered the offer (#resolved?)
+    def after_command(result, resolved:)
+      close(resolved ? "answered" : "dropped") unless awaiting?
+      return unless resolved
+
+      # An offer answered without a turn ("no") is activity: the recap
+      # written at the offer (it says the turn stopped) gets rewritten.
+      @engine.record_activity unless result.resume
+    end
+
+    # The continue offer was answered yes: resume the conversation without a
+    # user message, with the iteration limit the offer's turn had. A failure
+    # keeps the offer, as the REPL does ("continue prompt preserved"), and
+    # asks again.
+    def run_continue_turn(command)
+      offer = @turn_flow.offer
+      close("answered")
+      @turn_flow.before_continue_turn
+      @run_turn.call(nil, continue: true, origin: { client_id: command[:client_id] }.compact,
+                          max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
+        if error
+          open(offer)
+        else
+          after_turn(result, continue: true, no_interrupt: offer[:no_interrupt])
+        end
+      end
+    end
+
+    # The question goes (the offer went, or was answered).
+    # @param reason [String] dropped, answered
+    def close(reason)
+      return unless @asked
+
+      @asked = false
+      @engine.withdraw_question(reason)
+    end
+
+    private
+
+    def open(offer = @turn_flow.offer)
+      @engine.announce(type: :continue_offered, context: offer[:context], no_interrupt: offer[:no_interrupt])
+      ask
+    end
+
+    # Post the step-limit question while the offer stands (again, after a
+    # question that superseded it closed).
+    def ask
+      return unless awaiting?
+
+      @asked = true
+      @engine.post_question(question_fields(@turn_flow.offer), on_answer: method(:answered),
+                                                               on_superseded_close: method(:ask))
+    end
+
+    def question_fields(offer)
+      limit = limit_of_last_turn
+      context = offer[:context] || {}
+      text = "The turn ran out of iterations#{" (#{limit} steps)" if limit} before it answered. Continue it?"
+      prompt = context[:original_prompt].to_s.strip
+      unless prompt.empty?
+        prompt = "#{prompt[0, PROMPT_PREVIEW].rstrip}..." if prompt.length > PROMPT_PREVIEW
+        text += "\nPrompt: #{prompt}"
+      end
+      { kind: KIND, header: HEADER, question: text, options: [CONTINUE, STOP], multi_select: false,
+        allow_freeform: true, limit: limit, context: context }.compact
+    end
+
+    # The limit the offer's turn ran out at (Engine's last_turn marker).
+    def limit_of_last_turn
+      last = @engine.session&.last_turn
+      last.is_a?(Hash) && last["exhausted"] ? last["limit"] : nil
+    end
+
+    # The question's answer as the /continue line a typed answer would be:
+    # Continue → yes; Stop → no; a text (with Stop, or alone) → no, <text>.
+    def answered(answer, client_id:)
+      text = answer[:freeform].to_s.gsub(/\s+/, " ").strip
+      line = if Array(answer[:selected]).include?(CONTINUE) then "/continue yes"
+             elsif text.empty? then "/continue no"
+             else "/continue no, #{text}"
+             end
+      @queue_command&.call(line, client_id: client_id)
+    end
+  end
+end