samagotchi 0.130.1 → 0.132.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcca1391e17e266cf83e1c56dec7ab52d21a1928a4c5190d2bf594884cca936f
-  data.tar.gz: fc59a582d279b19352c3bda61bb5d2fc3796ae0e079e52b3dcb26dc85988ea33
+  metadata.gz: ebe264e1dbd5adc620889aa40d66fd458519c64f038a3a3e5de06ee6a6da46e7
+  data.tar.gz: 3c72148287422c9821c25bc3979c71890fb4abad81af3829650aef3c13549a3f
 SHA512:
-  metadata.gz: b5cc1d80ca1b0d64f809360e111bdae2778772c5ca3c8cae7d6f339f650a55fb65b796ccc5ca3038b25c637223568a7facbc90a351ac5df77bee25c24fac3e59
-  data.tar.gz: 4e149d518537a529c69494f14b0d07435c6e3327d27ae34a42c0e30504c74fee543282c4023fbd44587a301f189c24bd7d3aebdff40235784bd45f95cfd63217
+  metadata.gz: f8ffaf8ca17c125a38af6a30432d8b14a66ea97df8201686acedca8dde11869845b0e2a6abe0f9ece18db4e5848f9340b2ef73910371977fafe9889d430eebad
+  data.tar.gz: e556232bbad1093cff1779510162a179b1284cc90bd8cc54d8082e2a4dab5e96f98bb6ebae5ef99ab82610a1bd33880c830cfae8b1076d1e6ca841c406ae45b3

data/CHANGELOG.md

@@ -7,6 +7,79 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.132.0] - 2026-10-29
+
+### Added
+
+- `chi home`, `chi home set [--ruby PATH]`, `chi home doctor`: the chi home, the one Ruby and gem path every chi
+  launch boots (`~/.config/samagotchi/home.json`). The first `chi bootstrap` or `chi update` records it once (the
+  desktop helper's Ruby when it has samagotchi, else chi's own); see docs/configuration.md (The chi home). A
+  write or edit of home.json asks, as config.yml does (rule `chi-home`, the user's alone).
+- Bundles: model-notes 0.2.0 ships `model_notes_tone` (`models: *`): every model answers first, in plain words, without
+  preambles or closing offers. Off with `chi --mute model_notes_tone`; your own note of that name wins.
+- Plugins: `chi.prompt_section(name) { |ctx| … }` adds a bundle's text to the system prompt's stable part (after the
+  toolkit's prompt, before the memory indexes), and `chi.prompt_changed!` builds the prompt again at the next turn.
+  A section that fails keeps its last good text; `/stats` names the sections (`prompt sections:`).
+- Plugins: a command can ask before a change that restarts the prompt cache, as `/thinking` does:
+  `ctx.cache_confirm(line, changed:)` gives a confirm for a person at a web tab or a TUI once the session has a
+  model reply, and the command returns `[text, confirm]` (the TUI prefills the `--yes` line, the web shows Apply).
+- Plugins: `ctx.model_names` lists the names chi looks the session's model up under (alias, target, ref, bare id),
+  so a bundle can match a per-model map the way config.yml's `models:` settings are matched.
+
+### Changed
+
+- With a chi home, every session worker (whoever starts or wakes it), chi web's restart and Update, `chi update`
+  and `chi bootstrap`'s commonmarker install run on it: the home's Ruby with its gem path set inside Ruby, never in
+  an env, so session tools keep the spawner's GEM_HOME/GEM_PATH. `chi update` from another Ruby runs the home's
+  (`updating the chi home (<ruby>)`) and installs into its gems; a worker whose home can't load chi logs one
+  `boot_failed` line instead of a silent spawn timeout. Without a home every launch is as before.
+- Desktop helper: `chi desktop install` and `upgrade` make it boot the chi home when there is one, and its launch
+  file no longer carries `RUBYLIB`, nor `GEM_HOME`/`GEM_PATH` when it boots the home (they reached every command its
+  sessions ran). `chi update` drops `RUBYLIB` from an existing one, and `GEM_HOME`/`GEM_PATH` once it boots the home.
+- `/model` asks before switching to another model once the session has a model reply, from a web tab or a TUI (the
+  new model has no cache of the conversation): the reply names the size it rereads and the line that applies it,
+  flags and all (`/model qwen --default --yes`); `--yes` (or `-y`) applies at once, and a typo is an error before any
+  question. `chi send`, delegates and `chi --model` on an attached or resumed session apply at once.
+- `/llm-context` asks the same way before the two changes that break the prompt cache now: `forget` turned on or off,
+  and a layer with applied stubs turned off (`/llm-context reset --yes` applies too). Turning `stale` on, the apply
+  rule and the budget don't ask; the web's `llm ctx` chip and `chi --llm-context` on an attached or resumed session
+  apply at once.
+
+Update with `chi update`, then restart `chi web` and the session workers (`chi sessions restart`): a new TUI's
+`--model X` on a worker from before this release switches it to the model "X --yes".
+
+## [0.131.0] - 2026-10-29
+
+### Changed
+
+- Web: the start page's composer row stays one row at any width: a long model name ellipsizes instead of pushing
+  Start to a second row.
+- Web: the start page's model button shows a short name (`openrouter · deepseek-v4.1-flash`: no org prefix, the tag
+  kept, the host only when it isn't the default); its tooltip and label keep the full name.
+- Cache: confirmations for prompt-cache changes estimate the reread size when known and warn that Anthropic drops
+  preserved thinking after a full-prefix change.
+
+### Fixed
+
+- Web: a Verify verdict card sits right after the answer it quotes, on your page and a participant's, instead of
+  under the turn's prompt, screens above the claim in a long turn. A quote the page can't find yet puts the card at
+  the turn's end.
+- Web: Verify on a claim in a model's reply on a participant's page records its verdict and shows the card again;
+  the claim was sent without its turn, so the check ran as a plain comment.
+- Web: after a fresh verdict lands on an unclear card, its button reads **Verify fresh again**: each press starts
+  another paid check (a participant's counts against their cap).
+- Web: Verify is offered only on a finished turn's final answer, on your page and a participant's: the one place a
+  verdict card can come from. Selecting an earlier reply, a step, a message, a line added mid-turn or a turn still
+  running no longer offers a Verify that silently ran as a plain comment; the bar keeps its other actions there.
+- Web: on a participant's page, a turn a delegate's report or a context note woke opens as "An automatic turn"
+  (still without the report or note). Its answer read as one more reply of the turn before: Verify was offered on
+  it and refused, and hidden on that turn's real final answer.
+- Web: Verify on a claim that names a file in the session's folder or your home folder (or holds a key) records its
+  verdict: the pages quote such a path relative, or with `~`, and the check compared it against the answer's full
+  path, so it ran as a plain comment with no card.
+
+Update with `chi update`, then restart `chi web` and the session workers (`chi sessions restart`).
+
 ## [0.130.1] - 2026-10-29
 
 ### Fixed
@@ -4964,7 +5037,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.130.1...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.132.0...HEAD
+[0.132.0]: https://github.com/dm1try/samagotchi/compare/v0.131.0...v0.132.0
+[0.131.0]: https://github.com/dm1try/samagotchi/compare/v0.130.1...v0.131.0
 [0.130.1]: https://github.com/dm1try/samagotchi/compare/v0.130.0...v0.130.1
 [0.130.0]: https://github.com/dm1try/samagotchi/compare/v0.129.0...v0.130.0
 [0.129.0]: https://github.com/dm1try/samagotchi/compare/v0.128.0...v0.129.0

data/bin/chi

@@ -82,7 +82,9 @@ SUBCOMMANDS = {
   # audit suggestions for which toolkit fits a session's first prompt
   "toolkit" => ["samagotchi/toolkit_report_command", "ToolkitReportCommand"],
   # other machines' chi web, for chi --remote NAME (add, ls, rm)
-  "remote" => ["samagotchi/remote_command", "RemoteCommand"]
+  "remote" => ["samagotchi/remote_command", "RemoteCommand"],
+  # the chi home: the Ruby every chi launch boots (set, doctor)
+  "home" => ["samagotchi/home_command", "HomeCommand"]
 }.freeze
 # chi --remote NAME <command> (or CHI_REMOTE=NAME): the session commands
 # against another machine's chi web; what runs here only is refused (exit 2).

data/docs/architecture.md

@@ -133,6 +133,36 @@ terminal renders the events it gets over the Bridge.
 - In REPL mode `TerminalUI` builds the `Engine` in process (`-p` and `--non-interactive` too);
   otherwise the session's `Worker` (`lib/samagotchi/worker.rb`, spawned by `SessionManager`) builds it.
 
+## How chi launches itself
+
+chi starts chi in several places, and each must land on the same install whoever starts it (a terminal on another
+Ruby, chi web, the macOS helper under launchd). The **chi home** (`ChiHome`, `chi_home.rb`; recorded in
+`$XDG_CONFIG_HOME/samagotchi/home.json` by `chi home set`, or once by `chi bootstrap` / `chi update`:
+[configuration.md](configuration.md#the-chi-home)) names that install: a Ruby and its gem path.
+
+**One mechanism.** `ChiHome::Record#boot_argv(run:)` is `[home ruby, "-e", "Gem.paths = {'GEM_HOME' => …,
+'GEM_PATH' => …}; <run>"]`: the gem path goes into the boot string, never into an environment, so the tools a worker
+runs keep the spawner's GEM_HOME/GEM_PATH (or none), and a stray one in the spawner's env can't move chi off the
+home. `ChiHome::CHI_BOOT` (`gem 'samagotchi', '>= 0.a'; load Gem.bin_path('samagotchi', 'chi')`) plus `"--"` and
+the arguments runs the home's newest `chi`. Each site asks `ChiHome.current` at launch time; it is nil (and the site
+keeps its own argv, as before the home) without home.json, for one that isn't its shape (warned once), when the
+home's Ruby is gone, when no `samagotchi-*.gemspec` is under its gem path, and from a source checkout.
+
+| Site | With a home | Without |
+|---|---|---|
+| `SessionManager.worker_command`: every worker (attach, `chi send`, chi web, delegate and Verify-fresh children, `resume_session`, `:restart`) | the home's ruby, `Gem.paths`, `>= 0.a` with the fallback pin (`ChiHome.fallback_version`: the spawner's version when the home has it, else the home's newest; a home older than the spawner is warned once); a chi that still can't load writes one `boot_failed` line to `SAMAGOTCHI_LOG_FILE` and exits 1 | `RbConfig.ruby -e` with `>= 0.a` (a checkout: `-I lib`) |
+| `Web::Server.reexec_command` (chi web's restart) | `CHI_BOOT -- web …`; the `:no_wrapper` refusal never applies; a home whose newest chi is older than this one is passed over (logged `restart_home_older`) | `[RbConfig.ruby, wrapper, …]` (`$PROGRAM_NAME` in a checkout) |
+| `Web::App#update_argv` (the **Update** button's child) | `CHI_BOOT -- update --to V --no-desktop --json` | `[RbConfig.ruby, wrapper, update, …]` |
+| `UpdateCommand` | on another Ruby than the home (`Record#running_here?`): exec `CHI_BOOT -- update …` once (`SAMAGOTCHI_UPDATE_IN_HOME=1`: an older home chi ignores it); the install (`GemUpdate`) runs `ChiHome.gem_bin` with `ChiHome.install_env` (the home's GEM_HOME/GEM_PATH for that child, `mise`'s dir on PATH); the hand-over execs `CHI_BOOT -- update --no-gem --gem-from …` | this Ruby's `gem`, the wrapper |
+| `BootstrapCommand` (commonmarker) | `ChiHome.gem_bin` + `install_env`; installed? = in the home's specifications | this Ruby's `gem` |
+| `Desktop::MacOS#launch_config` | argv `CHI_BOOT + ["--"]`; `launch_ok?` / `launch_problem` check only absolute argv entries | `[ruby, wrapper or bin/chi]` |
+| `InstalledVersions`, `Web::UpdateCheck` | the home's specification dirs and gem dir | the running process's |
+
+Unchanged: `ContextProviders`' `{ruby}` (`RbConfig.ruby`: the home's ruby inside a home worker), `chi bundle
+try/test/check` (`-I LIB_DIR`), hooks (in-process). The worker's boot string, `run_session_loop(id, state_dir:)` and
+`SAMAGOTCHI_BOOT_FALLBACK` stay the cross-version contract (`spec/worker_contract_spec.rb`): the home only adds the
+prelude in front. An older chi that wakes a session doesn't read home.json and starts its worker as before.
+
 ## Session retention & ordering
 
 - **Files:** `~/.local/state/samagotchi/sessions/<uuid>.json` + `<uuid>/input|output|owner.lock|bridge.json` (XDG-aware), and the `<uuid>/stopped` and `<uuid>/archived` marker files.
@@ -227,7 +257,8 @@ The system prompt (`SystemPrompt#build`, assembled in `#system_prompt_with_index
 base prompt, then the toolkit's "Not loaded in this session" line (only when the toolkit
 leaves tools out), rg guidance, the identity, the model notes, the preloaded memories,
 AGENTS.md (root → cwd), the appended files (`--append-system-prompt`), the toolkit's
-kit prompt (a kit's `prompt:` text, only when it has one), the memory
+kit prompt (a kit's `prompt:` text, only when it has one), the plugins' prompt
+sections (`chi.prompt_section`, only when a plugin gives text), the memory
 indexes, and last **the model** (`Model: this session runs on <ref> (host …; model key …)` and a line telling
 the model to answer "which model are you" from it, not from training), the working
 directory and the session id and log (Gemma's native tool declarations still follow).

data/docs/cli.md

@@ -35,6 +35,7 @@
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
 - `chi update [--dry-run] [--to VERSION] [--json] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
+- `chi home`, `chi home set [--ruby PATH]`, `chi home doctor` — the chi home: the one Ruby (and its gem path) every chi launch boots, whoever launches it. `chi home` shows it (its Ruby, the newest chi in it, gem home and path, `mise`, when and by which chi it was set, and the chi you ran when that is another one; exit 1 with the problem when it can't boot chi), `set` records this chi's Ruby and gem path (or `--ruby PATH`'s own; it must have samagotchi), `doctor` checks it (for now: its Ruby is there and has samagotchi; exit 1 says what to do). This machine only (see [The chi home](configuration.md#the-chi-home))
 - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
 
 - `chi guardrails replay [--dry-run] [--threshold T] [--model M]` — seed System 1's record from the approvals this machine's sessions already answered: each ask is judged by the configured model and written to `guardrails/judgments.jsonl` with the answer the user gave, then a per-rule table prints (asks, allowed, denied, would-be auto-allows, false allows, asks with no judgment). A parent agent's answer is not the user's: only its deny is replayed, and only where the parent could have allowed. `--dry-run` judges without writing, `--threshold` overrides `guardrails.system_one.threshold` for the table, `--model` the configured model for this run. Exit 2 when `guardrails.system_one.mode` is off or no `host` is set; a usage error exits 2 (see [System 1](guardrails.md#system-1-experimental))
@@ -257,11 +258,22 @@ done
   [configuration](configuration.md#all-settings)). If the gem can't be updated
   in place, the notice gives the blocker and its command instead.
 
+- **The chi home.** With a [chi home](configuration.md#the-chi-home), a `chi
+  update` started on another Ruby first says `updating the chi home (<ruby>)`
+  and runs the home's chi update instead (the version check, `--to` and the
+  rows are the home's); chi web's **Update** runs the home's too. Without
+  one, the first `chi update` (not `--dry-run`, not under Bundler, and only
+  once its own checks passed) records one: of the desktop helper's Ruby and
+  the Ruby it runs on, the one with the newer chi, and says `chi home set to
+  <ruby> (chi home set to change)`.
 - **The gem.** It asks rubygems.org for the newest samagotchi (5 s timeout)
   and, when that's newer, runs `gem install samagotchi` with the gem command
-  of the Ruby chi runs on (the real one, not a mise/rbenv/asdf shim; a chi
-  installed under another Ruby is a separate install it doesn't touch). Then it
-  hands over to the new chi, which does the rest and prints the table. Old
+  of the chi home's Ruby, into the home's gems (`GEM_HOME`/`GEM_PATH` set to
+  the home's for that one command, and `mise`'s folder on its PATH when the
+  home names one, for mise's reshim plugin); without a home, the Ruby chi runs
+  on (the real one, not a mise/rbenv/asdf shim; a chi installed under another
+  Ruby is a separate install it doesn't touch). Then it hands over to the new
+  chi, which does the rest and prints the table. Old
   versions stay installed: running workers and an old `chi web` still load
   files from them, so a `gem cleanup` while they run breaks them (a
   `LoadError`, missing web assets); restart them first. A chi web, an
@@ -293,7 +305,9 @@ done
   sources changed; otherwise only its launch file is refreshed (a newer chi or
   other terminal settings). It keeps the Ruby, chi and PATH the helper runs (a
   PATH is filled in only when the file has none): `chi desktop install --force`
-  and `chi desktop upgrade` bake this shell's. A helper whose Ruby or chi is gone
+  and `chi desktop upgrade` bake this shell's (the chi home's boot, when there
+  is one). A refresh drops `RUBYLIB` from the launch file, and `GEM_HOME`/`GEM_PATH`
+  once it boots the chi home. A helper whose Ruby or chi is gone
   is reported as failed, naming `chi desktop install --force`. See
   [Desktop helper](desktop.md).
 - **Running processes** are reported, never stopped. A live worker keeps its
@@ -689,11 +703,14 @@ saved with the session and applies from the next turn's start; the reply says
 what it costs: `forget` on or off re-reads the whole prompt once, `stale` turned
 on stages the reads already superseded as one batch under the apply rule, and a
 layer turned off sends its stubs whole again (turning it back on brings them
-back). `/llm-context` alone answers mid-turn too; a change sent while a turn runs
+back). Once the session has a model reply, the two that break the cache now
+(`forget` on or off, a layer with applied stubs turned off) ask first and name
+the `--yes` line that applies them; `/llm-context reset --yes` works too.
+`/llm-context` alone answers mid-turn too; a change sent while a turn runs
 waits for the turn's end (see *Typing during a turn*). `/stats` shows
 the same values on its `llm context:` line. The web's info bar shows them as the
 `llm ctx` chip (`llm ctx stale,forget · session`), whose popover sets them
-through `/llm-context`. See "LLM context: a session's own strategy" in
+through `/llm-context … --yes` (its form says what a change costs). See "LLM context: a session's own strategy" in
 [configuration.md](configuration.md).
 
 `/working-set` lists the session's working set as the model has it (see [The
@@ -801,9 +818,9 @@ mid-turn too, and the lists, cards, top bar and tab show it in place of the firs
 message; a continue's next link keeps it. In the web, `✎` next to the session's
 title (its strip card, or the top bar) does it. See [Session titles](sessions.md#session-titles).
 
-A `/thinking`, `/reasoning-history` or `/toolkit` change that restarts the prompt cache
+A `/model`, `/llm-context`, `/thinking`, `/reasoning-history` or `/toolkit` change that restarts the prompt cache
 asks first: the reply says what it costs, changes nothing, and names the line
-that applies it (`/thinking low --yes`). `--yes` (or `-y`) applies it at once.
+that applies it (`/thinking low --yes`, `/model qwen --default --yes`). `--yes` (or `-y`) applies it at once.
 The terminal puts that line in the next input (Enter applies it); the web's
 reply has an Apply button. `chi send ID "/thinking low"`,
 `chi -p "/thinking low" --non-interactive` and lines piped into the REPL apply
@@ -1214,7 +1231,9 @@ pills there (a review turn refuses `/` lines).
 
 After the presets, both pages have a built-in **Verify**: the quote, then
 an ask to check the claim against the code and end on a line `Verdict:
-confirmed|refuted|unclear — <reason>`. A session whose worker predates Verify (started by an older chi) refuses it (409
+confirmed|refuted|unclear — <reason>`. Verify is offered only on text in a finished turn's final answer, the
+claim a verdict card can come from; elsewhere (an earlier reply, a step, a message, a line added mid-turn, a turn
+still running) the bar keeps its other actions. A session whose worker predates Verify (started by an older chi) refuses it (409
 `verify_unavailable`); a participant's page disables Verify and Verify fresh with a hint to restart the session. On your page a selection in a turn
 also offers **Copy link**: a link to that turn and quote for a participant's
 browser (the one their review link was opened in), which opens their page
@@ -1594,6 +1613,10 @@ In interactive assist mode, you can switch the request model without restarting:
 - `/model <name> --alias <alias>`: create alias for current effective model (alias value may be bare or `host:model`).
 - `/model`: show the effective model (and default when diverged: `runtime model: <effective> (default: <default>, profile=<name>, <source>)`, e.g. `profile=qwen36, server (chat_template)`). When the session's prompt carries model notes the line ends with `; notes: model_notes_deepseek (system, 612 chars)`; a switch's `runtime model set to …` names the new model's ([Memory](memory.md#model-notes)).
 - `/model clear` (or `default`/`none`/`off`): clear the session override, reverting to the configured default.
+- Once the session has a model reply, a switch to another model asks first from a web tab or a TUI (the new model
+  has no cache of the conversation): the reply names the line with `--yes` that applies it, flags and all
+  (`/model qwen --alias q --yes`); `--yes` (or `-y`) applies at once. A typo (an unknown host, a bad alias) is an
+  error before any question. See "Changes that restart the prompt cache" in [configuration.md](configuration.md).
 - `/guardrails`: the guardrail rules (by source), what failed to load, your stored approvals, and System 1's
   recent auto-allows; `/guardrails revoke N` removes approval N and `/guardrails wrong [N]` flags an auto-allow
   this session should have been asked about (see [Guardrails](guardrails.md)).

data/docs/configuration.md

@@ -833,12 +833,19 @@ models:
 
 ## Changes that restart the prompt cache
 
-`/thinking`, `/reasoning-history` and `/toolkit` ask before a change that makes the server read the conversation again:
-Gemma's thinking switch, a remote chat host's thinking fields ("Thinking"), a change to or from `all` once an earlier
-reply has thinking ("Reasoning history"), and any change to the declared tools, which start every request
-("Toolkits"). They ask only when what the next turn runs under really changes and the session has a model reply.
-
-- The reply says what it costs and changes nothing yet: `Nothing changed yet: send /thinking low --yes to apply.`
+`/model`, `/llm-context`, `/thinking`, `/reasoning-history` and `/toolkit` ask before a change that makes the server
+read the conversation again: a switch to another model (a plain name, `--default`, `--alias N`, `clear`; the new model
+has no cache of the conversation), `forget` turned on or off and a layer with applied stubs turned off ("LLM context:
+a session's own strategy"), Gemma's thinking switch, a remote chat host's thinking fields ("Thinking"), a change to or
+from `all` once an earlier reply has thinking ("Reasoning history"), and any change to the declared tools, which start
+every request ("Toolkits"). They ask only when what the next turn runs under really changes (`/model` naming the model
+it already runs, by its resolved ref, doesn't ask) and the session has a model reply. A `/model` name is checked
+first: an unknown host or a bad alias is an error at once, not a question.
+
+- The reply says what it costs and changes nothing yet. When known, it estimates the reread size: the whole
+  conversation for full-prefix changes, or from the first changed reply for reasoning history. On `api: anthropic`,
+  a full-prefix change also says preserved thinking in replies is dropped from then on.
+- `Nothing changed yet: send /thinking low --yes to apply.` names the line that applies it.
 - `--yes` (or `-y`, anywhere after the command) applies it at once.
 - The terminal (the REPL and an attached TUI) puts the `--yes` line in the next input: Enter applies it.
 - The web's reply bubble has an **Apply (restarts the cache)** button. The session bar's chips are already an explicit
@@ -846,8 +853,9 @@ reply has thinking ("Reasoning history"), and any change to the declared tools,
   the button is gone after a reload.
 - Only a person at a web tab or a chi TUI is asked. `chi send ID "/thinking low"`,
   `chi -p "/thinking low" --non-interactive`, lines piped into the REPL, a delegate, a plugin and a card's action
-  apply directly, since nobody would see the question; so do the start flags (`chi --thinking` on a resumed or
-  attached session sends `/thinking LEVEL --yes`). A plain `chi -p` opens the REPL, which asks.
+  apply directly, since nobody would see the question; so do the start flags (`chi --thinking`, `--model` and
+  `--llm-context` on a resumed or attached session send `/thinking LEVEL --yes`, `/model NAME --yes` and
+  `/llm-context … --yes`). A plain `chi -p` opens the REPL, which asks.
 
 ## Llama HTTP Timeouts
 
@@ -1344,6 +1352,51 @@ The helper reads these from its launch file: after editing them run
 (`$TMUX_TMPDIR/tmux-<uid>`, else `/tmp/tmux-<uid>`) are resolved then and
 frozen in it. See [Desktop helper](desktop.md#agents-in-kitty-and-tmux).
 
+## The chi home
+
+With several Rubies on one machine (mise, rbenv, chruby; a project that pins its own), whichever Ruby started chi
+used to decide which chi ran: a terminal in a project on Ruby 3.4 woke its session's worker on that Ruby's chi (an
+older one, or none), chi web's restart could fall off onto another install, and the macOS helper ran the Ruby of the
+shell it was installed from. The **chi home** is the one Ruby, and its gem path, every chi launch boots, whoever
+launches it. It is recorded in `~/.config/samagotchi/home.json` (`$XDG_CONFIG_HOME` is honoured):
+
+```json
+{
+  "ruby": "/Users/me/.local/share/mise/installs/ruby/4.0.7/bin/ruby",
+  "gem_home": "/Users/me/.local/share/mise/installs/ruby/4.0.7/lib/ruby/gems/4.0.0",
+  "gem_path": "/Users/me/.gem/ruby/4.0.0:/Users/me/.local/share/mise/installs/ruby/4.0.7/lib/ruby/gems/4.0.0",
+  "mise": "/opt/homebrew/bin/mise",
+  "set_at": "2026-10-29T21:00:00Z",
+  "set_by_version": "0.132.0"
+}
+```
+
+- **Setting it.** `chi home set` records the Ruby your `chi` runs on and its gem path (a chruby shell's
+  `GEM_HOME`/`GEM_PATH` are part of it: that is where its chi lives); `chi home set --ruby PATH` records another
+  Ruby with its own gem dirs. Either needs samagotchi installed there (`gem install samagotchi` with that Ruby
+  first). Without a home.json, the first `chi bootstrap` or `chi update` records one, once (from an installed chi,
+  never under `bundle exec`): of the desktop helper's Ruby (when its newest chi is at least the one running) and the
+  Ruby chi runs on, the one with the newer chi. Nothing else ever overwrites it.
+  `chi home` shows it; `chi home doctor` checks it (see [CLI](cli.md#commands)).
+- **What follows it.** Every session worker (whoever starts or wakes it: a terminal, `chi send`, chi web, a
+  delegating session, a restart), chi web's restart and its **Update** button, `chi update` (from another Ruby it
+  runs the home's `chi update`, and installs into the home's gems with the home's `gem`), `chi bootstrap`'s
+  commonmarker install, chi web's "installed; restart" notice and the macOS helper after its next `chi desktop
+  install` or `upgrade`. The boot sets the home's gem path inside Ruby (`Gem.paths`), never in an environment
+  variable: the commands a session runs (`execute`, tasks, `!cmd`, MCP servers) keep the GEM_HOME/GEM_PATH of whoever
+  started the worker, or none. How: [How chi launches itself](architecture.md#how-chi-launches-itself).
+- **No home, or one that can't boot chi** (its Ruby gone after a Ruby upgrade, samagotchi uninstalled there, a
+  home.json that isn't JSON): each launch uses the Ruby that starts it, as without a home, and the log says why once
+  per process (`home_unusable`, `home_invalid`). After a Ruby upgrade: `gem install samagotchi` with the new Ruby,
+  then `chi home set` from it. A source checkout (`bin/chi`, `bundle exec`) never uses the home: a worktree's
+  `bin/chi` starts its own code.
+- **A home with an older chi than the one launching**: workers still boot the home (the log says so once,
+  `home_older_than_spawner`), but chi web's restart runs the newest chi it knows outside the home instead
+  (`restart_home_older`): its flags may be ones the older chi doesn't know.
+- **A home that still fails at boot** (a broken install): the worker writes one `boot_failed` line to the debug log
+  (`log.file`) and exits, rather than leave the spawner waiting.
+- Each machine has its own home (a remote's is that machine's).
+
 ## Project specific description
 
 If an AGENTS.md file is present in the project root, samagotchi injects its
@@ -1638,6 +1691,12 @@ its own). The first target is a long session such as a day-long coordinator, whe
   and their results stay in the history.
 - **Switching a layer off:** its stubs go out whole again from the next request (a cache break from the first). The
   session keeps the originals and the edits, so turning the layer back on brings the same stubs back.
+- **Asks first:** once the session has a model reply, `/llm-context` from a web tab or a TUI asks before the two that
+  break the cache now: `forget` on or off, and a layer with applied stubs turned off (the reply names the
+  `/llm-context … --yes` line; "Changes that restart the prompt cache"). Turning `stale` on, the apply rule and the
+  budget don't ask: they only decide when a batch goes in, and each batch's break comes as designed (`next_request`
+  with staged edits pending moves a break the old rule makes by the end of the next turn anyway). The chip's Set and
+  `--llm-context` on an attached or resumed session send `--yes`.
 - **Where to see it:** `/llm-context` (each value and where it came from: `the session`, `models: <key>`,
   `hosts entry '<name>'`, `llm_context.*`), `/stats` (`llm context:`), the turn log (an `llm_context` record per
   turn that runs a layer or whose session set its strategy) and the web's chip. A woken worker's status line counts

data/docs/desktop.md

@@ -257,7 +257,9 @@ don't break it. From a checkout it runs **that** checkout's `bin/chi`; installin
 warning, because the helper stops working once that worktree is removed. After switching between a checkout and a
 gem install, run `chi desktop upgrade` from the one you now use.
 
-The helper runs the Ruby and chi of **the shell you installed from**, and only `chi desktop install --force` and
+With a [chi home](configuration.md#the-chi-home), `chi desktop install` and `upgrade` make the helper boot the home
+(its Ruby, the newest chi in its gems) whatever shell you run them from. Without one, the helper runs the Ruby and
+chi of **the shell you installed from**, and only `chi desktop install --force` and
 `chi desktop upgrade` change that: they pick the Ruby and chi of the shell you run them in. `chi update` never
 repoints it, so running it from a project with another Ruby (or an older chi) leaves the helper where it was. If
 the Ruby or chi the helper runs is gone (a Ruby upgrade, a removed worktree), `chi update` fails the helper's row
@@ -286,12 +288,19 @@ says the same.
 Apps started by macOS get a bare environment: no shell rc files, so no rbenv/chruby/mise/asdf and none of your
 exports. So `install` writes `~/Library/Application Support/Chi Helper/launch.json` with:
 
-- the absolute path of the Ruby running chi and of chi itself (the gem's wrapper, or a checkout's `bin/chi`), as of
-  the last `chi desktop install` or `upgrade` (`chi update` keeps them);
+- what to run, as of the last `chi desktop install` or `upgrade` (`chi update` keeps it): with a
+  [chi home](configuration.md#the-chi-home), the home's boot, `["<home ruby>", "-e", "Gem.paths = {…}; gem
+  'samagotchi', '>= 0.a'; load Gem.bin_path('samagotchi', 'chi')", "--"]` (the helper appends its own arguments
+  after `--`); without one, the absolute path of the Ruby running chi and of chi itself (the gem's wrapper, or a
+  checkout's `bin/chi`). The helper and `chi update` check only the absolute paths in it;
 - `LANG=en_US.UTF-8`;
-- only these variables, and only when they are set: `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `GEM_HOME`, `GEM_PATH`,
-  `RUBYLIB` (a relative `XDG_*` dir made absolute from the install's current folder: the helper starts in `/`).
-  No tokens and no `SAMAGOTCHI_*` settings go in;
+- only these variables, and only when they are set: `XDG_CONFIG_HOME`, `XDG_STATE_HOME` (a relative one made
+  absolute from the install's current folder: the helper starts in `/`). No tokens and no `SAMAGOTCHI_*` settings
+  go in, and never `RUBYLIB`. `GEM_HOME` and `GEM_PATH` go in only without a chi home (a `[ruby, chi]` launch,
+  whose chi may be found only through them, as under chruby): the home's boot sets its gem path itself, and they
+  would reach every command the helper's sessions run (a project's `bundle exec` on the wrong gems). A launch file
+  from an older chi loses `RUBYLIB` at the next `chi update`, and `GEM_HOME`/`GEM_PATH` once it boots the chi home
+  (`chi desktop upgrade` moves it to the home);
 - `PATH`: the shell's PATH when the file is written, with only absolute folders, in order, each once. The helper's
   chi, the sessions it starts and their `execute` commands can find the tools your terminal finds (mise, Homebrew,
   `codex`, `node`);

data/docs/guardrails.md

@@ -4,7 +4,7 @@ Every tool call the model makes passes one check before it runs, in both
 loops (native and chat hosts). The verdict is **allow**, **ask** or
 **deny**; the strictest vote wins, and a deny can't be undone by a later
 voter. Of two asks the first one names the rule, except a rule only the
-user may allow (`chi-config`, `chi-hooks`, `shell-touches-chi`,
+user may allow (`chi-config`, `chi-home`, `chi-hooks`, `shell-touches-chi`,
 `chi-context-cmd`, `chi-broadcast`): it takes over, and only the scopes both asks offer
 are offered.
 
@@ -215,7 +215,7 @@ rules off: `guardrails: {disable: [write-outside-repo, git-outside-repo]}`.
 
 Whatever the setting, a parent can't allow a call on chi's own files: a
 `write`, `edit` or `execute` on the config dir (config.yml, installed bundles'
-rules), the hooks dir or the approval store, by its rule (`chi-config`,
+rules), the hooks dir or the approval store, by its rule (`chi-config`, `chi-home`,
 `chi-hooks`, `shell-touches-chi`), its paths or its command. "Allow once" on a
 config.yml rewrite would allow everything from then on, so those questions are
 the user's alone (`user_only`): `chi answer` and the worker refuse the allow
@@ -280,7 +280,7 @@ Built in, for `write`, `edit` and `memory_write` (symlinks resolved; see
 - deny: the approval store's dir, installed bundles (`memories/.bundles/`),
   and [attached context](context.md) sources (`<state dir>/context/`: a
   source's command runs later, outside the gate; `chi context` changes them);
-- ask (once or for the session): `config.yml` and the plain hooks dir.
+- ask (once or for the session): `config.yml`, `home.json` (the [chi home](configuration.md#the-chi-home): the Ruby every chi launch boots) and the plain hooks dir.
 
 `execute` can still reach them; the guardrails bundle asks about shell
 commands that name them.

data/docs/internals/anthropic.md

@@ -133,8 +133,9 @@ append-only within a process, so what changes the prefix is:
 1. **A system-prompt rebuild** (`SystemPrompt#build` is cached per process and key; `SystemPrompt#reset!` drops it):
    a new process (`--resume`, a respawn after `session.idle_exit_minutes`, a crash) after a memory index line, an
    AGENTS.md, an appended file, a model note or a bundle memory changed; `/model` (the tail's `Model:` line, its
-   overlays and notes); `/thinking` (another key); a toolkit or profile change; a plugin's `tools_changed!`; the
-   session's first participant joining or last leaving (the tail's participants line, participants.md).
+   overlays and notes); `/thinking` (another key); a toolkit or profile change; a plugin's `tools_changed!` or
+   `prompt_changed!` (its prompt section's text, plugins.md); the session's first participant joining or last
+   leaving (the tail's participants line, participants.md).
 2. **A tool set change**: the same triggers, plus MCP lines that differ on a respawn.
 3. **History edits by design**: the `llm_context` `stale`/`forget` stubs, and the image cut moving a batch.
 

data/docs/internals/engine.md

@@ -832,10 +832,10 @@ answer is stripped from prefill + response, so the reasoning never lands in it).
    persistent.
 5. **A stable system prompt for the cache.** `SystemPrompt#build` caches the prompt per Engine, keyed by
    `[chat, thinking, layers]` (chat/native, the thinking level, the turn's LLM context layers), and is reset
-   only on a model switch, a tools change, a profile change or a toolkit change (`Engine#apply_toolkit!`). The
-   stable part (base prompt, the toolkit's not-loaded line, rg guidance, identity, model notes, preloaded memories,
-   AGENTS.md, appended files, the toolkit's kit prompt, memory indexes) comes before the volatile tail (model,
-   working directory, session).
+   only on a model switch, a tools change, a plugin's `prompt_changed!` (`Engine#prompt_changed!`), a profile
+   change or a toolkit change (`Engine#apply_toolkit!`). The stable part (base prompt, the toolkit's not-loaded line,
+   rg guidance, identity, model notes, preloaded memories, AGENTS.md, appended files, the toolkit's kit prompt, the
+   plugins' prompt sections, memory indexes) comes before the volatile tail (model, working directory, session).
    prompt-caching.md covers this in detail.
 
 ## Key files

data/docs/internals/participants.md

@@ -375,7 +375,10 @@ fields: a field added to an event later reaches nobody until it is named there.
   so the owner's `!` line and its output, a delegate's report (a wake turn's too), and the notes chi adds (a declined
   Continue) never show. A turn no person sent (its record's `automatic`, `SessionMetrics`: a task's or a plugin's,
   read from analytics.json and the live worker's records; the running turn's by its start; a delegate child's first
-  turn, its parent's task) shows as an automatic turn without its prompt, as the stream does. A raw loop's saved
+  turn, its parent's task) shows as an automatic turn without its prompt, as the stream does; so does a wake turn's
+  start (`.wake_start`: the delegate report or the context note a wake turn opens with is dropped, its `turn_id` and
+  `at` kept), so its answer is never read as one more reply of the turn before (Verify, verdict cards and claim
+  links group by `[data-turn-id]`). A raw loop's saved
   reply is cut before the display reads it (`.visible_raw`): what came before a bare `</think>` and everything from
   an unclosed thought or tool call on, which the display would only untag. Each
   prompt carries its author and an image count; replies their text and their step's tool rows. Notes, steers and
@@ -428,6 +431,13 @@ fields: a field added to an event later reaches nobody until it is named there.
   After the presets comes the built-in **Verify** (`verify_preset.js`, on the owner's page too): the quote, then
   "Verify this claim against the code. If this session's context doesn't settle it, say so. End with a line
   `Verdict: confirmed|refuted|unclear — <one-line reason>`." It fills the box like any preset and never sends.
+  It is offered only where the Engine will take the claim (`verify_target.js`, the bar's `offeredPreset`): a
+  selection in the final answer of an ended turn, the last answer bubble (the owner's `.bubble.output` that isn't a
+  delegate report's reply; a participant's last `.p-msg.reply > .p-bubble`) between the turn's opening
+  (`[data-turn-id]`) and the next one (or, on the owner's page, a context note: a wake turn opens with one; a
+  participant's page gets a wake turn's opening as an automatic turn).
+  Anywhere else (an earlier reply, a step, a prompt, a line merged mid-turn, the Plan, the running turn) the button
+  is hidden and the bar keeps its other actions.
 - **Deep links to a claim** (`claim_link.js`). The owner selects text in a turn's answer, step or own message and
   Annotate's **Copy link** copies `<base>/#s=<id>&t=<turn8>&q=<quote>&p=<prefix>`: `base` the participants list's
   `link_base` (`ParticipantsAdmin#participant_base`: `web.public_url`'s origin, else the LAN address, else the Host),
@@ -454,13 +464,18 @@ fields: a field added to an event later reaches nobody until it is named there.
   with the submitted turn, without changing its prompt text. A Verify turn that fails fast and is rolled back hands
   the claim back with its prompt (`prompt_restored`'s `verify`), so the owner's resend from the composer is a Verify
   turn again. Before the Engine stamps the anchor or records a verdict, it checks that the source turn exists and
-  its assistant reply contains the quote. Matching is case-sensitive, collapses whitespace, and strips common
+  its final assistant reply (`AnswerTail`: the turn's last assistant message with text) contains the quote. Matching is case-sensitive, collapses whitespace, and strips common
   Markdown presentation (links, headings, list/blockquote prefixes, emphasis and code delimiters) from both sides;
-  this matches the rendered text the page selects without treating different casing as the same claim. A fresh child
+  this matches the rendered text the page selects without treating different casing as the same claim. The quote may
+  also be in the answer as the pages show it (`Engine#verify_quote_in?`, `ParticipantView::Redact.text`: the session's
+  folder relative, home `~`, secret shapes `[redacted]`): a participant's page has only that text, and the owner's
+  page quotes it the same way (`claimOpts()`, `normalizeClaim`; `spec/fixtures/redact_cases.json` keeps the two
+  sides alike), so a claim naming a path is taken on both. A fresh child
   checks the same anchor against its parent's history. A completed Verify reply whose final non-empty line has
   a valid `Verdict: confirmed|refuted|unclear — <reason>` appends a verdict to the session. Both pages place its card
-  after the source turn, name its author, show the reason and quote, and link to the checking turn; a live completion
-  adds the card without a reload. The participant view receives only the card fields through its allowlist, with the
+  in the source turn, right after the bubble that holds the quote (the answer's, matched as a claim link reads the
+  page; a quote not found yet goes at the turn's end), name its author, show the reason and quote, and link to the
+  checking turn; a live completion adds the card without a reload. The participant view receives only the card fields through its allowlist, with the
   quote and reason redacted by the view's normal rules, never the full reply.
 - **Verify fresh** (`VerifyFresh`, `verdict_fresh.js`). An `unclear` card has a **Verify fresh** button (the owner's
   page always; a participant's while `can_comment`, i.e. while their grant could run a turn now; never in the owner's
@@ -520,7 +535,9 @@ fields: a field added to an event later reaches nobody until it is named there.
     `:verdict_recorded`; chi web shows the ones still waiting (`VerifyFresh.verdicts_of`: the summary, the review
     data). The card shows "Verifying fresh…" while the child runs (the summary's `verify_fresh` `{of, child_id}`,
     the review data's `fresh_running`, ids only) and the fresh verdict as a `fresh: ✅ confirmed — …` line on the same
-    card. The participant view passes `fresh` and `of`, never the child's id (a participant can't open it). No push
+    card. The original stays unclear, so the button stays, as **Verify fresh again**: each press is another paid
+    child (a participant's against their cap). The participant view passes `fresh` and `of`, never the child's id (a
+    participant can't open it). No push
     for a fresh verdict yet (`Attention` pushes a verdict at a turn's end).
 - **The comment box** is the owner's composer (`composer_mount.js`, styled by the shared `composer.css`), mounted by
   `participant.js` with a subset on. It has: the height that grows with the text, the grip (drag to resize,