samagotchi 0.74.0 → 0.76.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: baa839500eb96519376830a675e787eab121aab4c8de33fa72ffa3f007469643
-  data.tar.gz: 17e32518eaf7348ec4a08514a302a14139d71369904602815662186d9dfa584d
+  metadata.gz: c2bec0eb4ac3d46dcca5ca46f2496c4c419d1373ea595fcceae35d5a96098899
+  data.tar.gz: b9be22b2481f7489457eceb98eb1ace0cc3b58988ab34790d0c40197dc586ccc
 SHA512:
-  metadata.gz: 4f52356f77fe80e1cb56f3d28c4c7844c08ca4291ee3090a89f18a13261b5ee8db5d2b77835da6b756a118e3a30000b5fe2160f3de255f90ee30294728b0edd9
-  data.tar.gz: 88d10148534c0e9daaa6b5f97356b9b4f55311a25fa591ca48f70422f5c3cd128d9204b9bf7ea3f65e71c5fd26b7554de1571ddc650311ed1ab0af67eb4073fe
+  metadata.gz: f8d1c6f29de97f66b9ece157418f02628939f98c9a94926bbde5536fd2e1d126ca42cfce51497290f32e225d0ac169b81eda6e4aa1836c1d4d7bdd94d1d4c929
+  data.tar.gz: 9811070c6def3fe473d2e5fba2a044c25e1d843c12097b738a14854e1a9c6064e84f1b77ae56960166fceac101eb06aca6cbcb03c148e3017c034594cdb246a0

data/CHANGELOG.md

@@ -8,6 +8,71 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.76.0] - 2026-10-17
+
+### Security
+
+- A bundle can no longer replace an installed one by taking its name. `chi bundle install` over a bundle from another
+  source is refused (`--force` too): `chi bundle upgrade <new source>` switches the source and says
+  `Source changes: <old> → <new>`. A name chi ships (`guardrails`, `samagotchi-system`, …, in any letter case)
+  installs only from chi's own copy unless `--force`, and a name that differs from an installed one only in case is
+  refused.
+- A bundle's symlinked memory is no longer installed: a tar, zip or git repo whose `notes.md` linked to another file
+  (`~/.ssh/…`, an API key) copied that file into the memories the model reads. It is skipped with
+  `notes.md is a symlink (not installed)`; a linked hook or guardrail rule is skipped too, and a linked plugin or
+  script fails the install.
+
+### Added
+
+- `/stats`, `chi sessions stats` and the web's ctx tooltip split tokens, cost and speed per model after a `/model`
+  switch: a row per run of turns on one model, each switch's prefill under it, and a total.
+- Docs: [chi-nah](https://github.com/dm1try/chi-nah), an external guard bundle, in docs/guardrails.md.
+
+### Changed
+
+- A bundle installed from a git URL is named by its manifest's `name:` (it took the repo's name), so a URL install and
+  a local copy are one bundle. One installed by URL before this under a different repo name: `chi bundle uninstall
+  <repo name>`, then install it again (chi says so).
+- The `core` and `dev` profiles require the chi their members need (0.60.0 and 0.72.0).
+
+### Fixed
+
+- After `/model` the ctx % no longer shows the old model's window: it uses the new model's window at once, or shows
+  `ctx ?` (tooltip `Context window unknown until the next request`) until the window is known. The same for a session
+  resumed or woken on another model.
+- `/stats` no longer counts a `/model` to the same model on another host as a re-prefill.
+- Web: switching sessions while a command or a restored prompt re-reads no longer draws it in the session just
+  opened; a command's answer no longer clears another session's draft; such failures are a toast, not an alert.
+- `chi bundle install|upgrade`: an invalid or missing `manifest.yml` fails with one clear line (no backtrace, no
+  "falling back to install"); a manifest `name:` that is a path is refused; a plain re-install keeps the record of
+  files the bundle stopped shipping, so the upgrade it suggests trashes them; `chi bundle upgrade` with no source
+  prints the full usage line.
+- codex-peer: a send no longer hangs when `codex queue` exits but leaves a process holding its output; it stops
+  after 10 s and says the message may already be queued.
+
+Update with `chi update` (the system bundle 0.76.0, `core` 0.3.1, `dev` 0.5.1, `codex-peer` 0.3.2), then restart
+`chi web`.
+
+## [0.75.0] - 2026-10-17
+
+### Changed
+
+- Web: a session chain's links are numbered `#N` instead of `day N` (the chip `↩ #3`, `#2 of 3`; its popover's rows),
+  since a chain may be continued several times a day. The info bar's ← / → show the neighbour's time (`← 09:12`) when
+  it started on the open link's day, else its date, with its full start in the tooltip; a popover row adds its time
+  when another link of the chain started the same day. The carry note names the previous link's start with its time
+  (`This session continues 3fa2c1d0 (2026-10-17 09:12), …`).
+
+### Fixed
+
+- `chi bundle install` / `upgrade` no longer make a bundle repo's README, CHANGELOG, LICENSE, CONTRIBUTING,
+  CODE_OF_CONDUCT or SECURITY file a memory, and a manifest whose `files:` lists memories installs only those (an
+  unshipped name warns). An upgrade moves such a file an older install made a memory to the trash. Older chi still
+  installs every top-level `*.md` (`requires_chi` doesn't gate memories): a bundle for it too names its readme
+  `README.markdown`. `rake bundles:check` fails a shipped bundle's `*.md` that its `files:` doesn't list.
+
+Update with `chi update` (the system bundle 0.75.0), then restart `chi web`.
+
 ## [0.74.0] - 2026-10-17
 
 ### Changed
@@ -3156,7 +3221,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.74.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.76.0...HEAD
+[0.76.0]: https://github.com/dm1try/samagotchi/compare/v0.75.0...v0.76.0
+[0.75.0]: https://github.com/dm1try/samagotchi/compare/v0.74.0...v0.75.0
 [0.74.0]: https://github.com/dm1try/samagotchi/compare/v0.73.0...v0.74.0
 [0.73.0]: https://github.com/dm1try/samagotchi/compare/v0.72.0...v0.73.0
 [0.72.0]: https://github.com/dm1try/samagotchi/compare/v0.71.0...v0.72.0

data/docs/architecture.md

@@ -327,10 +327,16 @@ which `SessionMetrics#persist` rewrites after each turn; the web server merges t
 The totals' `tokens` block adds the cached, cache-write and reasoning sums, the reported cost (`cost_sum`) and the
 estimated one (`cost_estimate_sum`, from `hosts.<name>.models` prices; 0 for none), the decode time and tokens
 behind the average speed (`avg_decode_tps`) and the last speeds (`last_decode_tps`,
-`last_prefill_tps`, `tps_source`: `server` or `estimate`). Each `generation_completed` event
+`last_prefill_tps`, `tps_source`: `server` or `estimate`). `model_segments` (always present) splits those sums
+by model after a `/model` switch: one row per run of consecutive turns on one model (`SessionMetrics::ModelSegment`,
+keyed on the turn records' `model_ref`), in order, with its turns, token and cost sums, speeds and the switch's prefill
+(`prefill_tokens`, `prefill_cost_estimate`: the sums of its turn records' `switch_prefill_tokens` and
+`switch_prefill_cost_estimate`, [sessions.md](sessions.md)); `[]` with one model, the oldest rows folded into one (`folded_segments`)
+past 6; a running turn counts in its model's row (`ended_at` null). The rows add up to `tokens`. They are derived from
+the records, never read back. Each `generation_completed` event
 carries the generation's `speed` (`{decode_tps, source}`, null without one), its own prompt-cache
 counts (`prompt_tokens`, `cached_tokens`, `cache_write_tokens`: null when the server reported no writes) and
-those running `tokens`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
+those running `tokens` and `model_segments`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
 it, so the web's info bar updates per generation without parsing chunk payloads.
 
 The page's frequent reads of `GET /api/sessions/:id` stay light too:
@@ -504,6 +510,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 |---|---|---|
 | Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). The session is saved from the turn's thread, Bridge threads and a signal's thread; `Session#save` takes a per-session lock around its snapshot and write, so an older snapshot never lands over a newer one. |
 | Config | `config.rb` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)). |
+| Paths | `paths.rb` (`Paths`) | The XDG base dirs chi's files live under, read from the env on every call: `Paths.state_home` (`$XDG_STATE_HOME`, else `~/.local/state`) and `Paths.config_home` (`$XDG_CONFIG_HOME`, else `~/.config`), both defaults under `Dir.home`; a blank variable counts as unset, a relative one is made absolute from the current directory. `Paths.tilde` shows a path with `~` for the home folder. `SessionManager` hands a spawned worker the spawner's `XDG_STATE_HOME` / `XDG_CONFIG_HOME`, when set, made absolute, so a relative one isn't read from the session's folder. |
 | MemoryBundle | `memory_bundle.rb`, `memory_bundle/{installer,builder,installed_bundle,plugin_ref,bundle_hook}.rb` (`Installer`, `Builder`, `InstalledBundle`, `PluginRef`, `BundleHook`) | Installing, building and reading bundles of memories, hooks and plugins. |
 | Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/tool_spec.rb` (`Plugin::ToolSpec`: a checked tool declaration, how it is registered), `plugin/loader.rb` | What a bundle's plugin registers: tools, commands, annotation actions, hooks, services, toolkits, peer sources ([plugins.md](plugins.md)). |
 | Peer bundles' base | `plugin/peer.rb` (`Plugin::Peer`) | What claude-peer and codex-peer share (the send tool, the command, the cards, payloads); each bundle's subclass sets its strings and transport ([plugins.md](plugins.md#the-claude-peer-bundle)). |
@@ -515,8 +522,8 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Idle work | `idle_scheduler.rb` (`IdleScheduler`), `idle_recap.rb` (`IdleRecap`), `idle_reminders.rb` | One poller for an idle session's recap and reminders. |
 | Attached context | `context_sources.rb` (`ContextSources`), `context_poller.rb`, `context_absorber.rb`, `peer_sources.rb` (`PeerSources`: the sources peer bundles declare) | External sources a session keeps fresh, and the peer loop's wakes ([context.md](context.md)). |
 | LLM context strategies | `llm_context_strategy.rb`, `llm_context_view.rb`, `llm_context_stale.rb`, `llm_context_forget.rb` | What a request sends of the history (none, stale, forget) ([internals/llm-context-forget.md](internals/llm-context-forget.md)). |
-| Session chains | `session_continue.rb` (`SessionContinue`), `session_chain.rb` (`SessionChain`) | A session that continues an earlier one. |
-| Analytics | `analytics_file.rb` (`AnalyticsFile`) | A session's `analytics.json` (`SessionMetrics#persist`). |
+| Session chains | `session_continue.rb` (`SessionContinue`), `session_chain.rb` (`SessionChain`) | A session that continues an earlier one. `SessionChain.opener_for` gives the text web `continue →` prefills in the new link: the previous link's own first typed message when that link continues one itself, else nil (the 201's `opener`; not saved) ([sessions.md](sessions.md)). |
+| Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows). |
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
 | Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
 | Tool index | `tools/tool_index.rb` (`Tools::ToolIndex`) | `find_tools` and `call_tool`: the tools a session knows but doesn't declare one by one (an mcp bundle's servers through `chi.tool_source`, the built-ins its toolkit leaves out), searched and called by name ([plugins.md](plugins.md)). |

data/docs/cli.md

@@ -469,7 +469,17 @@ prompt (last, server)`); for other servers it is estimated from the first
 streamed chunk to the end and marked `~` (`~64 tok/s out (last, estimate)`).
 Generations under 8 tokens or 100 ms get no speed of their own, nor does a
 reply without server token counts or a non-streamed one. A delegated child
-keeps its own numbers: a parent's tokens and cost leave them out. `/recap` is in
+keeps its own numbers: a parent's tokens and cost leave them out.
+
+After a `/model` switch (or a hook's) the tokens line becomes a `models:` block, a row per run of turns on one
+model, in order (A → B → A is three rows): the model (`host:model` as asked), when (`10:43–now` while it runs; with
+the day when the rows span several), turns, tokens in/out, its average speed and cost. Under the row of the model
+switched to, `└ switch prefill 58.0k uncached prompt ≈$0.01` says what its first request prefilled on the new model
+(the prompt less the cached reads; `≈` an estimate from the new model's configured price, left out without one). A
+`total` row ends the block. The speed line names the model of its last speed, and the cost is from `each model's host
+prices`. Past 6 rows the oldest fold into one `N earlier segments` row; a session's turns from before chi recorded
+their model are one `earlier turns` row. One model: the output is unchanged. `chi sessions stats` prints the same,
+also offline (from the saved records). `/recap` is in
 [Session recap](#session-recap), `/model` and `/models` in [Runtime Model
 Switch](#runtime-model-switch-assist-mode).
 
@@ -889,6 +899,8 @@ In interactive assist mode, you can switch the request model without restarting:
 Notes:
 
 - The switch updates the request `model` field, routes to the matching host (`HostRegistry#resolve`), and resolves the prompt profile again (config, the server's chat template, the name; see "Prompt profile" in configuration.md).
+- The ctx % follows the switch at once: the last turn's count against the new model's window (the web's info bar, the attached TUI's status row, a client that joins later), recounted at the next generation. When the new window can't be resolved the web shows `ctx ?` and the attached TUI's status row drops its ctx until then ([context telemetry](internals/context-telemetry.md)).
+- After a switch `/stats` (and the web's ctx tooltip) splits the session's tokens, cost and speed per model, with what each switch prefilled on the new model: the `models:` block ([Session commands](#session-commands)).
 - Without `--default` the command is session-scoped and does not rewrite config files.
 - With `--default` the new default is written to `~/.config/samagotchi/config.yml` (honoring `XDG_CONFIG_HOME`) and takes effect for all new sessions; the current session's effective model is also updated immediately. Bare aliases and `host:model` are both valid.
 - `--default` and `--alias` change only their one key's line in `config.yml` (`default.model`, or the alias under `model_aliases:`): comments and the rest of the file stay as written, a symlinked file is written through and keeps its mode. When the edited text wouldn't read back as the expected settings (a flow-style section, anchors), chi writes the whole file out from the parsed data instead, which drops its comments.

data/docs/configuration.md

@@ -836,9 +836,10 @@ cache:
 ```
  Each request's own counts are in the debug log's `generation_completed` line:
 `prompt=` (its prompt tokens), `cached=` (read from the server's cache), `cache_write=` (written to it, when the
-server reports writes) and `reprefill=` (of the previous request's prompt on the same model, what the server
-prefilled again: an `llm_context` edit's cache break, or anything else that rewrote the prompt's middle; only when the
-server reports a cached count, and not on the first request after a warm-up); recap and side requests log theirs as `recap request_usage`.
+server reports writes) and `reprefill=` (of the previous request's prompt on the same model through the same host,
+what the server prefilled again: an `llm_context` edit's cache break, or anything else that rewrote the prompt's
+middle; only when the server reports a cached count, and not on the first request after a warm-up; a `/model` to the
+same model on another host is the switch's prefill, not a re-prefill); recap and side requests log theirs as `recap request_usage`.
 
 ## Llama Model Routing
 

data/docs/guardrails.md

@@ -568,6 +568,15 @@ next start.
 The system prompt names the home directory once, with the advice to write
 it as `~` or `$HOME`, so the model rarely has to spell it.
 
+## An external guard: chi-nah
+
+[chi-nah](https://github.com/dm1try/chi-nah) is a bundle kept in its own repo (`chi bundle install
+https://github.com/dm1try/chi-nah`). Its `before_tool_call` hook asks
+[nah](https://github.com/manuelschipper/nah)'s deterministic guards about every `execute`, `task_create`,
+`read`, `write` and `edit`: a call nah blocks (secret exfiltration, `rm -rf ~`, `git reset --hard`,
+`curl | sh`…) is denied with the guard's name and how the user pauses it (`nah nap <guard>`); everything
+else goes to chi's own rules. It needs nah installed; see its README for the settings.
+
 ## Failing closed
 
 - A config hook with `required: true`, or a bundle `before_tool_call` hook with

data/docs/internals/anthropic.md

@@ -38,7 +38,9 @@ Paths are under `lib/samagotchi/llm/`.
 
 `AnthropicMessages.for(entry)` takes the host's API root, key variable, `auth:`, `dialect:` and remoteness;
 `HostRegistry#adapter_for` keeps one per host for the worker's life, so what it learns from a 400 (below) lasts that
-long. Each request posts `{base}/v1/messages` with `anthropic-version: 2023-06-01`, the key in the header the host's
+long. Each request posts `{base}/v1/messages` with `anthropic-version: 2023-06-01`, the key (`LLM::ApiKey`: the
+variable `api_key_env:` names, else, on macOS, the login Keychain's item for that name, `HostKeys`; configuration.md,
+"API keys from the Keychain") in the header the host's
 `auth:` names (else the dialect's: `x-api-key` on the standard one), and `Session-Id` (plus the dialect's
 `session_header`) when the loop has a session id.
 

data/docs/internals/bundles.md

@@ -22,9 +22,12 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 
 | Piece | Role |
 |---|---|
-| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash`; runs the Installer, prints its summary, runs the conflict agent step |
+| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash`; runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it) |
 | `SourceNormalizer` (source.rb) | source → local dir; a git/zip/tar extract is *owned* and removed after the install |
-| `Manifest` | parses/validates `manifest.yml` (files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
+| `SourceIdentity` (source.rb) | what a source is, for comparing two installs of one name: `shipped:<dir>` (any gem or checkout), `git:<url>` (no `#ref`, trailing `/` or `.git`), `path:<realpath>`; nil when it can't place one |
+| `PreparedSource` (source.rb) | one source normalized once (dir, owned, git commit): `BundleCommand` reads the bundle's name from its `manifest.yml` (the name for every kind of source, a git URL too) and hands it to the Installer (`prepared:`), so a source is cloned or extracted once per command |
+| `MemoryFiles` | which top-level `*.md` files of a bundle are its memories (`.select`: the `files:` list, else all but README/LICENSE and the like), `.unshipped` (listed, not shipped) and `.symlinks` (skipped: a symlink is never a memory) |
+| `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
 | `Installer` | one install/upgrade/dry run of one bundle (below) |
 | `AssetInstaller` | the parts that live in `.bundles/<name>/`: hooks, guardrail rules, plugin, scripts; returns `AssetInstaller::Installed` (the paths the record keeps) |
 | `Merger` | 3-way classification per file: `install`, `fast_forward`, `keep`, `noop`, `conflict` |
@@ -47,19 +50,30 @@ and checks the recorded sha256 (and `requires_chi`) before loading.
 The order matters: warnings print in it, and a plugin/script the manifest names but the bundle lacks raises
 `InstallError` after the memories are already copied.
 
-1. `load_source`: normalize, read `manifest.yml` (strict: a missing/invalid one raises; non-strict: a warning).
-2. `resolve_target`: scope = CLI > manifest > `system`.
-3. `install_memories`, per `*.md`: an upgrade 3-way merges the files the bundle owns (`merge_memory`), a dry run only
+1. `load_source`: normalize (or take the `PreparedSource` `BundleCommand` passed as `prepared:`), read `manifest.yml` (strict: a missing/invalid one raises; non-strict: a warning).
+2. `resolve_target`: scope = CLI > manifest > `system`; then `check_source` against the existing record
+   (`SourceIdentity`, source.rb): a name differing from an installed one only in case raises (`force` too); a
+   shipped name (any case) from a source that isn't a dir in the Installer's `shipped_dir:` (default `SHIPPED_DIR`;
+   ShippedUpdate, Profile and SystemBundle pass theirs) raises unless `force` (a recorded source is matched by the
+   `SHIPPED_SOURCE` path pattern instead, for older gems); a plain install
+   over a record from another source raises (`force` too); an upgrade may switch sources and sets
+   `#source_change` (the summary's first line, `Source changes: old → new`). A source `SourceIdentity` can't place
+   (an older record's relative path) never refuses.
+3. `install_memories`, per memory (`MemoryFiles.select`: a non-empty `files:` list, else every top-level `*.md` but
+   README, CHANGELOG, LICENSE and the like; a listed name not shipped warns; a symlink is skipped with a warning): an upgrade 3-way merges the files the bundle owns (`merge_memory`), a dry run only
    classifies (`preview_memory`), a plain install writes new files and skips existing ones (`skip_existing`). A
    same-name file the bundle didn't write is the user's: skipped and never recorded (`@owned`). Model overlays
    (`<name>.<key>.md`) get no index line (`note_overlay`).
 4. `AssetInstaller#run`: hooks (manifest-listed, else every `hooks/*.rb`), prune dropped hooks, hook checksums,
-   guardrails, plugin, scripts; each set replaces the previous version's. requires_chi warnings for hooks/rules.
+   guardrails, plugin, scripts; each set replaces the previous version's. requires_chi warnings for hooks/rules. A
+   file that is a symlink or resolves outside the bundle dir (`AssetInstaller#linked?`, a linked `hooks/` too) is
+   skipped with a warning (a hook or rule) or raises `InstallError` (the plugin, a script).
 5. An upgrade's `prune_dropped_files`: unchanged → trash; edited → kept (`kept_pruned`); owned by another bundle → kept.
 6. `verify_memory_checksums` (strict), `warn_missing_needs`.
 7. `write_provenance` (manifest, not a dry run): bases come from the incoming file, except where the user's edit was
    kept (kept/noop/conflict/kept_pruned, or a re-install's skipped edit): those keep the old base, so the next
-   upgrade still sees the edit.
+   upgrade still sees the edit. A plain install also keeps the record (the old base) of a file an earlier install
+   owned and this version doesn't ship, while it is on disk (`dropped_owned_files`), so the next upgrade prunes it.
 8. `detect_placeholders`.
 
 Results are `@results` (file → `{status:, reason:}`), summarised by `#summary`. An upgrade with conflicts keeps an

data/docs/internals/context-telemetry.md

@@ -34,6 +34,28 @@ Emission behavior:
   `context.status_thresholds` the top bucket reads critical, the one below it
   elevated, the next moderate, and the first bucket (and the rest below) healthy.
 
+After `/model` (`SessionCommands#switch_model`), the old model's percentage goes at once (`Engine#switch_model!`
+clears the kept status), and `Engine#announce_switched_context!` sends a `:context_status` of its own, outside any
+turn: the last turn's count (the old model's tokenizer's; the next generation replaces it) against the new model's
+window (`EffectiveModel#context_window`, the lookup below: the running server first, one `/props` GET that a remote
+chat host is spared; else the host's cached model list; else the configured window) and the session's budget,
+with `context_window_tokens` / `context_window_source` (the web takes the window
+from them) and `usage.source: "switch"`. It is kept for a client that joins later (`session_state_snapshot`'s
+`context_status`). A window that doesn't resolve sends `usage: null` and `context_window_tokens: null`: the web shows
+`ctx ?` and drops the old model's window (a chunk's usage then counts no %, until a `generation_started` brings a
+window), and the attached TUI's status row drops its ctx until the next generation (the web's ctx tooltip then says
+`Context window unknown until the next request` over the session's tokens, `ctxBarTip`, until that request starts;
+plain `Context window unknown` after it, and for a session whose window lookup failed). Nothing is sent before the
+session's first counted turn. A
+hook's switch (`before_turn`) sends nothing: its turn's first request counts on the new model anyway.
+
+A process that loads the session on another model than its last turn ran on (`Engine#session=`:
+`SessionMetrics#last_model_ref` differs from `effective_model_ref`; a `--resume`'d REPL with `--model`, a worker woken
+after a `/model` with no turn since) drops the old window (`forget_model_reports!`) and calls
+`announce_switched_context!(configured_only: true)`: the configured window only
+(`EffectiveModel#configured_context_window`, no `/props` GET or model list, since a worker runs it before its Bridge
+serves); without one, no percentage until the first generation reports the window.
+
 Under an LLM context strategy (`ContextStatus.new(llm_context:)`, the turn's `LLMContextStrategy::Resolved`, given by
 both loops):
 

data/docs/internals/engine.md

@@ -131,6 +131,13 @@ The effective model doesn't resolve (a broken host config, HostRegistry#resolve
   → session_state_snapshot never raises (its model fields are nil); a turn, stats_snapshot,
      chat_model? and system_prompt raise, as before
 
+A session's toolkit doesn't resolve (an unknown kit name: a typo, a bundle's kit that isn't installed; a base that
+doesn't resolve, a cycle), at a turn's start (ToolkitBinding#apply!):
+  → that turn declares the full kit with the session's own added and removed tools on top (Toolkit#resolve's
+     fallback); the saved toolkit stays as it is, so a reinstalled bundle gets it back
+  → each warning (that fallback, a config.yml kit with a problem: Toolkit.kits) logged once per process as
+     toolkit_unresolved (WARN), with a :guardrail_warning (label "toolkit") to the turn and the observers
+
 Stopped before the model was asked (prepare_turn returned false):
   → stopped_before_model(turn) → end_turn(turn, "canceled")
   → nothing kept, :turn_canceled {cancellation_reason, cancelled_by, duration_ms}
@@ -460,11 +467,11 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 |---|---|---|
 | `:turn_started` | `prepare_turn` | `{session_id, prompt, turn_id, continue?, resumed?, images?, cut_after}` (`resumed`: a step-limit Continue) |
 | `:reminder_injected` | due reminders went into the turn | `{reminders}` |
-| `:context_status` | every request (unless `context.status` is off), the current estimate before it | `{iteration, status, usage, bucket, source}` (internals/context-telemetry.md) |
-| `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source, price}` (`price`: the turn's `ModelPrice#to_h`, nil without one; native adds `profile`, `profile_source`) |
+| `:context_status` | every request (unless `context.status` is off), the current estimate before it; and outside any turn after `/model` (or when a session is loaded on another model than its last turn ran on), to the observers only (`Engine#announce_switched_context!`) | `{iteration, status, usage, bucket, source}`; the switch's form has no `iteration`: `{usage, bucket, context_window_tokens, context_window_source}`, with `usage.source: "switch"`, and `usage` nil when the new window doesn't resolve (internals/context-telemetry.md) |
+| `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source, price, model_ref}` (`price`: the turn's `ModelPrice#to_h`, nil without one; `model_ref`: the turn's model, asked `host:model`, added by the Engine's stream handler from the model `#generate` resolved after the `before_turn` hooks, so a hook's switch is the one named; native adds `profile`, `profile_source`) |
 | `:generation_chunk` | each streamed chunk | `{iteration, content, text, thinking, payload, tool_call?}` |
 | `:generation_retrying` | the transport retries the request, or the chat loop asks again for a step whose stream dropped mid-answer (`restarted: true`: what the step streamed is void, and the web's live step, the TUI's activity line, the Bridge's TurnAccumulator and the stream hooks' watch start it over) | `{iteration, attempt, max_retries, next_delay, error_class, error_message, status, restarted?}` |
-| `:generation_completed` | a generation ended, or was cut | `{iteration, content_length, thinking_chars, served_model, requested_model, finish_reason, ...}`; a cut adds `stopped_by`, `stop_reason`; the Engine adds `speed`, `tokens` |
+| `:generation_completed` | a generation ended, or was cut | `{iteration, content_length, thinking_chars, served_model, requested_model, finish_reason, ...}`; a cut adds `stopped_by`, `stop_reason`; the Engine adds `speed`, `tokens`, `model_segments` |
 | `:generation_cancelled` | the turn was cancelled mid-loop | `{iteration, reason, stopped_by}` |
 | `:empty_answer_retry` | an empty, cut or malformed answer is asked again | `{iteration, attempt, of, finish_reason, thinking_chars, stopped_by?, malformed?}` |
 | `:steer_cut` | a steer cut the generation | `{iteration, source}` |
@@ -526,6 +533,10 @@ Model switching, Engine#switch_model!(model_name, persist_default:, typed:):
     thread finishes for the old model is neither kept nor applied: #store_profile)
   → sync_model_key!, @prompt_builder.reset! (the system prompt is built again)
   → sync_kernel_client! (the kernel talks to the new host), the context window cache dropped
+  → the old model's ctx dropped: @metrics.forget_model_reports! (its window and profile reports) and
+    @last_context_status = nil; /model (SessionCommands#switch_model) then calls #announce_switched_context!
+    (the ctx % on the new model's window, before its first turn; Engine#session= does the configured-window-only
+    variant for a session loaded on another model; internals/context-telemetry.md)
   → the kernel is never rebuilt; the next turn's backend follows the new host's api
 
 Model probes (per turn):

data/docs/internals/prompt-caching.md

@@ -149,7 +149,8 @@ is prefilled once. The native and the chat loop use the same plan.
 
 - The debug log's `generation_completed` line: `prompt=` (the request's prompt tokens), `cached=` (read from the
   server's cache), `cache_write=` (written to it, where the provider reports writes) and `reprefill=` (of the last
-  request's prompt on the same model, what was prefilled again). The `http` line of a
+  request's prompt on the same model through the same host, what was prefilled again; a `/model` to the same bare
+  model on another host is the switch's prefill, not a re-prefill). The `http` line of a
   remote Claude or Messages request shows `cache=on` (or `cache=1h`) when it carried breakpoints.
 - The warm-up logs `model warmup` with `cached=`, `prefilled=` and `prefill_ms=`.
 - `/stats`: "cached N (P%)", "cache writes" and "re-prefilled" for the session.

data/docs/memory.md

@@ -199,7 +199,7 @@ step instead of fixing the skill.
 ## What a bundle owns
 
 A bundle owns the memory files it wrote, nothing else. `chi bundle install`
-copies each of its `*.md` files into the scope dir; a file of the same name
+copies each of its memories into the scope dir; a file of the same name
 that is already there is left as it is and reported `Skipped` (`--force`
 overwrites it, and then the bundle owns it). A skipped file stays yours: the
 bundle doesn't record it, so `chi bundle upgrade` never merges into it and
@@ -207,6 +207,53 @@ bundle doesn't record it, so `chi bundle upgrade` never merges into it and
 for `chi bundle build` then installing the result on the same machine, and
 for a file another bundle installed.
 
+- **Which files are memories.** A manifest whose `files:` lists any: exactly
+  those (a listed name the bundle doesn't ship gets a warning). Without a
+  list (no `files:`, or `files: {}`): every top-level `*.md` except a repo's
+  meta files: README, CHANGELOG, LICENSE (or LICENCE), CONTRIBUTING,
+  CODE_OF_CONDUCT and SECURITY, in any case. So a bundle kept in its own git
+  repo can have a `README.md` without it becoming a memory. A listed file is
+  installed whatever its name (`chi bundle build` of your own `security.md`
+  lists it). Since chi 0.75.0. Older chi installs every top-level `*.md`
+  whatever `requires_chi` says (it gates hooks, rules and the plugin, not
+  memories), so a bundle for older chi too names its readme
+  `README.markdown` (or puts docs in a subdirectory).
+  `chi bundle upgrade` moves a README an older install made a memory to the
+  trash (unless you edited it, like any file a bundle stops shipping).
+- **A symlink is never installed.** A memory that is a symlink is skipped
+  with `notes.md is a symlink (not installed)`, and so is a hook or guardrail
+  rule that is one or lives in a linked dir (`hooks/x.rb is a symlink (not
+  installed)`); a plugin or script that is one fails the install. A tar, zip
+  or git repo keeps links, and copying through one would install whatever
+  file it points at (`~/.ssh/…`, an API key) as a memory the model reads.
+- **A bundle is its name and its source.** A bundle's name is its
+  manifest's `name:`, for every kind of source (a git URL too), and a
+  manifest can take any name, so the source decides who installs under it:
+  - `chi bundle install` of a source whose manifest names a bundle
+    installed from another source is refused, `--force` too (`btw is
+    installed from <source>; chi bundle upgrade <new source> switches its
+    source, or chi bundle uninstall btw first`);
+  - `chi bundle upgrade` may switch the source (a git URL and a local copy
+    of it are one bundle; an archive's file name carries its version), and
+    its output starts with `Source changes: <old> → <new>` (`--dry-run`
+    too);
+  - a name chi ships (`guardrails`, `btw`, `samagotchi-system`, …, in any
+    case) installs or upgrades only from chi's own copy (a dir in the
+    running chi's shipped bundles, not a fork's `lib/samagotchi/bundles/`),
+    unless `--force` (`guardrails is a bundle shipped with chi; <source>
+    isn't chi's copy of it`);
+  - a name that differs from an installed bundle's only in case is refused,
+    `--force` too (`BTW differs only in case from the installed btw`): on a
+    case-insensitive file system (macOS) it is that bundle's dir.
+
+  Sources compare as a git URL without its `#ref` (or a trailing `/` or
+  `.git`), a shipped bundle by its dir in any chi version, and a path with
+  symlinks resolved. A git URL bundle chi 0.75.0 or earlier installed under
+  the repo's name (`chi-foo` for `name: foo`) isn't installed again beside
+  it: `chi bundle install|upgrade <url>` says `<url> is installed as
+  chi-foo: chi bundle uninstall chi-foo, then install it again`. That match
+  is by the same source, so a record of `git@github.com:x/foo` isn't found
+  from `https://github.com/x/foo` (uninstall it by name).
 - **The index says where a memory came from.** The `index.md` line of a file
   a bundle installed ends in `· from <bundle>`, before the description:
   `- **memory_guide** · system · 2026-10-03 · 5120 · from samagotchi-system —

data/docs/plugins.md

@@ -15,11 +15,12 @@ my-bundle/
   manifest.yml
   plugin.rb
   identity.md        # optional, like any bundle's memories, hooks/ and guardrails/
+  README.md          # never a memory (nor CHANGELOG, LICENSE, ...): see memory.md#what-a-bundle-owns
 ```
 
 ```yaml
 # manifest.yml
-name: my-bundle
+name: my-bundle               # the bundle's name for every source (a git URL too): a plain name, no / (not . or ..)
 version: 1.0.0
 plugin:
   file: plugin.rb

data/docs/releasing.md

@@ -13,7 +13,7 @@ can run the whole release; the user approves the notes before the tag and the
   and `rake release:check` enforce it). The system bundle upgrades itself when
   chi starts.
 - **Every other shipped bundle** (btw, check-in, guardrails, known-names,
-  loop-guard, mcp, skills, source-links, github-pr, coordinator, claude-peer, codex-peer, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, slow-commands, agents-md, source-links, github-pr, coordinator, claude-peer, codex-peer, and the profiles core and dev) has its own semver in its
   `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`
@@ -30,6 +30,10 @@ can run the whole release; the user approves the notes before the tag and the
     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
     have the profile;
+  - a profile's `requires_chi` is its members' highest: a member's raised
+    floor (by hand, or by `release:bump` for a `requires_chi_next` marker)
+    raises its profile's too, with the profile's version (`bundles:check`
+    notes a profile below a member);
   - the release notes say "run `chi update`" and name the bundles whose
     version moved (what changed in each), not per-bundle upgrade steps.
 - Pre-1.0: config and commands may change in a minor version (0.2 → 0.3); a
@@ -55,7 +59,7 @@ as the GitHub release body.
 | Task | What it does |
 | --- | --- |
 | `rake bundles:sha` | Recomputes the sha256 lines of every shipped bundle manifest (`files:`, `hooks:`, `plugin:`). |
-| `rake bundles:check` | Sha lines match; a bundle changed since the last `v*` tag has a higher version (skipped, with a note, before the first tag). Warns (doesn't fail) when such a bundle's `requires_chi` still admits the tagged chi: mark it `requires_chi_next` if the change uses anything new. Notes a bundle marked `requires_chi_next`. The release workflow and `release:check` run it in full. |
+| `rake bundles:check` | Sha lines match; every top-level `*.md` of a bundle is listed in its `files:` (an install takes only the listed ones); a bundle changed since the last `v*` tag has a higher version (skipped, with a note, before the first tag). Warns (doesn't fail) when such a bundle's `requires_chi` still admits the tagged chi: mark it `requires_chi_next` if the change uses anything new. Notes a bundle marked `requires_chi_next`, and a profile (`core`, `dev`) whose `requires_chi` is below a member's. The release workflow and `release:check` run it in full. |
 | `rake 'bundles:check[ci]'` | The CI workflow's (every push and PR): the same, except the version check leaves out the system bundle, which is changed and unbumped between releases (`release:bump` moves its version with VERSION). A task argument, not `CI=1`: GitHub sets `CI` in the release workflow too. |
 | `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). No commit. |