samagotchi 0.130.0 → 0.130.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5830c4028607020136e2f0493d0d365f5d10889fa8ff2a493b979de7b7e164b9
-  data.tar.gz: 28f0fda8ba4b824af19381b12274262c0858f879565b58ab4a6a12e18b82f64e
+  metadata.gz: dcca1391e17e266cf83e1c56dec7ab52d21a1928a4c5190d2bf594884cca936f
+  data.tar.gz: fc59a582d279b19352c3bda61bb5d2fc3796ae0e079e52b3dcb26dc85988ea33
 SHA512:
-  metadata.gz: 38f04438ffc54f5569abbbfb5fdfdd7470ca805926f3593969924a5a248b29ff266f2eec6972aff25d29395982b255b6518989f174a1579b227a711ae1aeec68
-  data.tar.gz: 3dc45f2617ca67e11f8cf563c83ea1c979142d798d900b000b5f1ae0c12ffb559b692cdec8f8f614da09eeb8cd176a1e7e5af59d47958ddffc838b3faa8f8d9d
+  metadata.gz: b5cc1d80ca1b0d64f809360e111bdae2778772c5ca3c8cae7d6f339f650a55fb65b796ccc5ca3038b25c637223568a7facbc90a351ac5df77bee25c24fac3e59
+  data.tar.gz: 4e149d518537a529c69494f14b0d07435c6e3327d27ae34a42c0e30504c74fee543282c4023fbd44587a301f189c24bd7d3aebdff40235784bd45f95cfd63217

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [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 +4964,8 @@ 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.130.1...HEAD
+[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
@@ -1271,7 +1275,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/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

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.130.1
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/desktop/macos.rb

@@ -41,9 +41,11 @@ module Samagotchi
       BUILD_NAME = ".chi-helper-build"
       OLD_NAME = ".chi-helper-old"
       # Apps started by launchd get a bare env (no shell rc files), so the
-      # launch file carries what chi needs to find its gems and state. Only
-      # these, and only when set: no tokens, no runtime knobs.
+      # launch file carries what chi needs to find its gems, state and tools.
+      # Only these, and only when set: no tokens, no runtime knobs.
       ENV_ALLOWLIST = %w[XDG_CONFIG_HOME XDG_STATE_HOME GEM_HOME GEM_PATH RUBYLIB].freeze
+      # PATH is separately filtered to absolute dirs and frozen when written,
+      # so the helper's chi, workers and execute can find the shell's tools.
       # Without it Ruby reads stdin as US-ASCII and non-ASCII notes break.
       LANG = "en_US.UTF-8"
       # chi broadcast's default triage deadline, and the helper's seconds on
@@ -54,6 +56,17 @@ module Samagotchi
       # one launch-file section each, in this order.
       TERMINALS = %w[kitty tmux].freeze
 
+      # PATH dirs the helper can use from launchd's / working directory:
+      # keep absolute entries only, in order, once each.
+      def self.path_dirs(env)
+        env["PATH"].to_s.split(File::PATH_SEPARATOR).select { _1.start_with?("/") }.uniq
+      end
+
+      def self.baked_path(env)
+        dirs = path_dirs(env)
+        dirs.empty? ? nil : dirs.join(File::PATH_SEPARATOR)
+      end
+
       # Runs a command without a shell; [output, success].
       class Runner
         def run(argv)
@@ -76,7 +89,8 @@ module Samagotchi
 
       # The tmux: settings, or nil while tmux.enabled is off. The binary is
       # tmux.binary, else the tmux on +env+'s PATH ("" when there is none:
-      # see #warnings); the socket dir is where tmux puts `-L` sockets
+      # only absolute dirs are usable from launchd; see #warnings); the socket
+      # dir is where tmux puts `-L` sockets
       # ($TMUX_TMPDIR when it is a directory, else /tmp, then tmux-<uid>).
       # Both are frozen at bake time, like the rest of the launch file.
       def self.tmux_settings(get = Config.method(:get), env: ENV)
@@ -91,8 +105,7 @@ module Samagotchi
       end
 
       def self.path_tmux(env)
-        env["PATH"].to_s.split(File::PATH_SEPARATOR).reject(&:empty?).map { File.join(_1, "tmux") }
-                   .find { File.file?(_1) && File.executable?(_1) }.to_s
+        path_dirs(env).map { File.join(_1, "tmux") }.find { File.file?(_1) && File.executable?(_1) }.to_s
       end
 
       # Each switched-on terminal's settings by name ("kitty" => …).
@@ -148,10 +161,14 @@ module Samagotchi
       # `gem cleanup`), else this checkout's bin/chi. A section per terminal
       # switched on (TERMINALS order); the broadcast timeout when given.
       # The XDG dirs go in absolute (Paths): launchd starts the app in /,
-      # where a relative one would mean /<dir>.
+      # where a relative one would mean /<dir>. PATH is filtered to absolute,
+      # deduplicated dirs so chi, its workers and execute find shell tools;
+      # it is frozen at bake time.
       def launch_config
         env = { "LANG" => LANG }
         ENV_ALLOWLIST.each { |name| env[name] = @env[name] unless @env[name].to_s.empty? }
+        path = self.class.baked_path(@env)
+        env["PATH"] = path if path
         env.merge!(Paths.absolute_xdg(env: env, set: :key))
         config = { "version" => @version, "argv" => [@ruby, @chi_path], "env" => env, "sources_sha" => sources_sha }
         TERMINALS.each { |name| config[name] = @terminals[name] if @terminals[name] }
@@ -178,22 +195,55 @@ module Samagotchi
         launch["sources_sha"] != sources_sha || !launch_ok?(launch)
       end
 
-      # The launch file names another chi version or path than this one, or
-      # other terminal settings or broadcast timeout: refresh_launch_file
-      # fixes that without a rebuild.
+      # The launch file names an older chi version than this one (or none), or
+      # other terminal settings, broadcast timeout or a missing bakeable PATH:
+      # refresh_launch_file fixes that without a rebuild. A different argv or
+      # baked PATH, or a newer version, is intentional: the ruby, chi and PATH
+      # the helper runs change only with chi desktop install --force or upgrade.
       def launch_outdated?
         launch = read_launch
-        launch["version"] != @version || Array(launch["argv"]) != launch_config["argv"] ||
+        older_version?(launch["version"]) ||
           TERMINALS.map { launch[_1] } != TERMINALS.map { @terminals[_1] } ||
-          launch["broadcast_timeout"] != @broadcast_timeout
+          launch["broadcast_timeout"] != @broadcast_timeout || path_missing?(launch)
+      end
+
+      # Why chi update can't keep the launch file's ruby or chi: one of them
+      # is gone. nil when it runs, or has no usable argv (a refresh writes
+      # this chi's then).
+      def launch_problem
+        argv = usable_argv(read_launch)
+        missing = Array(argv).reject { |path| File.exist?(path) }
+        return nil if missing.empty?
+
+        "chi not found at #{missing.join(", ")}: run chi desktop install --force from the shell whose chi it should run"
+      end
+
+      # The chi version the launch file names, nil without one.
+      def launch_version = read_launch["version"]
+
+      # The launch file names a newer chi than this one: an older chi's
+      # chi update keeps the helper as it is (no rebuild from older sources).
+      def launch_newer?
+        Gem::Version.new(launch_version.to_s) > Gem::Version.new(@version)
+      rescue ArgumentError
+        false
       end
 
       # Rewrite the launch file for this chi and its settings, keeping
-      # the env it was installed with. The app reads it at each send: no restart.
+      # its argv and the env it was installed with; a PATH only when it has
+      # none (changing them takes chi desktop install --force or upgrade). A
+      # newer version stays. The app reads it at each send.
       def refresh_launch_file
         config = launch_config
-        env = read_launch["env"]
-        config["env"] = env if env.is_a?(Hash)
+        old = read_launch
+        config["argv"] = usable_argv(old) || config["argv"]
+        config["version"] = old["version"] unless older_version?(old["version"])
+        old_env = old["env"]
+        if old_env.is_a?(Hash)
+          config["env"] = old_env
+          path = self.class.baked_path(@env)
+          config["env"]["PATH"] = path if config["env"]["PATH"].to_s.empty? && path
+        end
         write_launch_file(config)
       end
 
@@ -242,7 +292,9 @@ module Samagotchi
 
       # @yield [String] progress lines
       # @param login [Boolean] also start the app at login
-      def install(force: false, login: false, &progress)
+      # @param keep_launch [Boolean] keep the launch file's ruby, chi and PATH
+      #   (chi update's rebuild) instead of baking this shell's
+      def install(force: false, login: false, keep_launch: false, &progress)
         raise Error, "already installed (#{app_version}); use chi desktop upgrade" if installed? && !force
 
         toolchain!
@@ -250,7 +302,7 @@ module Samagotchi
         progress&.call("building #{APP_NAME} #{@version} (can take a few minutes)…")
         built = build_app
         swap_in(built)
-        write_launch_file
+        write_launch_file(keep_launch: keep_launch)
         register_app
         self.login = true if login
         progress&.call("installed #{app_path}")
@@ -258,9 +310,9 @@ module Samagotchi
       end
 
       # Keeps the login item as it was.
-      def upgrade(&)
+      def upgrade(keep_launch: false, &)
         was_login = installed? && login == "enabled"
-        install(force: true, login: was_login, &)
+        install(force: true, login: was_login, keep_launch: keep_launch, &)
       end
 
       # SMAppService status as the app reports it ("enabled",
@@ -313,6 +365,7 @@ module Samagotchi
           launch_ok: launch_ok?(launch),
           stale: stale?,
           baked_dirs: env.select { |name, _| name.start_with?("XDG_") },
+          baked_path: env["PATH"],
           service: dump.include?(BUNDLE_ID),
           running: running,
           host_keys: host_keys
@@ -393,12 +446,39 @@ module Samagotchi
         {}
       end
 
+      # This chi is newer than the version the launch file names; a missing or
+      # unreadable version counts as older.
+      def older_version?(version)
+        Gem::Version.new(@version) > Gem::Version.new(version.to_s)
+      rescue ArgumentError
+        true
+      end
+
+      def usable_argv(launch)
+        argv = launch["argv"]
+        argv if argv.is_a?(Array) && !argv.empty? && argv.all? { |path| path.is_a?(String) && !path.empty? }
+      end
+
+      def path_missing?(launch)
+        return false unless self.class.baked_path(@env)
+
+        env = launch["env"]
+        !env.is_a?(Hash) || env["PATH"].to_s.empty?
+      end
+
       def launch_ok?(launch)
         argv = Array(launch["argv"])
         !argv.empty? && argv.all? { |path| File.exist?(path) }
       end
 
-      def write_launch_file(config = launch_config)
+      def write_launch_file(config = launch_config, keep_launch: false)
+        if keep_launch
+          old = read_launch
+          config["argv"] = usable_argv(old) || config["argv"]
+          old_env = old["env"]
+          old_path = old_env["PATH"] if old_env.is_a?(Hash)
+          config["env"]["PATH"] = old_path unless old_path.to_s.empty?
+        end
         FileUtils.mkdir_p(@support_dir)
         AtomicFile.write(launch_path, JSON.pretty_generate(config) + "\n")
       end

data/lib/samagotchi/desktop_command.rb

@@ -118,11 +118,12 @@ module Samagotchi
                   "#{s[:app_version] || "?"} (up to date: chi #{s[:chi_version]} changed nothing in it)"
                 end
       launch = s[:launch_argv].empty? ? "(none)" : s[:launch_argv].join(" ")
-      launch += s[:launch_ok] ? " (ok)" : " (missing: chi update)"
+      launch += s[:launch_ok] ? " (ok)" : " (missing: chi desktop install --force)"
       dirs = s[:baked_dirs].empty? ? "(defaults)" : s[:baked_dirs].map { |name, value| "#{name}=#{value}" }.join(" ")
+      path = path_row(s[:baked_path])
       service = s[:service] ? "registered" : "not registered (try chi desktop upgrade, or log out and back in)"
       running = s[:running] ? "running" : "not running (open -g \"#{s[:app_path]}\")"
-      rows = [["Chi Helper", version], ["app", s[:app_path]], ["runs chi", launch], ["state dirs", dirs],
+      rows = [["Chi Helper", version], ["app", s[:app_path]], ["runs chi", launch], ["state dirs", dirs], ["PATH", path],
               ["service", service], ["hotkey", hotkey(s[:hotkey])], ["process", running], ["at login", login(s[:login])]]
       rows << ["host keys", host_keys(s[:host_keys])] unless Array(s[:host_keys]).empty?
       @stdout.puts(format_rows(rows))
@@ -153,6 +154,10 @@ module Samagotchi
       end
     end
 
+    def path_row(path)
+      path.to_s.empty? ? "(none: macOS's default; chi update fills it, chi desktop install --force changes it)" : path
+    end
+
     def format_rows(rows)
       width = rows.map { |label, _| label.length }.max
       rows.map { |label, value| "#{label.ljust(width)}  #{value}" }.join("\n")

data/lib/samagotchi/guardrails/rules.rb

@@ -112,8 +112,8 @@ module Samagotchi
             # A resolved match only adds an ask or a deny; were a verdict
             # ever to let a call through, a symlink into its glob must not.
             if resolved_match?
-              real_base ||= PathResolve.real(base)
-              forms += PathResolve.reals(p).map { |real| [real, real_base] }
+              real_base ||= targets.real_rule_base
+              forms += targets.real_forms(p).map { |real| [real, real_base] }
             end
             forms.any? do |form, from|
               candidate = absolute ? form : relative(form, from)

data/lib/samagotchi/guardrails/targets.rb

@@ -379,6 +379,19 @@ module Samagotchi
         @paths.any? { |p| Outside.outside?(p, root: @session_root) }
       end
 
+      # The resolved forms used by rules' path: globs, once per target path.
+      def real_forms(path)
+        @real_forms ||= {}
+        @real_forms[path] ||= PathResolve.reals(path)
+      end
+
+      # The resolved base used by rules' path: globs.
+      def real_rule_base
+        return @real_rule_base if defined?(@real_rule_base)
+
+        @real_rule_base = PathResolve.real(@repo_root || @cwd)
+      end
+
       # Where a shell call runs mutating git (ShellGitDirs: dirs, and
       # :unknown for one the text doesn't tell); [] for other tools.
       def git_dirs

data/lib/samagotchi/session.rb

@@ -14,6 +14,7 @@ require_relative "session_setup"
 require_relative "prompt_note"
 require_relative "working_set_pin"
 require_relative "session_review"
+require_relative "version"
 
 require_relative "paths"
 require_relative "project_scope"
@@ -351,17 +352,27 @@ module Samagotchi
     # saved.
     attr_accessor :opener
 
+    # The top-level keys of the session file this chi doesn't know (a newer
+    # chi's fields), frozen, string keys: #to_h writes them back after the
+    # FIELDS as they were. Never read by this chi.
+    attr_reader :extra_fields
+
+    # The chi version that last saved the loaded file (#to_h writes this
+    # chi's VERSION); nil for a file from 0.130.0 or older.
+    attr_reader :written_by
+
     def initialize(id:, mode:, model_name:, working_directory:, messages:, created_at:, updated_at:,
-                   metadata_version: METADATA_VERSION, status: STATUS_IDLE, last_prompt: "",
+                   metadata_version: METADATA_VERSION, written_by: nil, status: STATUS_IDLE, last_prompt: "",
                    first_preview: "", first_turn_id: nil, test_run: false, pending_question: nil,
                    used_memory_names: [], project_root: nil,
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
                    continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
                    toolkit: nil, toolkit_origin: "chosen", settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil,
-                   working_set_pins: [], review: nil, verdicts: nil, verify_fresh: nil)
+                   working_set_pins: [], review: nil, verdicts: nil, verify_fresh: nil, extra_fields: {})
       @id = id
       @metadata_version = metadata_version
+      @written_by = written_by
       @mode = mode
       @model_name = model_name
       @model_typed = model_typed
@@ -399,12 +410,25 @@ module Samagotchi
       self.verdicts = verdicts
       self.verify_fresh = verify_fresh
       self.interrupted_turn = interrupted_turn
+      @extra_fields = extra_fields.to_h { |key, value| [key.to_s, value] }.freeze
       @turn_checkpoint = nil
       @archived = false
       # #save's lock: one snapshot-and-write at a time (see #save).
       @save_lock = Mutex.new
     end
 
+    # Whether a chi newer than this one saved the loaded file: its
+    # written_by is a later version, or it has keys this chi doesn't know
+    # (a hand-edited or future file). The worker logs it (newer_writer).
+    def newer_writer?
+      return true unless @extra_fields.empty?
+
+      # correct?(nil) is true (a 0 version): a file without the field is no newer.
+      return false unless @written_by.is_a?(String) && Gem::Version.correct?(@written_by)
+
+      Gem::Version.new(@written_by) > Gem::Version.new(VERSION)
+    end
+
     # A `delegate` child: its turns report to its parent (ChildReports). A
     # child saved before the field is known by the memory every delegate
     # starts with; a fork is neither.
@@ -543,8 +567,24 @@ module Samagotchi
     # the way (symbols in memory, strings on disk); last_turn, prompt_notes
     # and pending_question are value objects in memory (LastTurn,
     # PromptNote, PendingQuestion).
+    #
+    # A new field: a chi older than it (from the release after 0.130.0)
+    # keeps the key as it was (#extra_fields) but doesn't honour it, and the
+    # next newer chi reads it again. So it must be safe to come back
+    # unchanged after an older chi ran turns on the session: static data, or
+    # append-only data the older chi never appends to (review, verify_fresh,
+    # first_turn_id, verdicts); a cursor into messages, which an older chi
+    # would have moved, needs a check against what it points at. Only
+    # top-level keys are kept: the value objects (SessionReview,
+    # VerifyFreshOrigin, Toolkit, LastTurn, PendingQuestion, InterruptedTurn,
+    # PromptNote, WorkingSetPin, LLMContextOverride) write their own members
+    # only, so an older chi still drops a new sub-key of one of them; add a
+    # top-level field when an older chi must keep it. A removed key would
+    # stay an extra forever: leave it out of the extras in .from_h then (no
+    # key was ever removed).
     FIELDS = {
       "metadata_version" => 1,
+      "written_by" => nil,
       "id" => REQUIRED,
       "mode" => REQUIRED,
       "model_name" => REQUIRED,
@@ -599,6 +639,7 @@ module Samagotchi
       end
       attrs[:settings] = SessionConfig::Settings.new(core: attrs.delete(:config_settings), bundles: attrs.delete(:bundle_settings))
       attrs[:messages] = messages ? Array(attrs[:messages]).map { |msg| symbolize_message_keys(msg) } : []
+      attrs[:extra_fields] = data.reject { |key, _| FIELDS.key?(key) }
       new(**attrs)
     end
 
@@ -720,8 +761,10 @@ module Samagotchi
       self
     end
 
-    # The session as #save writes it (FIELDS, in their order); a running
-    # turn's checkpoint (#turn_checkpoint) in place of its messages.
+    # The session as #save writes it: FIELDS, in their order, then the keys
+    # this chi doesn't know (#extra_fields, in the file's order; a FIELDS key
+    # wins); a running turn's checkpoint (#turn_checkpoint) in place of its
+    # messages.
     def to_h
       checkpoint = checkpointed
       FIELDS.keys.to_h do |key|
@@ -730,6 +773,7 @@ module Samagotchi
                   (checkpoint ? checkpoint[:messages] : @messages).map { |msg| scrub_utf8(stringify_message_keys(msg)) }
                 when "interrupted_turn" then (checkpoint ? checkpoint[:marker] : @interrupted_turn)&.to_file
                 when "pending_question" then @pending_question && scrub_utf8(@pending_question.to_file)
+                when "written_by" then VERSION
                 when "test_run" then !!@test_run
                 when "delegate" then @delegate
                 when "llm_context" then llm_context_file
@@ -755,6 +799,7 @@ module Samagotchi
                 end
         [key, value]
       end.reject { |key, value| value.nil? && OPTIONAL_FIELDS.include?(key) }
+        .merge(@extra_fields.reject { |key, _| FIELDS.key?(key) })
     end
 
     # The running turn's checkpoint, while the turn runs (#turn_checkpoint).

data/lib/samagotchi/tools/execute.rb

@@ -85,7 +85,10 @@ module Samagotchi
       # @param stop_reason [#call] the stop's reason (:signal: a signal to
       #   chi, :session_stopped: a session stop, which the result then names
       #   instead of the user)
-      # @param env [Hash, nil] added to the command's environment
+      # @param env [Hash, nil] added to the command's environment, over
+      #   chi's Ruby/Bundler variables scrubbed as task_create scrubs them
+      #   (TaskRuntime.sanitized_spawn_env); chi's callers build it, so it
+      #   may set those keys (task_create refuses them from the model)
       # @param on_timeout [Symbol, String, nil] :task or :kill (ON_TIMEOUT);
       #   nil reads execute.on_timeout
       def self.call(command, cwd: nil, cancelled: -> { false }, stop_reason: -> {}, env: nil, on_timeout: nil)
@@ -267,7 +270,7 @@ module Samagotchi
         # file, and each write lands at the end.
         ios = logs.map { |path| File.open(path, "a") }
         ios.each { |io| io.flock(File::LOCK_SH) }
-        ProcessGroup.spawn(env || {}, *Shell.argv(TaskRuntime.wrapped_shell_command(command, exit_code_path)),
+        ProcessGroup.spawn(TaskRuntime.sanitized_spawn_env.merge(env || {}), *Shell.argv(TaskRuntime.wrapped_shell_command(command, exit_code_path)),
                            chdir: cwd, in: File::NULL, out: ios[0], err: ios[1])
       ensure
         ios&.each(&:close)

data/lib/samagotchi/tools/task_runtime.rb

@@ -445,9 +445,11 @@ module Samagotchi
         "trap #{Shellwords.escape(write)} EXIT\n#{command}\n"
       end
 
+      # chi's own Ruby/Bundler setup, kept out of a command's environment
+      # (execute and task_create both spawn with it): run under `bundle
+      # exec`, chi would otherwise hand a project's `ruby -e` or
+      # `bundle exec` its Gemfile (RUBYOPT=-rbundler/setup, BUNDLE_GEMFILE).
       def sanitized_spawn_env
-        # Running from temporary directories can inherit Bundler-specific env
-        # (for example RUBYOPT=-rbundler/setup) that breaks plain `ruby -e`.
         {
           "RUBYOPT" => sanitized_rubyopt,
           "RUBYLIB" => nil,

data/lib/samagotchi/update_command.rb

@@ -250,9 +250,17 @@ module Samagotchi
       return row.tap { |r| r.status = "not installed" } unless helper.installed?
 
       row.from = helper.app_version
+      if (problem = helper.launch_problem)
+        return failed(row, problem)
+      end
+
+      if helper.launch_newer?
+        return up_to_date(row).tap { |r| r.status += " (kept: chi #{helper.launch_version} set it up; this chi is older)" }
+      end
+
       if helper.stale?
         row.to = VERSION
-        done(row, :update, @dry_run ? "rebuilds and restarts it" : "restarted") { helper.upgrade { nil } }
+        done(row, :update, @dry_run ? "rebuilds and restarts it" : "restarted") { helper.upgrade(keep_launch: true) { nil } }
       elsif helper.launch_outdated?
         helper.refresh_launch_file unless @dry_run
         up_to_date(row).tap { |r| r.status += @dry_run ? " (would refresh the launch file)" : " (launch file refreshed)" }

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.130.0"
+  VERSION = "0.130.1"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -55,6 +55,7 @@ require_relative "../review_start"
 require_relative "../parent_answers_command"
 require_relative "../guardrails/parent_policy"
 require_relative "markdown_renderer"
+require_relative "token"
 require_relative "capabilities"
 require_relative "editor"
 require_relative "../message_parts"
@@ -431,6 +432,10 @@ module Samagotchi
       end
 
       TOKEN_COOKIE = "chi_token"
+      # The owner's cookie holds the token, but on the LAN a loopback
+      # peer's holds Token.loopback_cookie (#owner_cookie_value): a cookie
+      # for 127.0.0.1 goes to every server on any of its ports (a dev
+      # server that logs headers), and that value works nowhere else.
       # 400 days, the longest a browser keeps a cookie (Chrome's cap). No
       # Secure: the LAN page is plain http. Lax, not Strict: a token link
       # opened from another site (a web messenger) makes its 303 chain
@@ -473,10 +478,10 @@ module Samagotchi
         principal = principal_for(req)
         return [nil, refused_token(req)] if principal.nil?
 
-        # The cookie gets the token that was presented: the owner's, or the
-        # participant's grant's.
+        # The cookie gets the participant's grant's token, or the owner's
+        # cookie value (the loopback one on the LAN's 127.0.0.1).
         if token_trade?(req)
-          token = req.env[GRANT_TOKEN_ENV] || current_token
+          token = req.env[GRANT_TOKEN_ENV] || owner_cookie_value(req)
           return [nil, token_redirect(req, token)] unless fragment_trade?(req)
           return [nil, form_trade_redirect(req, token)] if form_post?(req)
 
@@ -492,7 +497,9 @@ module Samagotchi
       # one, looked up only when no owner token was given), wherever the
       # request comes from, this machine's loopback too; with neither, the
       # owner only on a chi web that asks no token (loopback only: no LAN
-      # mode, no web.public_url), else nil. An ended or unknown grant's
+      # mode, no web.public_url), else nil. The owner's cookie on the LAN's
+      # loopback is the loopback value (#loopback_cookie: it stands for the
+      # token in +given+). An ended or unknown grant's
       # token is nil anywhere: it never falls back to the owner.
       # @return [Principal, nil]
       # With web.public_url (ProxyGate) every request needs a token, and a
@@ -512,12 +519,39 @@ module Samagotchi
       # through the proxy (curl, chi's own callers) presents the Bearer
       # header only: no cookie, and no trade that would set one. A cookie for
       # 127.0.0.1 goes to every server on any of its ports. A LAN peer
-      # (web.host lan) keeps the LAN's token link and cookie.
+      # (web.host lan) keeps the LAN's token link and cookie; a loopback
+      # peer of a LAN chi web reads its cookie through #loopback_cookie.
       def presented_tokens(req)
         return [traded_token(req)] if token_trade?(req)
         return [bearer_token(req)] if direct_public?(req)
 
-        [bearer_token(req), req.cookies[token_cookie_name(req)]]
+        cookie = req.cookies[token_cookie_name(req)]
+        [bearer_token(req), loopback_cookie_peer?(req) ? loopback_cookie(cookie) : cookie]
+      end
+
+      # A loopback peer of a LAN chi web, whose owner cookie holds the
+      # loopback value. With web.public_url, #direct_public? takes the
+      # Bearer only. A request with a proxy's trace (one the user forwards
+      # to loopback by hand) is the LAN's: a leaked loopback value must not
+      # work from off this machine through it.
+      def loopback_cookie_peer?(req)
+        !@lan.nil? && @public_url.nil? && LOOPBACK_PEERS.include?(req.get_header("REMOTE_ADDR").to_s) &&
+          !proxy_trace?(req.env)
+      end
+
+      # What a trade sets as the owner's cookie.
+      def owner_cookie_value(req)
+        loopback_cookie_peer?(req) ? Token.loopback_cookie(current_token) : current_token
+      end
+
+      # A loopback peer's cookie: the loopback value stands for the owner's
+      # token, a grant's chp_ token is itself, and anything else, the token
+      # itself included (a 0.130.0 cookie, #refused_token clears it), is
+      # nothing.
+      def loopback_cookie(value)
+        return current_token if token_match?(value, Token.loopback_cookie(current_token))
+
+        Grants.token?(value) ? value : nil
       end
 
       def direct_public?(req)
@@ -622,10 +656,15 @@ module Samagotchi
       # The 401 for a request #principal_for refused: an ended grant's, else
       # unauthorized. On a peer the gate doesn't ask, a grant's cookie that
       # no longer works is cleared too, so the browser it was left in (the
-      # owner's, who opened a participant link) is the owner's again.
+      # owner's, who opened a participant link) is the owner's again. A
+      # LAN chi web's loopback peer whose cookie is the token itself (set
+      # before the loopback value) has it cleared, so it stops riding to
+      # the other local ports.
       def refused_token(req)
         response = grant_bound_response(req) || grant_ended_response(req) || unauthorized(req)
-        return response if token_required?(req) || !Grants.token?(req.cookies[token_cookie_name(req)])
+        cookie = req.cookies[token_cookie_name(req)]
+        stale = loopback_cookie_peer?(req) && token_match?(cookie, current_token)
+        return response unless stale || (!token_required?(req) && Grants.token?(cookie))
 
         status, headers, body = response
         [status, headers.merge("Set-Cookie" => cleared_token_cookie(req)), body]

data/lib/samagotchi/web/participant_review.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "participant_view"
+require_relative "token"
 require_relative "participant_stream_filter"
 require_relative "participant_exposure"
 require_relative "../session_metrics"
@@ -39,10 +40,16 @@ module Samagotchi
 
       # Who reads: the participant (their author), or the owner through the
       # participant view (nobody's own). The session's folder places tool
-      # paths; the owner's token is never shown.
+      # paths; the owner's token is never shown, nor (LAN) its loopback
+      # cookie value.
       def participant_viewer(req, session)
         author = principal(req).owner? ? nil : principal(req).grant.author
-        ParticipantView::Viewer.new(author: author, cwd: session.working_directory, secrets: [(@lan || @public_url) && current_token].compact)
+        ParticipantView::Viewer.new(author: author, cwd: session.working_directory, secrets: owner_secrets)
+      end
+
+      def owner_secrets
+        token = (@lan || @public_url) && current_token
+        [token, @lan && Token.loopback_cookie(token)].compact
       end
 
       # GET /api/sessions/:id/review: the participant page's data, always

data/lib/samagotchi/web/proxy_gate.rb

@@ -74,6 +74,12 @@ module Samagotchi
         return true if @public_url.host?(env["HTTP_HOST"])
         return true if @public_url.identity_env && env.key?(@public_url.identity_env)
 
+        proxy_trace?(env)
+      end
+
+      # Whether a request carries a proxy's trace (ProxyTrace: X-Forwarded-*,
+      # Forwarded, X-Real-IP, a known identity header).
+      def proxy_trace?(env)
         names = env[RAW_NAMES_ENV] || env.keys.filter_map { |key| ProxyTrace.env_name(key) }
         names.any? { |name| ProxyTrace.header?(name) }
       end

data/lib/samagotchi/web/token.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "openssl"
 require "securerandom"
 require_relative "../atomic_file"
 
@@ -14,11 +15,15 @@ module Samagotchi
     # can read, $XDG_STATE_HOME/samagotchi/web-token (0600). It is made on
     # the first LAN start and kept, so a phone's bookmark survives
     # restarts; `chi web --new-token` replaces it. A loopback-only chi web
-    # never reads it.
+    # never reads it. The owner's cookie for this machine's 127.0.0.1
+    # holds #loopback_cookie, never the token: a server on any other local
+    # port is sent that cookie too.
     module Token
       FILE = "web-token"
       # 32 random bytes: 43 URL-safe characters.
       BYTES = 32
+      LOOPBACK_PREFIX = "chl_"
+      LOOPBACK_LABEL = "chi web loopback cookie v1"
 
       module_function
 
@@ -49,6 +54,20 @@ module Samagotchi
         SecureRandom.urlsafe_base64(BYTES)
       end
 
+      # The owner's 127.0.0.1 cookie on the LAN: an HMAC of a label keyed
+      # by +token+, so a leaked one gives nothing about the token, and
+      # rotating the token ends it. The gate takes it only as that cookie,
+      # from an unproxied loopback peer (App#loopback_cookie_peer?).
+      # @return [String, nil] "chl_" and 43 URL-safe characters; nil
+      #   without a token
+      def loopback_cookie(token)
+        return nil if token.nil? || token.empty?
+
+        # URL-safe base64 without padding (pack: base64 isn't a default gem).
+        digest = OpenSSL::HMAC.digest("SHA256", token, LOOPBACK_LABEL)
+        LOOPBACK_PREFIX + [digest].pack("m0").tr("+/", "-_").delete("=")
+      end
+
       # Written whole under a temporary name, then renamed over +path+: a
       # reader never sees half a token. The file is 0600 from the start,
       # its folder 0700 when this makes it.

data/lib/samagotchi/worker.rb

@@ -251,6 +251,13 @@ module Samagotchi
       ChildMove.clear_starting(@session_id, state_dir: @state_dir)
       ChildMove.adopt(@session_id, state_dir: @state_dir)
       @session = Session.load(@session_id, state_dir: @state_dir)
+      # A newer chi saved it: this worker keeps the fields it doesn't know
+      # but runs the session without them (docs/sessions.md).
+      if @session.newer_writer?
+        unknown = @session.extra_fields.keys.join(",")
+        Log.warn(:worker, "newer_writer", sid: @session_id, version: VERSION, written_by: @session.written_by,
+                                          unknown_fields: (unknown unless unknown.empty?))
+      end
       drop_dead_question
       # The running turn, on disk at its iteration boundaries.
       @checkpoint = TurnCheckpoint.new(session: @session, state_dir: @state_dir)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.130.0
+  version: 0.130.1
 platform: ruby
 authors:
 - Dmitry Dedov