samagotchi 0.122.0 → 0.124.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ba0370c70db9c98a500766ef59cd8cedbf574852c60625679ed84c6a78d50d0
-  data.tar.gz: 937ffbf1066bc4acd34aaaf0ac19680c5099191f0bc87b8681863b362a280940
+  metadata.gz: e85ff88270cf7569d21ff95bba739199ceb3c53d32675b1648a18363ca5482cd
+  data.tar.gz: d9f539982d7c41b94ad40d17368041f2debed8040ebc48a27776486fe2476dc9
 SHA512:
-  metadata.gz: c351af56a92b5df2cfabbd2d8a52ffefd76b1d7be74a92ffacd25f035d5ab6951214aa083a4d016beefd924cf2794d802c91ddf9ca4b437c860716f99e13ea76
-  data.tar.gz: f00a99184817060ca6d8741bee006bbdcacc3438896a48801a49e6694f4cb2c41868cbabca6f7cd27f807a475f752bf1a62acc580104159036dc033f7611965c
+  metadata.gz: e3496206b25f1d329a3a915c075cefe5e0c3e1fc40b71694128c7d3fee633fc65447686efbb4c8f4f19e0872998cecb2f269db67a7428b9b519a9cc5b6469bd3
+  data.tar.gz: 3ed82d4bb9b01288f391e2d68d9eba5b71492fa66f411d7a5fd25276ac68425f8432979fd0d4d59882b741a2dfa79bcb0810fc74e3b2c7e66bb590e0c5bdbccc

data/CHANGELOG.md

@@ -7,6 +7,61 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.124.0] - 2026-10-27
+
+### Added
+
+- The desktop helper's panel lists and sends to the sessions of the remotes `chi remote add` keeps: a section per
+  remote ("on studio") after this Mac's rows, each row tagged with its machine, "→ studio" in the hint while one is
+  ticked, one call per machine at once; a remote that doesn't answer within 4 s or refuses shows one line, and this
+  Mac's rows don't wait for it. A remote with a session also gets a "New session on studio in <folder>" row, in its
+  newest session's folder, on that remote's default model. The Everyone row, the model chooser and agents stay on
+  this Mac.
+- chi web updates chi from its page: the notice's **Update** installs the release it names in a progress sheet
+  that lists kept edits, then offers **Restart workers** (each worker on an older chi; a busy one says what holds
+  it) and **Restart chi web** (in place: same port, token, flags and Tailscale Serve). `chi update --to VERSION`
+  installs an exact release; `--json` prints its rows as JSON.
+
+Update with `chi update` (it rebuilds the desktop helper), then restart `chi web` and the session workers
+(`chi sessions restart`). From the next release on, chi web's Update button does this from its page.
+
+## [0.123.0] - 2026-10-27
+
+### Added
+
+- chi web checks RubyGems daily and shows the newest aged, stable release newer than both the running and installed
+  chi, with its RubyGems page and a command to copy (`chi update`, or the blocker-specific command).
+- chi web sends one 24-hour phone push per newly available chi; it skips the push when a chi web page is in front.
+- `toolkit.suggest.mode: on` starts a new session on the kit System 1 suggests for its first prompt (or a later one
+  after `undecided`), waiting at most System 1's timeout before the first request, with a
+  `toolkit: NAME (suggested, p=…) · /toolkit to change` notice; anything uncertain keeps the default kit.
+- Pair access for a shared working session: a participant invited to a working session (not a `chi review`
+  session) while its worker runs pair turns gets turns that act with the session's tools under the owner's
+  guardrails; the grant is stamped `mode: pair` only when the share warning said so. Existing grants, and any invited
+  while the worker was older, stay read-only review participants until they are invited again. A pair turn's asks
+  reach the owner's card naming who asks, with Allow once only, and System 1 never answers them; a write outside the
+  project always asks, whatever the owner approved before. A new core check (`pair-boundary`) denies reading or
+  writing secrets and chi's own files (keys, shell startup files, histories, credential files; by a file tool, a
+  command, a glob, a variable or a script it hands a shell), running chi, backgrounding commands, reading the
+  environment or the keychain, git settings that run commands, sweeping home with find/tar/cp/grep, the owner-voiced
+  tools (delegate, reminders, notes, background tasks,
+  forgetting outputs, loading tools, memories) and the model's own question. A pair turn stops mid-turn once the
+  participant's cap is passed or their link is revoked or expires. A pair turn's commands run without
+  secret-named environment variables and are killed at the execute limit, and one that writes outside the project
+  asks the owner. Workers name a `pair_turns` feature.
+- Participant turns show a one-line tools overview with expandable, names-only rows that update as a turn runs.
+
+### Changed
+
+- Sharing a working session warns what a participant's turns may do there (writes included, asks to you) instead of
+  only how many tool outputs they can quote. Its participant messages carry a pair header, a `pair` badge and no
+  Apply; review sessions, their messages and their headers are unchanged. The system prompt's participants line,
+  the cap notice, the participant page's note and the participants panel follow the session's mode; the delivery
+  line says "after their turn".
+
+Update with `chi update`, then restart `chi web` and the session workers (`chi sessions restart`); a participant
+invited before this release stays a review participant until invited again.
+
 ## [0.122.0] - 2026-10-27
 
 ### Added
@@ -4658,7 +4713,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.122.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.124.0...HEAD
+[0.124.0]: https://github.com/dm1try/samagotchi/compare/v0.123.0...v0.124.0
+[0.123.0]: https://github.com/dm1try/samagotchi/compare/v0.122.0...v0.123.0
 [0.122.0]: https://github.com/dm1try/samagotchi/compare/v0.121.1...v0.122.0
 [0.121.1]: https://github.com/dm1try/samagotchi/compare/v0.121.0...v0.121.1
 [0.121.0]: https://github.com/dm1try/samagotchi/compare/v0.120.0...v0.121.0

data/bin/chi

@@ -18,6 +18,15 @@ rescue Samagotchi::ConfigFile::RemovedApi => e
 end
 require "samagotchi"
 
+# A web self-restart re-enters through the installed wrapper: its marker and
+# the worker starters to adopt leave ENV before anything spawns with it
+# (Server.take_restart_env!); a restarted chi web skips the first-run hint.
+web_restarted = false
+if ENV.key?("SAMAGOTCHI_WEB_RESTARTED") || ENV.key?("SAMAGOTCHI_WEB_ADOPT_PIDS")
+  require "samagotchi/web/server"
+  web_restarted = Samagotchi::Web::Server.take_restart_env!
+end
+
 # `chi self`: print version, source dir, config/memory/session paths, model and
 # bundles (read-only, offline) — lets the agent find its own code and state.
 if ARGV[0] == "self"
@@ -221,7 +230,7 @@ chi_update_hint = lambda do
 end
 
 if options[:web]
-  chi_update_hint.call
+  chi_update_hint.call unless web_restarted
   require "samagotchi/web/server"
   port = options[:web_port] || Samagotchi::Config.get("web.port")
   markdown = options[:web_markdown]
@@ -233,7 +242,9 @@ if options[:web]
                                       annotate_presets: Samagotchi::Config.get("web.annotate_presets"),
                                       editor: Samagotchi::Config.get("web.editor"),
                                       start_dir: options[:start_dir] || Samagotchi::Config.get("web.start_dir"),
-                                      start_dir_from: options[:start_dir] ? :flag : :config)
+                                      start_dir_from: options[:start_dir] ? :flag : :config,
+                                      restarted: web_restarted,
+                                      restart_argv: Samagotchi::RunOptions.web_restart_argv(options))
 end
 
 # --resume and --attach take a unique id prefix too, like git.

data/docs/architecture.md

@@ -533,12 +533,41 @@ The snapshot names chi's version: a tab served by another one (its `<body data-v
 reload in a toast, since an open tab keeps its old JS across a `chi web` upgrade. It also names
 `installed`, the newest chi on this machine (`InstalledVersions`: the highest `samagotchi-<v>.gemspec`
 in RubyGems' specification dirs, or a checkout's `version.rb` on disk; looked at again on each full
-probe, every 10 s), and a change is a `chi` frame `{version, installed}`. A newer one than the
-server runs is said in chi web's terminal and on the page: restart chi web (its workers already
-run the newest chi, [Sessions](sessions.md)). `GET /api/info` carries `installed` too, and the
-feature `newest_workers`; next to `cwd` (the folder chi web runs in) it names `start_dir`, the folder it
-starts in (`web.start_dir`, `--start-dir`; `Web::StartDir`), which a second `chi web` given another one
-mentions.
+probe, every 10 s). A `chi` frame and the `GET /api/events` snapshot carry the full state
+`{version, installed, available, update_blocked}`; `/api/info` and the session-command wake response
+carry the same fields. `SessionHub#update_available` publishes the checker result under the hub's
+Monitor, but fetching never holds it.
+
+`Web::UpdateCheck` runs its own thread beside the hub. When `update.notify: on` (the default), its
+first RubyGems check is about 30 seconds after chi web starts, then it checks at `update.check_hours`
+intervals. A stable release is available only after `update.min_age_hours` and when newer than both
+the running and newest installed chi. Its atomic, mode-0600
+`$XDG_STATE_HOME/samagotchi/update_check.json` keeps the check cooldown and versions already
+announced across restarts. `update.notify: off` starts no checker thread and makes no network
+request. `update_blocked` names why the local gem cannot be updated in place (checkout, Bundler, or
+an unwritable gem directory). The page tells the owner to run `chi update`; a newer `installed`
+version than the server itself still means restart chi web (its workers already run the newest chi,
+[Sessions](sessions.md)). `GET /api/info` also names `newest_workers`; next to `cwd` (the folder chi
+web runs in) it names `start_dir`, the folder it starts in (`web.start_dir`, `--start-dir`;
+`Web::StartDir`), which a second `chi web` given another one mentions.
+
+The owner's update routes publish progress and results as `chi_update` events with an
+`operation` (`install` or `workers`), `state`, and `rows`; install events also name the target
+`version` and may include a progress line. The hub retains the latest event for a reconnecting
+tab's snapshot. `POST /api/update` decides itself whether this install can take a gem
+(`UpdateCheck.blocked_reason`: a checkout, Bundler, an unwritable gem dir → 409 `update_blocked`), so
+it holds with `update.notify: off`; a child that prints no rows fails with its own last line, and a
+done install refreshes the hub's installed version (`SessionHub#refresh_installed`) before its `done`.
+Worker restarts target every worker older than the version installed now (refreshed the same way)
+and publish per-session results. Only one of an install, a worker restart pass and a web restart runs
+at a time (409 `update_running`). `POST /api/update/restart_web` (409 `restart_unavailable` without a
+chi wrapper to exec) schedules WEBrick shutdown only after its response is sent; after the hub and
+listener stop, `Server` execs the RubyGems chi wrapper with every flag chi web was started with, as
+`RunOptions`' parser recorded them (`RunOptions.web_restart_argv`), but the one-shot `--open` and
+`--new-token`. The re-entry (`SAMAGOTCHI_WEB_RESTARTED`, taken out of ENV first by
+`Server.take_restart_env!`) skips the first-run update hint, adopts live worker-starter PIDs (workers
+themselves are detached), and adopts an exact Tailscale Serve handler. A failed exec, or a restarted
+chi web that doesn't start for any reason, turns off only that exact adopted handler.
 
 The page's scope is in its URL, and the server picks the default: `?dir=<folder>` is that folder's
 project (the list, the events stream and a new chat follow it), `?scope=all` every session, and a bare
@@ -775,4 +804,4 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Stores | `reminder_store.rb` (`ReminderStore`), `recap_store.rb` (`RecapStore`) | A session's reminders, and its idle recap (`recap.json`). |
 | Setup and update | `bootstrap_command.rb`, `bootstrap/`, `update_command.rb`, `gem_update.rb` | `chi bootstrap` (first config.yml, system bundle, core profile) and `chi update` (the gem, shipped bundles, the macOS helper). |
 | Process groups | `process_group.rb` (`ProcessGroup`) | A command in a process group of its own, stopped as a group (TERM, grace, KILL): execute, tasks, context fetches, the mcp bundle's servers. |
-| Desktop | `desktop.rb`, `desktop/macos.rb`, `desktop_command.rb`, `desktop/macos/*.swift` | `chi desktop`, the macOS "Send to chi" helper ([desktop.md](desktop.md)). The helper's Swift side: the panel (`Panel.swift`), the chi CLI runner (`ChiRunner.swift`), agent terminals behind `AgentTerminal` (`AgentTerminal.swift`, `Kitty.swift`, `Tmux.swift`; `ChiHelper --agents` is their CLI seam). |
+| Desktop | `desktop.rb`, `desktop/macos.rb`, `desktop_command.rb`, `desktop/macos/*.swift` | `chi desktop`, the macOS "Send to chi" helper ([desktop.md](desktop.md)). The helper's Swift side: the panel (`Panel.swift`), the chi CLI runner (`ChiRunner.swift`), the session rows and the chi calls a send makes (`Sessions.swift`: `SendPlan`; `ChiHelper --sessions` and `--send-plan` are their CLI seams), agent terminals behind `AgentTerminal` (`AgentTerminal.swift`, `Kitty.swift`, `Tmux.swift`; `ChiHelper --agents` is their CLI seam). |

data/docs/cli.md

@@ -27,18 +27,18 @@
 - `chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]` (or `--dismiss`) — answer the question a session waits on (the one `chi send --wait` exited 3 with), then wait and print what comes next as `chi send --wait` does: the reply (0), the next question (3), still running after `--timeout` (4). `--option` is 1-based or the label, repeated on a multi-select question; `--text` is free text, or a Deny's reason; `--dismiss` leaves it unanswered and the model finishes its reply. A question no longer open (the web answered first) isn't answered again: it waits for that turn's reply. An option the question doesn't offer exits 2; a worker that is gone exits 1 (`send the task again: chi send --wait -m "…" ID`). What a parent may pick follows `guardrails.parent_answers`, or the session's own `parent_answers` when stricter (`soft`, the default: a deny, a plain answer, Continue and "Allow once"; `standard`: no allow; `hard`: no Continue either), never a wider scope or an allow on chi's own config; a refused pick exits 1 with what to answer instead (a convention, not a security boundary; see [Guardrails](guardrails.md#answers-from-a-parent-agent))
 - `chi remote add NAME URL [--token-file F | --token-stdin]`, `chi remote ls`, `chi remote rm NAME` — the other machines whose chi web the session commands reach with `--remote NAME` (see [Remote sessions](#remote-sessions))
 - `chi review FILE… [--dir DIR] [--model M]`, `chi review --from ID [FILE…]` — start a review session to invite participants to: for files of a project, or as a review of a working session that starts from its recap, not its transcript (see [Review sessions](#review-sessions))
-- `chi share ID --name NAME [--identity EMAIL] [--agent] [--expires 3d] [--cap 2]`, `chi share ls [ID]`, `chi share cap ID P DOLLARS`, `chi share revoke ID [P] | --all` — invite a participant to review a session through chi web on the LAN (a link of their own, 7 days, a $2 spending cap), list them, change one's cap, revoke them (see [Participants](#participants))
+- `chi share ID --name NAME [--identity EMAIL] [--agent] [--expires 3d] [--cap 2]`, `chi share ls [ID]`, `chi share cap ID P DOLLARS`, `chi share revoke ID [P] | --all` — invite a participant to a session through chi web on the LAN (read-only review turns in a review session, pair turns that act under your guardrails in a working session) (a link of their own, 7 days, a $2 spending cap), list them, change one's cap, revoke them (see [Participants](#participants))
 - `chi --remote NAME send|answer|note|context|sessions|share|review …` (or `CHI_REMOTE=NAME`) — those commands on that machine's sessions, through its chi web (see [Remote sessions](#remote-sessions))
 - `chi --remote NAME --attach ID` (`--resume ID`, `--dir DIR [-p TEXT]`) — the attached TUI on a session of that machine (see [Remote sessions](#remote-sessions))
 - `chi memory ls [--scope project|system] [--format text|json]` — the memories of both scopes (this folder's project first), one row each: scope, name, size, date, `from <bundle>`, the index description and its model overlays; `chi memory rm NAME [--scope project|system]` removes one as `memory_write` with `remove: true` does: its file and model overlays go to the bundle trash (the line names the dir; `chi bundle trash` lists and empties it) and its index line is dropped. NAME in both scopes without `--scope` exits 2 naming both; a missing NAME or a bundle's memory (`chi bundle uninstall` removes it) exits 1 (see [Memory: Listing and removing from the shell](memory.md#listing-and-removing-from-the-shell))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
-- `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
+- `chi update [--dry-run] [--to VERSION] [--json] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
 - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
 
 - `chi guardrails replay [--dry-run] [--threshold T] [--model M]` — seed System 1's record from the approvals this machine's sessions already answered: each ask is judged by the configured model and written to `guardrails/judgments.jsonl` with the answer the user gave, then a per-rule table prints (asks, allowed, denied, would-be auto-allows, false allows, asks with no judgment). A parent agent's answer is not the user's: only its deny is replayed, and only where the parent could have allowed. `--dry-run` judges without writing, `--threshold` overrides `guardrails.system_one.threshold` for the table, `--model` the configured model for this run. Exit 2 when `guardrails.system_one.mode` is off or no `host` is set; a usage error exits 2 (see [System 1](guardrails.md#system-1-experimental))
-- `chi toolkit report [--days N]` — grade toolkit suggestion audits: the kit on mode would have run (the suggested kit when it would have applied it, else the default) against the tools the session called from that turn on (only that turn when the toolkit was chosen since), `call_tool` targets included, for both the chat and the raw-prompt loop. Each is *covers*, *short of a tool* (naming the tools), *wider than needed* (a narrower kit offered in the same ask would also have covered) or *ungradable* (calls it can't read back); then a per-kit tally with what on mode would have done. Includes archived sessions and caps the report at 14 days and 500 sessions. Reads `toolkit_suggestions.jsonl` (each ask logs every offered kit's rules, expanded against the called tools here); it never runs the model or changes a session. Local only; `--days` must be a positive whole number.
+- `chi toolkit report [--days N]` — grade toolkit suggestions: the kit on mode would have run (the suggested kit when it would have applied it, else the default; an on-mode line's `did` says what it ran) against the tools the session called from that turn on (only that turn when the toolkit was chosen since), `call_tool` targets included, for both the chat and the raw-prompt loop. Each is *covers*, *short of a tool* (naming the tools), *wider than needed* (a narrower kit offered in the same ask would also have covered) or *ungradable* (calls it can't read back); then a per-kit tally with what on mode would have done. Includes archived sessions and caps the report at 14 days and 500 sessions. Reads `toolkit_suggestions.jsonl` (each ask logs every offered kit's rules, expanded against the called tools here); it never runs the model or changes a session. Local only; `--days` must be a positive whole number.
 
 - `chi bundle try PATH -p TEXT [options]` — install a bundle in a temporary, filtered sandbox, run one real model turn,
   and print its trace (see [Trying a bundle](#trying-a-bundle)).
@@ -233,6 +233,30 @@ Also shipped, not installed: dev (mcp, skills, source-links) (chi bundle install
 done
 ```
 
+- `--to VERSION` installs exactly that gem version instead of checking for the
+  newest release. It must be newer than the running chi; an equal or older
+  version is refused.
+- `--json` writes the component rows as one JSON array on stdout. Each row has
+  `component`, `from`, `to`, `status`, `failed` and `kept` fields; `kept` is an
+  array of edited filenames. Install progress is written to stderr.
+
+- **chi web update notices.** By default, chi web checks RubyGems about 30
+  seconds after it starts and every 24 hours after that. Once a stable release
+  is at least 24 hours old and newer than both the running chi and the newest
+  installed one, the owner's page shows its version and a link to that
+  RubyGems release. When the install is unblocked, **Update** installs that
+  exact release and opens a progress sheet with component results and any
+  edited files kept. A blocked install instead shows the reason and a command
+  to copy. After installation, the notice and the sheet's footer offer
+  **Restart workers** and **Restart chi web**; the sheet reports worker results
+  (a busy worker's refusal says what holds it) and waits for chi web to
+  reconnect, and keeps the other restart in reach. The notice is once per version per browser: a reload or a chi
+  web restart doesn't repeat it. `update.notify: off` disables checking;
+  `update.check_hours` and
+  `update.min_age_hours` tune the interval and release age (see
+  [configuration](configuration.md#all-settings)). If the gem can't be updated
+  in place, the notice gives the blocker and its command instead.
+
 - **The gem.** It asks rubygems.org for the newest samagotchi (5 s timeout)
   and, when that's newer, runs `gem install samagotchi` with the gem command
   of the Ruby chi runs on (the real one, not a mise/rbenv/asdf shim; a chi
@@ -1314,6 +1338,8 @@ CHI_REMOTE=studio chi context push claude-outbox ab12 < answer.json
   studio (http://192.168.1.29:4567): connection refused`, exit 1; with
   `--format json` an `error` object).
 - Plain http, the same as the phone's: use it on your home network.
+- The macOS desktop helper's panel lists and sends to a remote's sessions too: see
+  [Desktop helper: Remote sessions](desktop.md#remote-sessions).
 
 A session there in this terminal (the attached TUI, through that machine's
 chi web; its worker stays there):
@@ -1423,6 +1449,25 @@ chi share revoke --all          # every link to every session
   share cap` raises it. `/stats` shows each participant's spend. Their turns go only to a worker with the review
   boundary: restart an older one. While your turn waits at the step limit (Continue or Stop), their turns wait too
   (still queued, still counted): they run, in order, once you continue, stop or send a turn of your own.
+- **Pair turns: sharing a working session.** The read-only review turn is a review session's (`chi review`). Invite
+  someone to a working session instead and their turns **act** in it with its tools, writes included, under your
+  guardrails: what your rules allow runs, what they ask about comes to you as "Sam's turn asks: approve tool call?"
+  with **Allow once** only (nothing session-wide or repo-wide is approved from their calls), and System 1 never
+  answers for you. A write outside the project always asks you, whatever you approved before. It can't read or
+  write secrets or chi's own files (keys, shell startup files, histories, credential files; by a file tool, a
+  command, a glob or a variable), run chi, leave a command running in the background, read the environment or the
+  keychain, sweep your home with find/tar/cp/grep, delegate, set or cancel reminders, send notes, start or stop
+  background tasks, load tools, forget outputs or write memories, and it asks its questions in its reply, not on a
+  card. Its commands run without your secret-named environment variables (`KEY`, `TOKEN`, `SECRET`, `PASS`,
+  `CREDENTIAL`, `AUTH` in the name) and are killed at the execute limit rather than left running; a command that
+  writes outside the project asks you, as a write does (the tmp dirs aside). A pair turn stops mid-turn once their
+  cap is passed or their link ends. `chi share` and the panel's Invite
+  warn you with what their turns may do and how many tool outputs the history holds, and only a link issued with
+  that warning acts: links from before, or issued while the session's worker predated pair turns (the warning says
+  so), stay read-only until you restart the worker and invite them again. Their messages carry a `pair` badge and no
+  Apply (they acted already). This is an accident guard for a trusted team, not containment: a pair turn can still
+  send what it reads out through `web_fetch` or your MCP tools. A link without `--identity` gets the same access:
+  share it only with people you'd let type in your session.
 - **The participant page.** Their link opens a page of its own (never yours): the session's title and status, who
   else takes part, and the conversation as a participant sees it: every prompt and reply with who wrote it, each
   step's tools as one line (`read docs/plan.md`: the tool and a project file's path, never arguments or output), and

data/docs/configuration.md

@@ -163,7 +163,7 @@ or `chi web` restart.
 | `append_system_prompt` | Worker start for the file list | The config list is not saved in the session file. File text is read when the prompt is built; `/model` rebuilds it, while an already-built prompt is cached. CLI `--append-system-prompt` files are saved in the session. |
 | `toolkit.default`, `toolkit.child` | Session creation | The chosen toolkit is saved; changing the defaults does not move existing sessions. |
 | `toolkit.kits`, `execute.description`, `llm_context.policy` | Worker start | These are held by the engine's toolkit or tool registry. |
-| `toolkit.suggest.mode`, `toolkit.suggest.threshold`, `toolkit.suggest.defer_turns`, `toolkit.suggest.defer_tokens` | Worker start | Suggestion settings are config-only and are resolved when the worker runs its audit. |
+| `toolkit.suggest.mode`, `toolkit.suggest.threshold`, `toolkit.suggest.defer_turns`, `toolkit.suggest.defer_tokens` | Worker start | Suggestion settings are config-only and are resolved when the worker runs its audit or on-mode ask. |
 | `skip_agents_md` | Prompt rebuild | A running engine caches its built prompt; a new worker or `/model` rebuild uses the changed value. |
 | `context.*` except `context.every_seconds`, `llm_context.*` except `llm_context.policy`, `steer.cut_after`, `memory.index_warn_tokens`, `status.line`, `web.participants.*` | Next matching turn, display, poll or write | Readers resolve these settings when they perform that operation. Session-specific LLM context and thinking values remain saved in the session. A participant's grant keeps the expiry and cap it was issued with; `web.participants.*` is what the next invite gets, and the cap and queue of a grant from before caps. |
 | `context.every_seconds` | Next context poll | The poller checks it for each source that has no explicit interval. |
@@ -177,7 +177,8 @@ or `chi web` restart.
 | `log.*` | Process start | Each process holds its configured log sink and level after first use; restart that process. |
 | `history.file` | Next history access | The TUI and web composer resolve its path when they read or append history. |
 | `broadcast.*` | Next `chi broadcast` | Each broadcast invocation reads its targeting and triage settings. |
-| `update.*` | Next `chi update` | The command reads which components to update when it runs. |
+| `update.gem`, `update.bundles`, `update.desktop` | Next `chi update` | The command reads which components to update when it runs. |
+| `update.notify`, `update.check_hours`, `update.min_age_hours` | `chi web` start | The update checker starts with chi web; restart it to apply changes. |
 | `kitty.*`, `tmux.*` | `chi desktop upgrade` or desktop update | These settings are copied into the desktop helper's launch file. |
 | `model.profile`, `reasoning_history` | Not from config.yml | These are CLI/environment settings; `models:` and `hosts:` provide their model- and host-specific forms. |
 
@@ -1432,13 +1433,34 @@ toolkit:
   prompt, without changing its toolkit or delaying the turn. It offers the configured default as the fallback and
   `undecided` for greetings or check-ins. Only a default-origin session with at least two described candidates is
   asked; chosen or inherited toolkits, delegate children, review sessions and participant turns are skipped. After
-  `undecided`, later owner prompts may be asked again within both defer limits. `toolkit.suggest.mode: on` is accepted
-  but behaves exactly like `audit` in this build. The default is `off`. System 1's host, model and timeout come from
-  `guardrails.system_one.*`; the suggestion threshold and defer limits are its own settings below. Suggestions are
+  `undecided`, later owner prompts may be asked again within both defer limits. The default is `off`. System 1's
+  host, model and timeout come from `guardrails.system_one.*`; the suggestion threshold and defer limits are its own
+  settings below. Suggestions are
   kept in `toolkit_suggestions.jsonl`; `chi toolkit report` grades them against the session's tool calls. One ask
   runs at a time (a turn that comes while one still runs goes unasked, with an info line), and a kit that doesn't
   resolve (a missing base, a cycle) is left out of the candidates. A worker that exits waits about a second for a
   running ask, so a one-shot `-p --non-interactive` run may end before its suggestion is logged.
+- **On mode.** `toolkit.suggest.mode: on` asks the same question on the same eligible turns, but the turn waits for
+  the answer before it declares any tool, for at most `guardrails.system_one.timeout_ms` from the ask's start (it
+  starts right after the turn does, so plugin and MCP start-up hide most of it). A described kit picked with
+  confidence at or above `toolkit.suggest.threshold` becomes the session's toolkit, saved with `toolkit_origin:
+  suggested`, and the turn's first request declares it; the notice reads
+  `toolkit: web (suggested, p=0.71) · /toolkit to change`. Anything else (the default, a low-confidence or unknown
+  pick, `undecided`, no answer, a failing System 1, which warns once as `[samagotchi:toolkit]`) keeps the default
+  kit. A Stop during the wait (or before it, even with the answer in) ends the turn before its first request, and
+  nothing switches. After an `undecided`, a later prompt within the defer limits may switch the session; that notice
+  says `from this turn`, and that request re-reads the whole prompt (system prompt, tools and conversation, which
+  the defer limits keep small) without `/toolkit`'s cache confirmation. `/toolkit` or `ctx.use_toolkit` marks the
+  toolkit chosen, and nothing is suggested after that; a `/toolkit` sent during a turn runs after it and replaces
+  that turn's suggestion. When System 1's host is the model's own local server (the same `hosts:` name or server
+  root, as audit checks), on mode asks only on a session's first turn, never on the deferred path, and sends no
+  warm-up (one info line). Otherwise an idle worker for an eligible session sends one warm-up ask with the real
+  question and a stand-in prompt so the server has its prefix cached; its answer is dropped and never logged, and
+  the first real ask stops a warm-up still running. Each answered ask's line in `toolkit_suggestions.jsonl` adds
+  `did`: `suggested`, `default`, `defer`, `chosen` (the toolkit was no longer the default), `unavailable` (the
+  picked kit was gone), `timeout` or `canceled` (written when the late answer arrives; a Stop after a timeout
+  doesn't cut it), or `failed` (the turn failed or the switch couldn't be saved); `chi toolkit report` grades
+  on-mode lines by what they did.
 - **Tool-index groups.** `groups:` selects source groups by name or glob (`chrome`, `db*`; any case, `{a,b}` braces,
   as the guardrails rules' `models:`); for the MCP bundle each group is a server. Anything but a name or a list (a
   map such as `{chrome: true}`) refuses every new session on that kit or on a kit built on it, on every surface (chi,
@@ -2003,7 +2025,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `context.peer_turns` | `3` | yes | Wake turns in a row a peer agent's answers may start (a peer bundle's outbox source, such as `codex-outbox`), with no message typed in the web or a TUI in between (`chi send` doesn't count); within `session.max_wakes`. Then answers wait as notes, and the UIs hear it once. An answer whose summary ends its verdicts with `VERDICT OK` wakes once to close the round, counted toward `session.max_wakes` only. `0`: a peer source wakes like any other. See [Waking](context.md#waking). |
 | `toolkit.default` | `full` | | The toolkit a new session is stored on: the tools its prompts declare (`full`, `lean`, `child`, one of `toolkit.kits` or a bundle's). `chi --toolkit` picks one per session. See "Toolkits". |
 | `toolkit.child` | `full` | | A delegate child's toolkit, unless its `delegate` call names one (`toolkit:`). See "Toolkits". |
-| `toolkit.suggest.mode` | `off` | | `audit` asks System 1 for a toolkit suggestion without changing the session; `on` currently behaves the same as `audit`. The System 1 host, model and timeout come from `guardrails.system_one.*`. config.yml only. |
+| `toolkit.suggest.mode` | `off` | | `audit` asks System 1 for a toolkit suggestion without changing the session; `on` waits for it (up to `guardrails.system_one.timeout_ms`) on an eligible turn and starts the session on a confidently suggested kit (Toolkits, On mode). The System 1 host, model and timeout come from `guardrails.system_one.*`. config.yml only. |
 | `toolkit.suggest.threshold` | `0.5` | | Minimum confidence for a non-default toolkit suggestion. config.yml only. |
 | `toolkit.suggest.defer_turns` | `3` | | Maximum owner-prompt number for another ask after `undecided` (the owner's own prompts: not steers, notes, reminders or `!` command output). config.yml only. |
 | `toolkit.suggest.defer_tokens` | `5000` | | Maximum estimated conversation size for another ask after `undecided` (characters / 4). config.yml only. |
@@ -2028,6 +2050,9 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |
 | `update.bundles` | `true` | | `false`: `chi update` leaves the shipped bundles to `chi bundle upgrade` (`--no-bundles`). |
 | `update.desktop` | `true` | | `false`: `chi update` leaves the desktop helper alone (`--no-desktop`). |
+| `update.notify` | `on` | | `on`: chi web checks RubyGems once a day and shows aged stable releases newer than both this chi and the newest installed chi; `off`: no thread or network check. |
+| `update.check_hours` | `24` | | Hours between RubyGems checks (at least 1). The first check starts about 30 seconds after chi web starts. |
+| `update.min_age_hours` | `24` | | A release must be this old before chi web offers it; `0` disables the age delay. |
 | `kitty.listen_on` | none | | The desktop helper's kitty socket, copied from `kitty.conf`; unset = no kitty targets. See "Desktop helper: agents in kitty". |
 | `kitty.binary` | `/Applications/kitty.app/Contents/MacOS/kitty` | | The kitty the helper runs `kitty @` with. |
 | `kitty.agents` | `claude\|codex\|gemini\|aider\|opencode\|cursor-agent\|amp\|goose` | | Foreground programs whose kitty windows the helper lists, `\|`-separated (a YAML list works too); `*` lists every window. |

data/docs/desktop.md

@@ -41,7 +41,7 @@ alias as the model it names).
 
 ### Everyone it concerns
 
-The second row, **Everyone it concerns** (⌘B), shares a note with every session it may concern instead of the ones
+The second row, **Everyone it concerns (this Mac)** (⌘B), shares a note with every session it may concern instead of the ones
 you pick: ⌘⏎ (the **Broadcast** button) runs [`chi broadcast`](broadcast.md) with the line, then the text, on stdin.
 chi picks the sessions (a shared ticket, PR or link, else a small triage model), so the preselected session doesn't
 count: the row is ticked alone, like the new row. Write it the way you'd tell a colleague: a first line such as
@@ -51,6 +51,8 @@ count: the row is ticked alone, like the new row. Write it the way you'd tell a
   skipped 2 · 1 unchecked: triage deadline`), and **stays open**: Esc closes. Which sessions got it and why:
   `chi broadcast log` in a terminal.
 - A broadcast is a text note: ⏎ and images beep. The source field and Send are hidden (its source is `broadcast`).
+- It reaches this Mac's sessions only (`chi broadcast` runs on this machine only), never a
+  [remote's](#remote-sessions).
 - It may take `broadcast.triage_deadline` (20 s) and 10 s more before the helper stops it ("the note may be partly
   delivered"). The helper reads that from its launch file: after changing the deadline, run `chi update` (or
   `chi desktop upgrade`).
@@ -106,6 +108,46 @@ thumbnails sit under the message line, 48 px high, the file name as a tooltip; h
   the panel closes; files from Finder are sent as they are, never touched. A send with images may take up to 30 s
   (converting, a worker starting) before the panel gives up.
 
+## Remote sessions
+
+The panel also lists the sessions of the other machines `chi remote add` keeps (see
+[Remote sessions](cli.md#remote-sessions)), say the Studio's from a laptop: select text or take a screenshot here,
+and it lands in a session running there.
+
+- **Which:** every remote in `chi remote ls` that has a token, asked at each open (a remote you don't want in the
+  panel: `chi remote rm` it). No `chi update` or `chi desktop upgrade` after adding one.
+- **Where:** after this Mac's rows, one section per remote under an **on studio** divider: its live sessions, then up
+  to 3 recent ones, as for this Mac. Each row carries a grey **studio** tag and its whole folder path (that machine's
+  home may differ from this one's). ⌘1…⌘9 number this Mac's rows first, then the remotes' in order; past nine, a row
+  is clicked.
+- **Not twice:** a session shows once, where it is listed first (this Mac, then the remotes in `chi remote ls` order),
+  so two remotes for the same Studio (its LAN address and its ts.net name), or a remote that is this Mac, don't
+  list or send to it twice.
+- **Wrong machine:** both machines likely have the same paths. While a remote's row is ticked the message line's hint
+  ends in **→ studio**, and **→ studio** shows beside Send (it stays there while you type). The last choice is
+  preselected while it is still live, a remote's row too; the "only one live session" rule picks this Mac's only,
+  never a remote's. A remote that answers after this Mac's list never changes what is ticked: it is preselected only
+  when nothing is (so a remembered remote row is ticked when the remote answers first, or when this Mac has live
+  sessions but none was remembered).
+- **Keys:** ⏎ and ⌘⏎ work as for this Mac's sessions (`chi --remote studio send …`, `chi --remote studio note …`;
+  a note to a stopped session there waits for its next start). Images go along (`--image`: chi uploads them). With
+  rows of several machines ticked, the helper runs one call per machine at once and shows one line: `sent · studio:
+  sent`. ⌥⏎ (paste) beeps on a remote's row as on this Mac's.
+- **Down or refused:** this Mac's rows show as soon as they are in; each remote's fill in as it answers. A remote's
+  two lists run at once and get 4 s together: one that doesn't answer shows **studio: no answer within 4 s** under
+  its divider, one that chi gives up on by itself (connection refused, the token refused) the first line of chi's
+  error. The previous open's rows for it are never reused: a stale row could send to a stopped worker.
+- **New session there:** a remote with a session has its own new row under its divider, **New session on studio in
+  proj**: the folder is that remote's most recently updated session's (live first, then recent), whole and not
+  checked on this Mac. A remote with no session has no new row (never a guess at its home). It is ticked alone like
+  this Mac's new row (ticking it clears the sessions, and the reverse), is never preselected and has no ⌘ number (⌘0
+  stays this Mac's). ⏎ runs `chi --remote studio send --new --dir <that folder>` with the message and images, and
+  shows `studio: started 1a2b3c4d…` for 3 s. It starts on the remote's default model, never `--model`: its hint
+  says **remote default**, and ⌘M or a click on it beeps with "Model choice is for this Mac's sessions" (`chi models`
+  answers for this Mac's hosts).
+- **What stays on this Mac:** the model chooser, the **Everyone it concerns** row (`chi broadcast` is local only)
+  and the agents in kitty and tmux.
+
 ## Agents in kitty and tmux
 
 The panel can also send to agent CLIs (claude, codex, gemini, aider, …) running in
@@ -276,8 +318,14 @@ The helper uses only these commands, so it could ship on its own later:
   (`delivered N · skipped M…`); exit 0 when it ran, 1 when refused or a delivery failed.
 - `chi self --model` → the model a new session starts on (the panel's hint).
 - `chi models --format json` → the models the hosts offer (the new-session model picker).
-
-Each call is stopped after 10 s, a send with images after 30 s, a broadcast after the launch file's
+- `chi remote ls --format json` → `[{name, url, token}]` (never the token itself): the remotes whose sessions the
+  panel lists. A name goes on only when it has a token and passes chi's own rule (letters, digits, `_`, `-`, not
+  starting with `-`). An older chi without `chi remote` lists none.
+- `chi --remote NAME sessions list …`, `chi --remote NAME send …` and `chi --remote NAME note …`: the same calls on a
+  remote's sessions. `CHI_REMOTE` is taken out of the helper's environment, so this Mac's calls never go remote.
+
+Each call is stopped after 10 s, a remote's two lists after 4 s, a send of text to a remote after 15 s (waking a
+stopped worker there), a send with images after 30 s, a broadcast after the launch file's
 `broadcast_timeout` (`broadcast.triage_deadline` + 10 s; 30 s when it has none). A stopped `chi note` or `chi
 broadcast` says the note may be partly delivered.
 

data/docs/guardrails.md

@@ -315,8 +315,11 @@ ordinary sessions don't get it. Like the rules it reads command text: a
 
 ## A participant's review boundary
 
-Built in, for a [participant's](internals/participants.md#turns) turns only (a
-turn whose author is `p:<id>`), in every mode (also with
+Built in, for a [participant's](internals/participants.md#turns) turns in a
+**review session** only (a turn whose author is `p:<id>`, in a session with a
+`review:` key: `ParticipantMode.of` is `:review`; a working session's
+participant turns get the [pair boundary](#a-participants-pair-boundary)
+instead), in every mode (also with
 `guardrails.enabled: false`) and without the guardrails bundle:
 `Guardrails::ReviewBoundary`, rule `review-boundary`, source `core`. It comes
 right after the load-failure check (rules that don't load deny every call) and before the hooks' asks, the
@@ -359,6 +362,96 @@ config can't widen the boundary. Hooks still run on a participant's turn, with
 the owner's power ([hooks](hooks.md#participants-turns)); a hook that rewrites a
 call is checked on the call it leaves.
 
+## A participant's pair boundary
+
+A participant's turn in a **working session** acts with the session's tools
+under the owner's guardrails, as the owner's own turns do: the rules, the
+protected paths and every approval the owner already granted apply, and an ask
+goes to the owner. It is a pair turn only when all three hold
+(`ParticipantMode.for_turn`, decided once at the turn's start:
+`GuardrailWiring#turn_mode`): the session has no `review:` key, its worker
+names the `pair_turns` feature, and the participant's grant was issued with
+`mode: pair`, which chi share and the web's Invite stamp only when the warning
+they showed said their turns act. A grant from before, or one issued while an
+older worker held the session, keeps review turns until it is invited again.
+
+`Guardrails::PairBoundary` (rule `pair-boundary`, source `core`) sits in the
+review boundary's seat in `GuardrailWiring#checks`, in every mode (also with
+`guardrails.enabled: false`), and **denies, never asks**, each with its own
+message:
+
+- secrets, read or written: the review boundary's denylist (chi's state and
+  config dirs, so `grants.json`, the web token and every `participants.json`;
+  `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config/gh`, `~/.config/fish`,
+  `~/.config/git`, `~/Library/LaunchAgents`, `~/.local/bin`; the home's shell
+  startup files, histories, `.gitconfig`, `.netrc`, `.npmrc`, `.pypirc`, `.claude.json`;
+  the project's secret files, any config under `.git`) on every file tool's
+  path (`read`, `write`, `edit`, a plugin's `targets:` paths) and on the paths
+  a command names (`execute`, and any call whose targets carry a command),
+  each word resolved as `touches: chi_dirs` resolves it; a glob that matches a
+  secret or whose fixed part leads into a denied folder (`~/.ss?/id_*`,
+  `~/.config/*/config.yml`, `.en?`), a `$var` word whose fixed part does
+  (`~/.ss${d}h`), and a text match for the rest;
+- sweeping a folder that holds secrets: `find`, `tar`, `cp`, `rsync`, `scp`,
+  `zip`, `ditto`, `grep`/`rg`/`ag` and the like given home or any folder above
+  a denied one;
+- the environment and the keychain: `env` or `printenv` alone, `set`,
+  `export`, `declare` or `typeset` that list, `launchctl getenv`, `ps e`,
+  `security`, `/proc/*/environ`. On top of it, a pair turn's `execute` runs
+  without every variable whose name matches `KEY|TOKEN|SECRET|PASS|CREDENTIAL|AUTH`
+  (`PairBoundary::SECRET_ENV_NAME`, case-insensitive), and a command still
+  running at the limit is killed, never handed over as a background task;
+- git settings that make git run a command (`core.hooksPath`,
+  `core.fsmonitor`, `core.sshCommand`, `core.pager`, `core.editor`, a `!`
+  alias) by `git config` or `git -c`, and `git config --global`/`--system`;
+- running chi, by any wrapper (`bin/chi`, `bundle exec chi`, `ruby … bin/chi`,
+  `env … chi`, `watch`, `npx`, `sh -c 'chi …'`, `$(chi …)`), in an assignment's
+  value or an alias, a function, after `-exec`/`-c`/`-e`, but `chi --version` and
+  `chi --help`: its commands act in the owner's name (shares, caps, sends,
+  answers, sessions);
+- leaving something running: `&` at a command's end, `nohup`, `setsid`,
+  `disown`, `screen -d…`, `tmux new -d`;
+- owner-voiced tools, which act in the owner's name beyond the turn:
+  `delegate` and any `delegate_*` tool, `register_reminder`,
+  `cancel_reminder`, `send_note`, `forget_outputs`, `task_create`,
+  `task_stop`, `find_tools` (it loads tools into the session), and
+  `memory_write` (a memory reaches the owner's later sessions);
+- `ask_user_question`, with the advice to ask in the reply: nobody on the
+  participant's side answers a card.
+
+A script a command hands on is read too (`Guardrails::PairCommand`): one a
+shell runs (`sh -c`, `eval`, a heredoc or here-string) as a command of its
+own, one another interpreter runs (`ruby -e`, `python - <<EOF`) by its text
+(chi, secrets, the environment, detaching). A heredoc written as data (`cat`,
+`tee`, `git commit -F -`) is not looked into: where it goes is checked. A
+command the checks can't read is refused, never let through on a text match.
+
+And it **asks the owner** before a `write` or `edit` outside the session's
+project root, and before a command that writes there (a redirection's target,
+`tee`'s files, a `cp`/`mv`/`ln`/`install`/`rsync`/`ditto` destination, or a
+target it can't resolve), every time: the ask is fresh (`Verdict#fresh_ask`: no
+stored approval answers it, and no rule lowers it), so it comes even in auto
+mode. The tmp dirs (`Dir.tmpdir`, `$TMPDIR`, `/tmp`, `/private/tmp`) and
+`/dev/null` neither ask nor deny.
+
+A participant's ask names them on the owner's card ("Sam's turn asks: approve
+tool call?", `approval.author`/`author_name`, `approval.asked_by`, the same
+line in the plain question: `Approval::ASKED_BY`) and offers **Allow once**
+only: no session, repo or rule approval is made from a participant's call.
+System 1 never judges it, and `chi guardrails replay` skips it. A pair turn
+stops before its next generation once the participant passed their spending
+cap or their link was revoked or expired
+([participants](internals/participants.md#limits-and-the-cap)).
+
+The trust model is a team's (everyone invited is trusted): the boundary is an
+**accident guard** for secrets and the owner's voice, not containment of a
+hostile participant; a review session is. A pair turn can still reach, through
+the owner's rules: `web_fetch` (an open egress path: what the turn can read it
+can send out in a URL), plugin and MCP tools, `memory_read` and `context_read`,
+`list_sessions` (the owner's other sessions' titles), and anything a script
+does that the command checks don't read (a script file's body, an interpreter's
+`-e` code). Share a working session only with people you would let type in it.
+
 ## Rules in config.yml
 
 ```yaml
@@ -666,14 +759,16 @@ a body that isn't JSON, a question with no answer, a request longer than
 `timeout_ms`. A nil means "ask the user", which is what the caller would
 have done anyway.
 
-Toolkit suggestions are a separate audit use of System 1. When
-`toolkit.suggest.mode` is `audit` (or `on`, which is audit-only in this
-build), the engine asks a `choice` question from a background thread after
-the turn starts. This uses the same configured host, model and timeout, but
-is gated by `toolkit.suggest.mode`, not `guardrails.system_one.mode`, and it
-never changes the session's toolkit. Its audit records use the `toolkit` tag
-and are written to `toolkit_suggestions.jsonl` beside the guardrail logs.
-To avoid competing with the session's model, it skips (one info line) when
+Toolkit suggestions are a second use of System 1. When
+`toolkit.suggest.mode` is `audit` or `on`, the engine asks a `choice`
+question from a background thread after the turn starts. This uses the same
+configured host, model and timeout, but is gated by `toolkit.suggest.mode`,
+not `guardrails.system_one.mode`. Audit never changes the session's toolkit;
+on mode's turn waits for the answer (at most `timeout_ms`, cut by a Stop)
+and may start the session on the suggested kit (configuration.md, Toolkits).
+Its warnings use the `toolkit` tag and its records are written to
+`toolkit_suggestions.jsonl` beside the guardrail logs. To avoid competing
+with the session's model, audit skips (one info line) when
 the System 1 host is the model's local host: the same `hosts:` name, or
 another entry for the same server root (scheme, host and port). There is no
 reliable single-slot signal, so this host-identity check is the available
@@ -697,8 +792,8 @@ user's **earlier asks they answered** (`SystemOne::Similar`) — this rule in
 this repository first, then this rule anywhere, then any answered ask, ranked
 by how many words the logged call shares with this one, ties going to the
 newest. Reading the log is best-effort, so a log that cannot be read simply
-offers no examples. A participant's review turn is never judged: there is no
-user there to ask. The judgment runs before the card appears, so an ask is
+offers no examples. A participant's turn (review or pair) is never judged:
+there is no user there to ask, and its asks go to the owner. The judgment runs before the card appears, so an ask is
 slower by up to `timeout_ms` (2000 ms by default).
 
 Each judgment is a line in `judgments.jsonl`, beside `approvals.json` in
@@ -985,9 +1080,11 @@ send; [internals/participants.md](internals/participants.md#apply)). A quote
 lowers the risk, it doesn't remove it: your line still asks the model to act
 on what it quotes, with your tools, so read the quote before you send it.
 
-Within its own turn a participant's text can't act: the review boundary
-leaves it reads of the project only, and an injection that convinces the
-model still meets the boundary (containment over detection). What it can do
+Within its own turn in a review session a participant's text can't act: the
+review boundary leaves it reads of the project only, and an injection that
+convinces the model still meets the boundary (containment over detection). In
+a working session it acts, by design ([the pair boundary](#a-participants-pair-boundary)):
+invite only people you would let type in your session, under your guardrails. What it can do
 is make the model *say* what the history holds: a review turn's model sees the
 whole conversation, earlier tool outputs included, so start a review in a
 fresh session (or a continue), not on a working session full of outputs. A