samagotchi 0.130.0 → 0.131.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5830c4028607020136e2f0493d0d365f5d10889fa8ff2a493b979de7b7e164b9
-  data.tar.gz: 28f0fda8ba4b824af19381b12274262c0858f879565b58ab4a6a12e18b82f64e
+  metadata.gz: 37f2a54062786637083ade10186ebb751a1cfd7a7996540defa03da018b29533
+  data.tar.gz: 6836e60f2a87358698adaf000592ac68af5ce8fe8f3c26799825fa26641d3f1a
 SHA512:
-  metadata.gz: 38f04438ffc54f5569abbbfb5fdfdd7470ca805926f3593969924a5a248b29ff266f2eec6972aff25d29395982b255b6518989f174a1579b227a711ae1aeec68
-  data.tar.gz: 3dc45f2617ca67e11f8cf563c83ea1c979142d798d900b000b5f1ae0c12ffb559b692cdec8f8f614da09eeb8cd176a1e7e5af59d47958ddffc838b3faa8f8d9d
+  metadata.gz: b908ad2c276d4dabb1c8bd64ad8435a2f9ab5408663243f8cd0f24e25ca2e4647cb356228a7a37027c1c5f2895936c4df8424af5203d8c121b5403577e2a2456
+  data.tar.gz: a3c96161fc7cb55e200367417e1dac93442845e0a868ad02d58ecca15a504af6824c419e8188252c9100daf405892be203e75fd6d7baaca1406c20186a4ff6f4

data/CHANGELOG.md

@@ -7,6 +7,65 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.131.0] - 2026-10-29
+
+### Changed
+
+- 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
+
+- Sessions started from the desktop helper find the tools your terminal finds (mise, Homebrew, `codex`):
+  `chi desktop install` writes your shell's PATH into the helper's launch file, `chi update` adds it to a
+  launch file that has none (it never changes a baked one; `chi desktop install --force` does), and
+  `chi desktop status` shows it. Run `chi update` once from your terminal, then restart the sessions the
+  panel started.
+- `chi update` no longer repoints the desktop helper at the Ruby or chi it runs from, nor refreshes the launch file
+  from an older chi: only `chi desktop install --force` and `chi desktop upgrade` pick the current shell's Ruby,
+  chi and PATH. When the helper's Ruby or chi is gone, `chi update` says so and names that command.
+- An older chi that saves a session a newer chi wrote (waking it from a project whose Ruby has an older chi, say)
+  keeps the session's fields it doesn't know instead of dropping them, and the session file names the chi that saved
+  it last (`written_by`; a worker woken on a file a newer chi saved logs `newer_writer`). This works from this release
+  on: chi 0.130.0 and older still drop them, so update the chi in every Ruby you run it from.
+- `execute` (and a user's `!cmd`) no longer hands a project's commands chi's own Bundler setup: run under
+  `bundle exec`, chi passed on `RUBYOPT=-rbundler/setup` and its `BUNDLE_GEMFILE`, so `ruby -e` or `bundle exec`
+  in another project loaded chi's Gemfile. It now scrubs them the way `task_create` always has.
+
+### Security
+
+- On the LAN (`web.host: lan`), the cookie chi web sets for this machine's 127.0.0.1 no longer holds the access
+  token: a server on another local port gets every 127.0.0.1 cookie, so a dev server that logs headers caught the
+  token. It now holds a value that works only as that cookie on this machine and ends with `chi web --new-token`.
+  An open 127.0.0.1 tab lands on the 401 page once: open the `Local:` link. If you ran a participant's pair turns
+  with dev servers on 0.130.0, run `chi web --new-token`. The LAN address's cookie (your phone's) still holds the
+  token.
+
+Update with `chi update`, then restart `chi web` and the session workers (`chi sessions restart`).
+
 ## [0.130.0] - 2026-10-29
 
 ### Changed
@@ -4933,7 +4992,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.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.131.0...HEAD
+[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
 [0.128.0]: https://github.com/dm1try/samagotchi/compare/v0.127.0...v0.128.0

data/docs/architecture.md

@@ -153,7 +153,7 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 | UI | `Samagotchi::TerminalUI` | Interactive REPL (Reline), rendering (ANSI, spinner, status line), REPL commands. Delegates all core work to an `Engine`. |
 | Model loops and adapters | `KernelLoop`, `LLM::ChatLoop`, `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | The model↔tool loops and the HTTP adapters they talk through (see "Model loops and adapters"). |
 | Bridge (SSE/HTTP) | `Samagotchi::Bridge`, `SessionManager` | The **single live client transport**: an SSE read stream + HTTP POST turn/cancel/answer surface that attaches to a worker's existing `Engine` via `Engine#subscribe`. Every session worker starts it (bound `127.0.0.1`, localhost-only), and it answers only a request that names its secret (`X-Chi-Bridge`, from the worker's 0600 `bridge.json`). |
-| Web (Rack) | `Samagotchi::Web::App`, `SessionManager` | Single-port `127.0.0.1:4567` control plane via `rack`+`webrick` (serve `index.html` + `/api/*`). With `web.host: lan` (or one of this machine's IPv4 addresses) the server also listens on that address, where every request needs the access token, this machine's on loopback too (`App#token_gate`: the `chi_token` cookie or `Authorization: Bearer`; chi web prints a `Local:` link with a one-time code; [CLI](cli.md#chi-web-on-your-phone)). Experimental: behind an auth proxy (`web.public_url`, `Web::ProxyGate`) every request needs the token, this machine's too, and one that came through the proxy also the configured identity header for the owner ([configuration.md](configuration.md#behind-an-auth-proxy)). A request goes through, in order: the Host check (`local_host_header?`: loopback names, the LAN address, the public host), the cross-site check (`cross_site?`: Origin this server's or the public origin, no `Sec-Fetch-Site` cross-site/same-site on a POST or `/api`), the frame check (`framed?`: a frame/embed/object load from another origin, 403 `framed`; every HTML answer carries `X-Frame-Options: DENY` and `frame-ancestors 'none'`), the token gate (`token_gate` → `principal_for`, `proxied_principal` for a proxied request; the `?token=` / `POST /api/token` trade sets the cookie, `__Host-chi_token` through the proxy; with `web.public_url` a direct request takes Bearer only, and with it or LAN mode chi's token-less `/api/info` probe gets `probe_info`), then the route's permission (`Principal#permits?`). It talks to each worker's Bridge (`App#relay`, `bridge_get`; `/stream` proxies it) and reads the session files; no `Engine` of its own. Markdown (`web.markdown`) is rendered here only (`Web::MarkdownRenderer`): the answers it serves, card bodies, and `POST /api/render` for a text the page already shows. `App` keeps the gate, `ROUTES` and the helpers the handlers share; its handlers live in mixins it includes, each a `Web::` module with private methods: `SessionAccessRoutes` (`web/session_access_routes.rb`), `ParticipantAccess` (`web/participant_access.rb`), `ParticipantsAdmin` (`web/participants_admin.rb`), `ParticipantReview` (`web/participant_review.rb`), `MessageDisplay` (`web/message_display.rb`), `SessionShow` (`web/session_show.rb`), `SessionCreate` (`web/session_create.rb`), `SessionControl` (`web/session_control.rb`), `PushRoutes` (`web/push_routes.rb`) and `ProxyGate` (`web/proxy_gate.rb`). Exact paths in `GATE_FREE_PATHS` are served before the token gate (the fragment trade's script, and the Home Screen app's manifest, service worker and icons). `bin/chi web` entrypoint. |
+| Web (Rack) | `Samagotchi::Web::App`, `SessionManager` | Single-port `127.0.0.1:4567` control plane via `rack`+`webrick` (serve `index.html` + `/api/*`). With `web.host: lan` (or one of this machine's IPv4 addresses) the server also listens on that address, where every request needs the access token, this machine's on loopback too (`App#token_gate`: the `chi_token` cookie, on loopback a value derived from the token (`Token.loopback_cookie`), or `Authorization: Bearer`; chi web prints a `Local:` link with a one-time code; [CLI](cli.md#chi-web-on-your-phone)). Experimental: behind an auth proxy (`web.public_url`, `Web::ProxyGate`) every request needs the token, this machine's too, and one that came through the proxy also the configured identity header for the owner ([configuration.md](configuration.md#behind-an-auth-proxy)). A request goes through, in order: the Host check (`local_host_header?`: loopback names, the LAN address, the public host), the cross-site check (`cross_site?`: Origin this server's or the public origin, no `Sec-Fetch-Site` cross-site/same-site on a POST or `/api`), the frame check (`framed?`: a frame/embed/object load from another origin, 403 `framed`; every HTML answer carries `X-Frame-Options: DENY` and `frame-ancestors 'none'`), the token gate (`token_gate` → `principal_for`, `proxied_principal` for a proxied request; the `?token=` / `POST /api/token` trade sets the cookie, `__Host-chi_token` through the proxy; with `web.public_url` a direct request takes Bearer only, and with it or LAN mode chi's token-less `/api/info` probe gets `probe_info`), then the route's permission (`Principal#permits?`). It talks to each worker's Bridge (`App#relay`, `bridge_get`; `/stream` proxies it) and reads the session files; no `Engine` of its own. Markdown (`web.markdown`) is rendered here only (`Web::MarkdownRenderer`): the answers it serves, card bodies, and `POST /api/render` for a text the page already shows. `App` keeps the gate, `ROUTES` and the helpers the handlers share; its handlers live in mixins it includes, each a `Web::` module with private methods: `SessionAccessRoutes` (`web/session_access_routes.rb`), `ParticipantAccess` (`web/participant_access.rb`), `ParticipantsAdmin` (`web/participants_admin.rb`), `ParticipantReview` (`web/participant_review.rb`), `MessageDisplay` (`web/message_display.rb`), `SessionShow` (`web/session_show.rb`), `SessionCreate` (`web/session_create.rb`), `SessionControl` (`web/session_control.rb`), `PushRoutes` (`web/push_routes.rb`) and `ProxyGate` (`web/proxy_gate.rb`). Exact paths in `GATE_FREE_PATHS` are served before the token gate (the fragment trade's script, and the Home Screen app's manifest, service worker and icons). `bin/chi web` entrypoint. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File-based `~/.local/state/samagotchi/sessions/<uuid>.json` + sidecar `input/`/`output/`; retention (14d/500) + ordering (`updated_at desc`). |
 
 - `bin/chi` in REPL mode (see `LaunchMode` above) builds `TerminalUI`. `TerminalUI#run` is the single

data/docs/cli.md

@@ -290,8 +290,12 @@ done
   one that failed before; one you uninstalled stays out. See [Bundle
   profiles](memory.md#bundle-profiles-core-and-dev).
 - **The desktop helper** (macOS) is rebuilt and restarted only when its Swift
-  sources changed (or the Ruby it runs moved); otherwise only its launch file
-  is refreshed. See [Desktop helper](desktop.md).
+  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
+  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
   chi until it is restarted: `chi sessions restart ID` (one from before
   restarts: `chi sessions stop ID`, and the next prompt starts it on the new
@@ -1210,7 +1214,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
@@ -1271,7 +1277,12 @@ access token", paste the token there (the part of the link after
   paste the token) and the API answers 401. On this Mac open the `Local:`
   link (`chi web --open` opens it): its one-time code (10 minutes, once) sets
   the cookie for 127.0.0.1 without the token in the address; the LAN link
-  works here too. chi's own probe (`GET /api/info` with no token or cookie)
+  works here too. The cookie for 127.0.0.1 holds a value derived from the
+  token, not the token: the browser sends it to a server on any other local
+  port too (a dev server that logs headers), and that server can't use it
+  from the network (unless something forwards it to this machine's
+  loopback), as Bearer, or as the token; `chi web --new-token` ends it. The LAN address's cookie (your phone's, or this Mac's when it opens
+  the LAN link) is the token itself. chi's own probe (`GET /api/info` with no token or cookie)
   gets a few fields (version, pid, features, the LAN address, the start
   folder), nothing of the sessions.
 - The token lives in `$XDG_STATE_HOME/samagotchi/web-token` (0600).

data/docs/configuration.md

@@ -838,7 +838,10 @@ Gemma's thinking switch, a remote chat host's thinking fields ("Thinking"), a ch
 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.`
+- 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

data/docs/desktop.md

@@ -194,7 +194,8 @@ grant:
 
    `tmux.agents` picks the programs listed (kitty.agents' default; `"*"` lists every pane), `tmux.binary` the tmux
    to run (default: the `tmux` on your shell's PATH when the launch file is written, e.g. `/opt/homebrew/bin/tmux`;
-   the helper itself has no PATH). See [Configuration](configuration.md#desktop-helper-agents-in-kitty-and-tmux).
+   the helper itself keeps macOS's default PATH, and tmux is resolved when the file is written). See
+   [Configuration](configuration.md#desktop-helper-agents-in-kitty-and-tmux).
 2. Run `chi update` (or `chi desktop upgrade`), and again after every edit of `tmux:`. With no tmux found they say
    "tmux.enabled but no tmux found on PATH: set tmux.binary", and the panel "tmux not found…".
 
@@ -256,9 +257,16 @@ 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
+`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
+with "chi not found at …: run chi desktop install --force from the shell whose chi it should run".
+
 `chi update` keeps it current: it rebuilds and restarts the helper only when its Swift sources changed since the
-build (`launch.json` records their digest) or the Ruby it runs moved. A new chi that left the sources alone only
-rewrites `launch.json`, which the app reads at each send, so the app keeps its older version number and that's fine.
+build (`launch.json` records their digest), keeping the Ruby, chi and PATH it runs. A newer chi that left the
+sources alone only rewrites `launch.json` (its version and settings), which the app reads at each send, so the app
+keeps its older version number and that's fine. An older chi than the one that wrote the file changes nothing.
 
 ## Commands
 
@@ -267,7 +275,7 @@ rewrites `launch.json`, which the app reads at each send, so the app keeps its o
 | `chi desktop install [--force] [--login]` | builds, installs and starts it; `--force` replaces an existing copy |
 | `chi desktop upgrade` | rebuilds it for this chi and restarts it, keeping the login setting (always; `chi update` does it only when needed) |
 | `chi desktop uninstall` | quits it and removes the app, its login item, launch file and settings |
-| `chi desktop status` | version against chi's, how it runs chi, state dirs, Service, hotkey, process, login item, host keys |
+| `chi desktop status` | version against chi's, how it runs chi, state dirs, PATH, Service, hotkey, process, login item, host keys |
 
 `chi self` has a `desktop` line: `0.1.x (matches)`, `0.1.w (up to date for chi 0.1.x)` (an older build whose sources
 haven't changed), `0.1.w (chi is 0.1.x: chi update)` (a rebuild is due) or `not installed`. `chi desktop status`
@@ -278,17 +286,24 @@ 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`);
+- 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);
 - `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;
+- `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`);
 - the settings the panel needs from config.yml, as chi read them then: the `kitty:` section (when
   `kitty.listen_on` is set), the `tmux:` section (when `tmux.enabled`: the tmux binary and the socket dir resolved
   then, and the agents) and `broadcast_timeout` (`broadcast.triage_deadline` + 10 s).
 
-The file freezes the install shell's values. If you install with a temporary `XDG_STATE_HOME`, the helper keeps
-using it. `status` prints the baked dirs.
+The file freezes the install shell's values, including PATH. If you install with a temporary `XDG_STATE_HOME`, the
+helper keeps using it. `chi update` fills in a PATH only when the file has none (as in a launch file written before
+this change); it never changes an existing baked PATH. To change it (for example, after a mise upgrade changes the
+versioned folders on PATH), run `chi desktop install --force` or `chi desktop upgrade` from the shell whose PATH
+you want. `status` prints the baked state dirs and PATH.
 
 **Host API keys** don't go in the launch file either: with the variable a host's `api_key_env:` names unset, chi
 reads the key from the login Keychain (service `chi`, account the variable's name; see
@@ -331,8 +346,12 @@ broadcast` says the note may be partly delivered.
 
 ## Troubleshooting
 
-- **"chi not found at …, run `chi desktop upgrade`"**: the Ruby or checkout in `launch.json` moved (a Ruby upgrade,
-  a removed worktree). Run `chi desktop upgrade` (or `chi update`) from the chi you use now.
+- **"chi not found at …"**: the Ruby or checkout in `launch.json` moved (a Ruby upgrade, a removed worktree).
+  `chi update` won't repoint it: run `chi desktop install --force` (or `chi desktop upgrade`) from the shell whose
+  chi the helper should run.
+- **A session started from the panel can't find a tool (`codex`, `node`):** `chi desktop status` shows the PATH it
+  gets. With none, run `chi update`; to change it, run `chi desktop install --force` from your terminal. Then
+  restart that session (`chi sessions restart ID`).
 - **No "Send to chi" in the Services menu:** check `chi desktop status` (service). Try
   `/System/Library/CoreServices/pbs -update`, start the app again, or log out and back in. It must be ticked in
   System Settings → Keyboard → Keyboard Shortcuts… → Services → Text.

data/docs/internals/background-tasks.md

@@ -42,6 +42,7 @@ Behavior:
   again or stop it (`TaskWait::MESSAGE_WAITING_NOTE`), and `waited: Ns`; the task keeps running and stays watched
   (below). A task that finished meanwhile gives its finished result, as after a Stop. A `chi -p` turn has no probe.
 - `task_create` accepts `env` as a JSON object string for deterministic overrides such as `PATH`; use an absolute interpreter path when that is simpler. Ruby/Bundler isolation variables remain protected.
+- `execute` and `task_create` both spawn with chi's own Ruby/Bundler setup scrubbed (`TaskRuntime.sanitized_spawn_env`): `RUBYOPT` loses its `-r…bundler/setup` flags (others stay) and `RUBYLIB`, `BUNDLE_GEMFILE`, `BUNDLE_BIN_PATH`, `BUNDLER_VERSION` are unset, so a project's `ruby -e` or `bundle exec` uses its own Gemfile when chi runs under `bundle exec`. `task_create` refuses those keys in the model's `env`; `execute`'s `env` comes from chi's callers (`Builtins`, `!cmd`), not the model, and is set over the scrub. An `execute` handed over at its limit keeps the process it spawned, so the task runs with the same env.
 - `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent), `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown) `SAMAGOTCHI_SESSION_THINKING` (the session's own thinking level; unset when it has none) and `SAMAGOTCHI_SESSION_REASONING_HISTORY` (its own reasoning_history level, the same way). `chi self` reads the last three for its model, thinking level and reasoning history. The four are `ChildEnv::SESSION_MARKERS` (`TaskRuntime::MARKER_ENV_KEYS`), which a spawned worker unsets (`ChildEnv.unset`, merged into its spawn env). A session's worker never inherits them from whoever started it (a `chi send` run by another session's `execute`): its other commands (a user's `!cmd`, an MCP server, a context command) have none.
 - They also pass on a set `XDG_STATE_HOME` / `XDG_CONFIG_HOME` made absolute (`Builtins.xdg_absolute`, via `Paths`), so a chi the command runs in another `cwd` (`chi send`) reads this chi's state and config. These aren't reserved: an XDG dir the model sets in `task_create`'s `env` stays its own.
 

data/docs/internals/participants.md

@@ -122,7 +122,13 @@ participant** and **one role**, until it expires or is revoked.
    the detail (only the requester's own identity). Unproxied, every request needs a token too (no "loopback is the
    owner"): rule 3 doesn't apply.
 1. The owner's token (Bearer, then the cookie; `?token=` on the page's trade): the **owner**. Checked first, so the
-   owner's requests never touch the grants store (measured: no change to an owner route's time).
+   owner's requests never touch the grants store (measured: no change to an owner route's time). On a LAN chi web
+   (no `web.public_url`) a loopback peer's owner cookie is `Token.loopback_cookie` instead (`chl_`, an HMAC of a
+   label keyed by the token, `App#loopback_cookie_peer?` / `#loopback_cookie`): it stands for the token only as that
+   cookie from a loopback peer, never as Bearer, a trade or from the LAN address, and `chi web --new-token` ends it.
+   The token itself as a loopback cookie (set by 0.130.0) is refused, and its 401 clears it (`#refused_token`). The
+   token as Bearer on loopback is the owner as before (SSH tunnels, `chi --remote` over `ssh -L`, curl, the e2e
+   harness).
 2. A `chp_` token (`Grants.token?`) whose grant is active: a **participant** (`Principal.new(kind: :participant,
    grant:)`), from any peer: loopback and a chi web not on the LAN too. An ended or unknown one is refused
    (below), never the owner.
@@ -134,7 +140,10 @@ participant** and **one role**, until it expires or is revoked.
    (`Server.local_owner_link`), the fragment trade sets the cookie there. `PairCommand` still denies a pair command
    naming chi web on a loopback name (defense in depth), and URL openers and listeners: a page opened in the owner's
    browser at a port the shell listens on would catch the owner's cookie (one on 127.0.0.1 or the LAN address goes
-   to every port).
+   to every port: on 127.0.0.1 it holds the loopback value of rule 1, usable only as that cookie from a loopback peer with no proxy trace (anything that can reach loopback, such as an `ssh -L` user or code running as the owner, can still replay it); on
+   the LAN address it is the token, a known gap, as a cookie there is replayable from any LAN device anyway). A
+   server on another local port can also answer `Set-Cookie: chi_token=…` and overwrite the owner's cookie (cookie
+   tossing: it logs the owner out, or swaps in a grant's token; visible, nothing leaks; not fixed).
 4. Anything else: nil. `#token_gate` answers a bound grant's token without its identity **401 `token_bound`**, an
    ended grant's token **401 `token_revoked`** or **401
    `token_expired`** (the page says the same words as a sentence: "This review link was revoked by the session's
@@ -143,7 +152,8 @@ participant** and **one role**, until it expires or is revoked.
 
 The `?token=` trade (and `POST /api/token`, with a link's one-time `{code}` or the 401 page's pasted `{token}`; with
 `web.public_url` only through the proxy, as a direct request takes Bearer only) sets the `chi_token` cookie (`__Host-chi_token`, Secure, on a proxied request) to the token that was
-presented, the owner's or the participant's
+presented, the owner's or the participant's (the owner's loopback value instead, on a LAN chi web's loopback peer,
+`App#owner_cookie_value`)
 (one at a time per browser: a participant link opened in the owner's browser replaces the owner's cookie there, and
 makes that browser the participant, on loopback too). A grant's token is traded on any peer; the owner's only where
 the gate asks for it (on the LAN, this machine's loopback too). On a chi web the gate doesn't ask (loopback only), the
@@ -365,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
@@ -418,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),
@@ -444,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
@@ -510,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,

data/docs/internals/prompt-caching.md

@@ -232,8 +232,11 @@ is prefilled once. The native and the chat loop use the same plan.
    classifier: `Thinking.cache_cost` (`:full` for Gemma, `:provider` for a remote chat host, `:tail` otherwise) and
    `ReasoningHistory.cache_cost` (`:history` for a change to or from `all` once an earlier reply has thinking).
    `CacheConfirm.needed?` asks only for `:full`, `:provider` and `:history`, when the effective level changes and
-   the session has a model reply. A new setting with a cost (a `/model` across templates, `/llm-context` turning
-   forget on) adds its classifier and goes through the same step.
+   the session has a model reply. The confirmation estimates the reread size from the latest known context count:
+   the whole conversation for `:full` / `:provider`, or up to the first changed reply for `:history`; it omits the
+   estimate when no count is known. On `api: anthropic`, a `:full` / `:provider` change also warns that preserved
+   thinking in replies is dropped from then on. A new setting with a cost (a `/model` across templates,
+   `/llm-context` turning forget on) adds its classifier and goes through the same step.
 7. **No wall-clock time rendered at wire time.** A history entry's `at` (`MessageTime::KEY`, when it happened) is
    display-only: no wire format reads it, and a guard spec checks that `ChatLoop#wire_messages` and
    `Prompt.format_with_images` give the same bytes with and without it (`spec/message_time_history_spec.rb`). A

data/docs/sessions.md

@@ -1,6 +1,6 @@
 # Sessions
 
-Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Besides the messages and turn state, the JSON keeps `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
+Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Besides the messages and turn state, the JSON keeps `written_by` (the chi version that saved it last; see *Which chi a worker runs*), `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
 
 **Message times:** an entry of `messages` may carry `at`, when it happened: a local-offset ISO time with milliseconds (`2026-10-24T14:32:05.120+02:00`). User prompts, lines merged into a turn and steers, reminders, context and task notes, and the model's replies have one (a note's is its `created_at`); tool results, `!cmd` messages and chi's own turn notes don't, nor does anything saved before chi stamped messages (no backfill). It is for the UIs only (the gap dividers, a bubble's time): it never goes to the model, so it changes nothing in the requests or their prompt cache. The one time the model reads is the reminders': due reminders go into a turn as a system message headed `[SYSTEM: REMINDERS DUE 2026-10-24 14:32 local]` (the turn's local time; `ReminderQueue#inject!`), written into the saved content then, so a later request sends the same text.
 
@@ -29,7 +29,9 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 **Attached by default:** plain `chi` and `chi --resume ID` run their session in a background worker and attach to it (`session.shared`, default `true`; env `SAMAGOTCHI_SESSION_SHARED`). The worker runs in the session's `working_directory`, so `!commands` and tools see the directory the session was started in. `session.shared: false` keeps the in-process REPL, `--no-shared` does for one run; a session the REPL has open can't be attached ("close it there first"). See [CLI: Sharing a session](cli.md#sharing-a-session).
 
-**Which chi a worker runs:** a new or woken worker runs the newest chi installed for this Ruby (`gem 'samagotchi', '>= 0.a'`, prereleases count), whoever starts it: a `chi web` or terminal still on an older chi starts it on the newest one, so a stale process doesn't spread old code. A worker already running keeps its version until it is restarted. Should the newest install fail to load, the worker runs the starter's own version and logs `boot_fallback` (its stdio is `/dev/null`). Under `bundle exec` the worker drops Bundler's env first, so it activates the newest gem too. Two consequences: a wrapper pin (`chi _0.17.0_ web`) pins only that process, not the workers it starts; and a source checkout (`bin/chi` in a worktree, `bundle exec`) starts its workers on its own `lib/`, but a session it made that is later woken by an installed chi (`chi web`, `chi send`) runs the installed code. The names an older starter hands a newer worker (the boot line, its env keys, `input/` files, the session JSON fields and the Bridge routes sessions use on each other) are pinned in `spec/worker_contract_spec.rb`.
+**Which chi a worker runs:** a new or woken worker runs the newest chi installed for this Ruby (`gem 'samagotchi', '>= 0.a'`, prereleases count), whoever starts it: a `chi web` or terminal still on an older chi starts it on the newest one, so a stale process doesn't spread old code. A worker already running keeps its version until it is restarted. Should the newest install fail to load, the worker runs the starter's own version and logs `boot_fallback` (its stdio is `/dev/null`). Under `bundle exec` the worker drops Bundler's env first, so it activates the newest gem too. Two consequences: a wrapper pin (`chi _0.17.0_ web`) pins only that process, not the workers it starts; and a source checkout (`bin/chi` in a worktree, `bundle exec`) starts its workers on its own `lib/`, but a session it made that is later woken by an installed chi (`chi web`, `chi send`) runs the installed code. The names an older starter hands a newer worker (the boot line, its env keys, `input/` files, the session JSON fields and the Bridge routes sessions use on each other) are pinned in `spec/worker_contract_spec.rb`. A chi newer than 0.130.0 keeps the top-level keys it doesn't know (a newer chi's fields) when it saves a session, after its own, and doesn't act on them; `written_by` names the chi that saved the file last, and a worker woken on a file a newer chi saved logs `newer_writer`. chi 0.130.0 and older drop those keys: a session a newer chi made loses its newer fields when an older chi wakes or saves it (for example `chi --attach` from a project whose Ruby has an older chi). Keep the chi in every Ruby you run it from newer than 0.130.0.
+
+A new session field (the rule in `Session::FIELDS`' comment): only top-level keys are kept (a new sub-key of `review`, `toolkit` or another value object is still dropped by an older chi), and an older chi keeps a key without honouring it, so a new field must be safe to come back unchanged after an older chi ran turns on the session.
 
 **A worker outlives whoever started it:** a spawned worker leaves its spawner's process tree (it is forked again, in a session of its own, and reparented to init), so closing the terminal of a `chi web`, or a tool tearing down a background `chi send --wait` and its children, no longer takes the worker and its turn with it.
 

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

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.130.0
+version: 0.131.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/cache_confirm.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  # The confirm step before a session setting change that restarts the
-  # prompt cache (/thinking, /reasoning-history): such a change, sent
-  # without --yes from a person at a web tab or a chi TUI, changes nothing
+  # The confirm step before a command that restarts the prompt cache: sent
+  # without --yes by a person at a web tab or a chi TUI, it changes nothing
   # and replies with what it costs and the line that applies it. Two steps,
   # no stored state: the reply carries a Confirm (SessionCommands::Result,
   # the worker's command_ran), the TUI prefills its line, the web draws an
@@ -43,12 +42,33 @@ module Samagotchi
       changed && history && COSTLY.include?(cost)
     end
 
-    # The Confirm for +name+ set to +word+: the line with --yes, and the
-    # question naming it.
-    # @return [Confirm]
-    def confirm(name, word)
-      line = "#{name} #{word} --yes"
-      Confirm.new(line: line, text: "Nothing changed yet: send `#{line}` to apply.")
+    # Whether a cache-changing command should ask, and its reply line.
+    # Kept independent of any UI so commands and plugins can share it.
+    # @param line [String] the full command line without --yes
+    # @param cost [Symbol, nil] the change's cache cost
+    # @param changed [Boolean] whether the effective setting changes
+    # @param engine [Engine] supplies history, used tokens and model host
+    # @return [Confirm, nil]
+    def ask(line:, cost:, changed:, engine:)
+      return nil unless needed?(cost: cost, history: engine.history?, changed: changed)
+
+      apply_line = "#{line.to_s.strip} --yes"
+      notes = []
+      tokens = engine.cache_restart_tokens
+      if tokens
+        size = tokens >= 1000 ? "#{format("%.1f", tokens / 1000.0).delete_suffix(".0")}k" : tokens.to_s
+        notes << case cost
+                 when :full, :provider
+                   "The next request reads the whole conversation again (about #{size} tokens)."
+                 when :history
+                   "The next request reads again from the first changed reply (up to about #{size} tokens)."
+                 end
+      end
+      if %i[full provider].include?(cost) && engine.cache_restart_anthropic?
+        notes << "On an `api: anthropic` host, preserved thinking in replies is dropped from then on."
+      end
+      notes << "Nothing changed yet: send `#{apply_line}` to apply."
+      Confirm.new(line: apply_line, text: notes.compact.join("\n"))
     end
   end
 end