samagotchi 0.118.0 → 0.120.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06322a414267628aff61367b71dc4a6ecb76d4789673d594aff987a8da678d94
-  data.tar.gz: 12cc40d770cfd7072ccb1a64543033da5619f19d472ae69e7db880ae9a7f867f
+  metadata.gz: 0b242fb85587a862bad996a05e189367e5a4e1b9d025df7a7d335d60b2184fe4
+  data.tar.gz: 85ababba9d74adb82a892cc96d8e2a9fc430a36caf55e9fa9bf549b0f502d136
 SHA512:
-  metadata.gz: 0db2e221e335c74dcb3770ec17d92a2ded1b4e92589e958e33f95008e0ab5a9e13d72aed2ebb3bc2875fa6800e5cba6e19898b68515fda951a1709b5fc864a09
-  data.tar.gz: 7d8e40e0f7966a75d0914229a6e7a94b626ed9a045451ab65c154eef2eea3a5e8ba81eb20fc90cff703986e063fbfbef55225919a4be47e92b3b6b28ae611bbf
+  metadata.gz: 179d89d141810eccc0038f7eac484775c17cc6b07b80504e4139a6ad0579ebb51fe344619bbb949ad9d5a183c5e82fff90915015915a12bdfac46a5b4589cde2
+  data.tar.gz: faeb2bde8eab54b4c286f596e9e3005678d1a6aeebc4758af00aa33da12e4ec5492627a6edc4b7f19c7343e361b0501e3ad92ef53edcf7684255241904e14006

data/CHANGELOG.md

@@ -7,6 +7,79 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.120.0] - 2026-10-26
+
+### Added
+
+- `chi web --start-dir DIR` and `web.start_dir`: the folder chi web starts in, in place of the one you run it in
+  (`~` and a relative path work; one that isn't a folder stops it, exit 1). Its page opens on that folder's project,
+  and a new session from the all view starts there. A chi web already running in another folder keeps it and the
+  second one says so: restart it to change it.
+- Annotate on the participant page: selecting text in the Plan (the review's files) or the thread offers your
+  `web.annotate_presets` and quotes the selection into the comment box (`From <path>:` / `From <name>'s comment:`),
+  as on your own page.
+- The participant page's comment box is the owner's composer: it grows with the text, its grip resizes or folds it
+  (Annotate and typing open it again), it stays one row on a phone, and ↑/↓ recall the participant's own earlier
+  comments from that browser (kept per review link, never your prompt history). No `/` list, delivery choices or
+  images there yet; every comment is still a queued review turn. Your participant view has no comment box.
+- The participant page shows the participant their own usage in one line under the comment box: what their
+  comments have cost you of their cap (a running turn's too), their queued comments of their queue limit, when their
+  link ends, and the session's model. Never another participant's spend, yours or the session's. It sits on a
+  per-link exposure level (`own`, the only one so far), so a later tier can show more.
+- Review links bound to one account: `chi share ID --name NAME --identity EMAIL` (and the Invite dialog's email field,
+  behind an auth proxy that names the signed-in user: `web.public_url` with `web.proxy.identity_header`, or
+  `chi web --tunnel tailscale`) makes a link that opens only through that proxy, signed in as EMAIL. A forwarded
+  link opens for nobody else, and on the LAN or this machine for nobody. `--identity` without such a proxy is refused
+  (the link could never open), and `chi share` warns when a link could be bound and isn't. `chi share ls` shows
+  `alex@corp · bound`. Through `chi --remote`, `--identity` needs that chi web to be this version or newer (an older
+  one would ignore it and make a link anyone could open).
+- chi web trusts proxy headers (`X-Forwarded-*`, the identity header, the public Host) only from this machine
+  (a loopback peer): the proxy must run where chi web runs. With `web.host: lan` and `web.public_url` together, a LAN
+  device sending those headers is a LAN request, never one through the proxy. An identity header that isn't ASCII is
+  refused.
+- A bound link opened by another account, or not through the proxy, is refused with its own words (401
+  `token_bound`: "this review link is for another account …", on the page too), and the refusal goes into the
+  session's participants audit naming who tried. Its one-time code stays usable: the person it was sent to can still
+  open it. Behind a proxy the audit's new-peer lines are per signed-in identity (every peer there is 127.0.0.1).
+
+### Changed
+
+- chi web's bare page (`/`: the LAN link and its QR code, the Home Screen app) opens on the project chi web starts in,
+  as its printed link already did; outside a repo it shows every session as before. Every project's sessions are now
+  `/?scope=all` (the header's `all`), and `chi web --scope=all` (or a `chi web` run outside a repo) prints that link.
+- A pushed notification opens its session in that session's own project (the all view for a session outside a repo),
+  not the project the app shows. The Home Screen app's notifications and badge still cover every project: on a
+  project's page it tidies them from every session's events, where before a project's page (`?dir=`) left them as
+  they were.
+- The participants' grants store (`web-grants/grants.json`) carries a version: 2 once a grant is bound to an identity.
+  chi keeps a grant's fields it doesn't know when it rewrites the store, and never writes over a store a newer chi
+  wrote (its links still work; invite, cap and revoke say to update chi). A chi from before this one doesn't check.
+
+### Fixed
+
+- chi web's stage: on a phone its height follows the whole bottom dock (an info bar that wraps late after a reload
+  no longer leaves it too tall), and the keyboard opening during a smooth scroll no longer leaves a question card
+  out of sight.
+
+### Security
+
+- A session's worker answers only chi's own clients on its machine: its Bridge makes a random secret, written to the
+  session's `bridge.json` (readable by you only), and refuses every request that doesn't name it (403
+  `bridge_secret`). A proxy or tunnel that forwards every local port, or another account on the machine, reaches the
+  port but no longer a session. **After updating chi, restart chi web, re-attach terminals** (`chi --attach ID`) **and
+  restart older session workers** (`chi sessions restart ID...`): a chi web, attached terminal or session worker from
+  before the update sends no secret, and a worker the new chi starts (a delegate child too) refuses it with a message
+  saying so. Workers started before the update ask for no secret and answer both until they restart.
+
+## [0.119.0] - 2026-10-26
+
+### Added
+
+- claude-peer (0.4.3): `pair --inbox-socket PATH` pairs both ways with chi on
+  another machine through an `ssh -R` forward of Claude's socket
+  ([docs/plugins.md](docs/plugins.md)); docs/cli.md: remote sessions through an
+  SSH tunnel. Update with `chi update`.
+
 ## [0.118.0] - 2026-10-26
 
 ### Changed
@@ -4445,7 +4518,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.118.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.120.0...HEAD
+[0.120.0]: https://github.com/dm1try/samagotchi/compare/v0.119.0...v0.120.0
+[0.119.0]: https://github.com/dm1try/samagotchi/compare/v0.118.0...v0.119.0
 [0.118.0]: https://github.com/dm1try/samagotchi/compare/v0.117.0...v0.118.0
 [0.117.0]: https://github.com/dm1try/samagotchi/compare/v0.116.0...v0.117.0
 [0.116.0]: https://github.com/dm1try/samagotchi/compare/v0.115.0...v0.116.0

data/bin/chi

@@ -134,6 +134,10 @@ if options[:tunnel] && !web
   warn "Error: --tunnel goes with chi web (chi web --tunnel tailscale)"
   exit 2
 end
+if options[:start_dir] && !web
+  warn "Error: --start-dir goes with chi web (chi web --start-dir DIR)"
+  exit 2
+end
 if options[:sets] && web
   warn "Error: --set is a new session's (chi --set, chi send --new --set), not chi web's"
   exit 2
@@ -225,7 +229,8 @@ if options[:web]
                                       markdown: markdown, view: view, new_token: options[:new_token], tunnel: options[:tunnel],
                                       working_set: Samagotchi::Config.get("web.working_set"),
                                       annotate_presets: Samagotchi::Config.get("web.annotate_presets"),
-                                      editor: Samagotchi::Config.get("web.editor"))
+                                      editor: Samagotchi::Config.get("web.editor"),
+                                      start_dir: options[:start_dir] || Samagotchi::Config.get("web.start_dir"))
 end
 
 # --resume and --attach take a unique id prefix too, like git.

data/docs/architecture.md

@@ -152,7 +152,7 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 | Core | `Samagotchi::Engine` | System prompt, memory injection, tool declarations, session lifecycle, the model↔tool loop (`run_turn`). No terminal coupling. |
 | 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`, no auth, localhost-only). |
+| 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 but this machine's needs the access token (`App#token_gate`: the `chi_token` cookie or `Authorization: Bearer`; [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 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`). |
 
@@ -390,8 +390,27 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   worker only through `chi web`. A request carrying any trace a proxy adds (`ProxyTrace`: `X-Forwarded-*`,
   `Forwarded`, `X-Real-IP`, `X-Auth-Request-*`, `Cf-*`…, underscore twins too) is `403 proxied`
   (`Bridge#proxied_request?`): an auth proxy that forwards every local port and adds such a header doesn't reach a
-  worker. A heuristic: a forward that adds none still does, until Bridges have a secret (shared-sessions P6).
-  `bridge.json` is 0600.
+  worker.
+- **The secret.** Every request, on every route (the stream, the reads such as `state` and `stats`, the writes, and
+  an unknown path), names the Bridge's secret in `X-Chi-Bridge`; one without it, or with another one, is
+  `403 bridge_secret` with one message (`BridgeSecret::REFUSED`: restart chi web, re-attach terminals and restart
+  older session workers), after the browser and proxy checks and before any route (`Bridge#secret_ok?`,
+  `OpenSSL.secure_compare`). No route is left open: what the reads show is the session itself. Only a request that
+  got past it counts as client activity, so a refused one (an older chi web's polls) never holds the idle exit. Each Bridge makes its own (`SecureRandom.hex(32)`, 64 hex
+  characters) when it starts and writes it to `bridge.json`, which is 0600 from the moment it exists
+  (`AtomicFile` creates the temporary file with that mode, then renames it), so only this machine's user can read
+  it: a forward that adds no proxy header, or another local account, reaches the port but not a session. Clients get
+  it only from the sidecar: `BridgeClient.discover`/`.wait_for`/`.for_sidecar` take the port and the secret from the
+  same read (chi web makes its client from the sidecar for every request, the attached terminal again on a
+  `worker_changed`), so a respawned worker's new one is used and nothing passes a port by hand. A worker from before
+  the secret writes none and asks for none; a chi web or attached terminal from before it sends none, so a worker
+  the newer chi started refuses it until it is restarted. A client tells that refusal from a route's own 403
+  (`BridgeClient::Response#secret_refused?`) and shows the one message: chi web's relays answer 502 `bridge_secret`,
+  `chi answer` and a parent's approval relay say it instead of "refused", and an event stream ends with reason
+  `bridge_secret` once rediscovery finds no newer worker (the attached terminal's closing line), never retrying in
+  silence; chi web's stream proxy passes no refusal on as frames. The secret is never logged (a refusal logs
+  `secret_refused` with the path, at most once a minute), never in an event, a reply, `/api/info` or a session
+  file, and `WorkerSidecar`, `BridgeClient` and `Bridge` leave it out of `#inspect`.
 
 The metrics in `/state`, `/snapshot`, `/stats` and the SSE `snapshot`/`reset` frames
 (`SessionMetrics#snapshot`) carry the session's totals and only the recent timing records: the
@@ -472,7 +491,7 @@ Every route goes through `Bridge#dispatch`: an id other than the bridge's own se
 `handler_failed`) rather than dropping the connection.
 
 The per-session port is OS-assigned (bound to `0`) and published to a `bridge.json` sidecar
-for client discovery. `chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
+for client discovery, with the Bridge's secret (see above). `chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
 (503 `not_live` when the worker is not running; full history of any session is served by
 `GET /api/sessions/:id/output`), as a byte pipe for the owner: `App#proxy_stream_body` gives `ProxyStreamBody` the
 request's frame filter (`App#stream_filter`: nil for the owner; for a participant, and the owner's participant view
@@ -493,7 +512,18 @@ in RubyGems' specification dirs, or a checkout's `version.rb` on disk; looked at
 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`.
+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.
+
+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
+`/` the start folder's project when that folder is in a repo (`App#index_data_attributes` writes
+`data-scope-dir`, which the page reads when the URL has no `?dir`), else every session. The page never
+redirects, so the `?token=` trade's 303, a link code's `#code=` and the Home Screen app's `start_url` `/`
+all land on the start project; a push opens its session's own project (`/?dir=<root>#/s/<id>`, or
+`/?scope=all#/s/<id>` outside a repo). `?dir=` beats `?scope=all`. A session created
+without a folder starts in the start folder.
 Files stay the source of truth and workers don't know the hub. Its watcher is a 1 s tick that
 stats the sessions dir (every session writer goes tmp + rename, which bumps the dir's mtime) and
 each `<id>/` folder (recap.json, bridge.json, the stopped and archived markers), re-parsing only the files whose mtime or size

data/docs/cli.md

@@ -11,8 +11,9 @@
 - `chi scratch [options]` — a one-time session in the plain in-process REPL, in this folder, that leaves nothing behind (see [Scratch sessions](#scratch-sessions))
 - `chi --attach <session-id>` — attach the terminal to a session's worker (e.g. one started from the Web UI), waking one if it has exited
 - A session id can be shortened to any unique prefix (like git): `chi --attach 2ea8`. `--resume`, `--attach`, `sessions stop`, `sessions archive` and `sessions delete` take one; an ambiguous prefix lists the sessions it matches.
-- `chi web [--port 4567] [--open] [--scope=all]` — start the Web UI (single localhost port session control plane) on this git project's sessions (`--scope=all`, or a folder in no repo: every session); if a chi web already runs on the port, print (with `--open`, open) its page for this folder and exit. Something else on the port (an older chi web too) exits 1 with "port N is in use"
+- `chi web [--port 4567] [--open] [--scope=all] [--start-dir DIR]` — start the Web UI (single localhost port session control plane) on this git project's sessions (`--scope=all`, or a folder in no repo: `/?scope=all`, every session); if a chi web already runs on the port, print (with `--open`, open) its page for this folder and exit. Something else on the port (an older chi web too) exits 1 with "port N is in use"
 - `chi web --web-host lan` — the Web UI on your home network too, for your phone: a link with an access token and its QR code (see [chi web on your phone](#chi-web-on-your-phone)); `chi web --new-token` replaces the token
+- `chi web --start-dir DIR` (config `web.start_dir`) — the folder chi web starts in, in place of the one you run it in (`~` and a relative path work; chi web never changes its own folder): its page opens on that folder's project (the printed link, a bare `/`, the LAN link and its QR code, the Home Screen app), and a new session from the all view starts there; `/?scope=all` (the header's `all`) is every project. One that isn't a folder exits 1; `--start-dir` without `web` exits 2. A chi web already running in another folder keeps it (the second one says so: restart it to change it)
 - `chi web --tunnel tailscale` — the Web UI over https on your tailnet, for your phone anywhere: Tailscale Serve (never Funnel) on this machine's `<machine>.<tailnet>.ts.net` name for this run, the owner your Tailscale login, turned off on exit (see [Tailscale Serve](configuration.md#tailscale-serve-your-tailnet)); `--tunnel` without `web` exits 2
 - `chi web push ls [--format json]`, `chi web push rm ID`, `chi web push test [ID]` — the phones chi web pushes to (see [Phone notifications](configuration.md#phone-notifications-web-push)): list them (short id, label, origin, added, last delivery, done turns, last error; `stale` for one made on another public URL than chi web's now: never sent to), remove one, or send a test notification to ID or to every device not stale. chi web need not run; nothing printed holds a device's push address or keys. A usage error exits 2; a store others can read, a corrupt one, an unknown device or a failed test push exit 1. This machine only: `chi --remote X web push` exits 2
 - `chi web --web-markdown` — opt in to sanitized Markdown rendering for completed assistant messages, the stage's asking text and a resolved question card's reply
@@ -26,7 +27,7 @@
 - `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 [--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 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 --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))
@@ -238,7 +239,12 @@ done
   hands over to the new chi, which does the rest and prints the table. Old
   versions stay installed: running workers and an old `chi web` still load
   files from them, so a `gem cleanup` while they run breaks them (a
-  `LoadError`, missing web assets); restart them first. Offline, the row says
+  `LoadError`, missing web assets); restart them first. A chi web, an
+  attached terminal or a session worker started before the update may not
+  reach a worker the new chi starts (403 `bridge_secret`: its Bridge asks for
+  a secret they don't send; an older worker's delegate child is one): restart
+  chi web, re-attach, and restart the older workers (`chi sessions restart
+  ID...`, as the `workers` row says). Offline, the row says
   "couldn't check" and the rest still runs; a failed install fails the row
   and the rest runs on the current version. Under Bundler (`bundle exec`)
   the row says `bundle update samagotchi` instead.
@@ -1164,6 +1170,12 @@ On a touch screen (a phone, a tablet) the bar sits just above the composer
 instead of next to the selection, where the system's own Copy menu and the
 selection handles would cover it; several pills wrap to a second row.
 
+A review's participants get the same on their page (a `chi share` / `chi
+review` link): selecting text in the Plan or the thread quotes it into
+their comment box, labelled `From docs/plan.md:` or `From Sam's comment:`,
+with the same presets. Not in the owner's participant view, and no plugin
+pills there (a review turn refuses `/` lines).
+
 The list is `web.annotate_presets`, `|`-separated (at most five; a preset
 can't contain `|`; a YAML list works too):
 
@@ -1200,7 +1212,10 @@ Plain http: the link and your traffic can be read by anyone on this Wi-Fi.
 
 Scan the QR code with the phone's camera. The page trades the token in the
 link for a cookie (kept 400 days) and drops it from the address, so a
-bookmark or a home-screen icon keeps working across restarts. A home-screen
+bookmark or a home-screen icon keeps working across restarts. It opens on
+the project chi web starts in (`--start-dir DIR` or `web.start_dir` picks
+another; outside a repo it shows every session); the header's `all` shows
+every project's. A home-screen
 web app on iOS has cookies of its own: if it opens on "needs chi web's
 access token", paste the token there (the part of the link after
 `token=`), or open the link once in it.
@@ -1336,6 +1351,36 @@ chi --remote studio --dir /Users/me/app -p "hi"        # a new session there (--
   has installed (`chi --remote studio sessions restart ab12`), this terminal
   older than studio (`chi update` here).
 
+#### Through an SSH tunnel
+
+When that machine's chi web is only reachable over SSH — behind a sign-in proxy
+(`chi --remote` through one isn't supported yet), or bound to 127.0.0.1 —
+forward its port and add it as a remote like any other:
+
+```sh
+ssh -N -L 14567:127.0.0.1:4567 studio          # the host's web.port, 4567 by default
+chi remote add work http://127.0.0.1:14567 --token-file work-token
+# work-token: the host's $XDG_STATE_HOME/samagotchi/web-token
+chi --remote work sessions list
+```
+
+- Pick a local port other than 14567 when this machine runs its own chi web.
+- Forward only chi web's port, never a worker's: a session's Bridge answers
+  only chi's own clients on its machine (they read its secret from the
+  session's folder), so a forwarded worker port is of no use.
+- Without `web.public_url` there, a request that arrives through the tunnel
+  looks local and needs no token, so any process here reaching the forwarded
+  port acts as you there. With it set, every request needs the token, which
+  `chi --remote` sends as Bearer.
+- `-L` binds 127.0.0.1 unless you write `-g` or `0.0.0.0:`: don't.
+- Attaching works through the tunnel too (`chi --remote work --attach ab12`),
+  plain http, no proxy.
+
+SSH can forward a Unix socket as well, which is how claude-peer's pairing makes
+a Claude session on this laptop reachable from chi on that machine
+(`pair --inbox-socket <path>`): see [plugins.md](plugins.md), "chi on another
+machine".
+
 How it works inside (`SessionAccess`, chi web's routes, where each check runs):
 [internals/remote-sessions.md](internals/remote-sessions.md).
 
@@ -1374,8 +1419,9 @@ chi share revoke --all          # every link to every 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
-  the reply streaming in while a turn runs. A "Comment or ask" box sends their comment; their queued comments show
-  with **Take back**; "waiting for the owner" shows while you answer a question or an approval of the turn; a refused
+  the reply streaming in while a turn runs. A "Comment or ask" box sends their comment (your composer's box, with its
+  grip to resize or fold it and ↑/↓ over their own earlier comments from that browser; no `/` list, no images yet);
+  their queued comments show with **Take back**; "waiting for the owner" shows while you answer a question or an approval of the turn; a refused
   comment (a `!` or `/` line, too many waiting, their cap reached) says why. On a phone it is the thread first with
   the box pinned, tool lines folded. They never see tool output or arguments, thinking, approvals or questions,
   memories, context notes, plugin and delegate input, cards, command output, the working set, cost, timing or host
@@ -1404,6 +1450,14 @@ chi share revoke --all          # every link to every session
   `https://<public url>/#code=…`; with `chi web --tunnel tailscale` too (its `ts.net` name, which web.json records
   while that chi web answers on its port: a chi web on another port takes web.json over, and the link falls back to
   127.0.0.1). A tunnel link opens only on a device on your tailnet; the grant still decides.
+- **A link for one account.** Behind an auth proxy that names the signed-in user (`web.public_url` with
+  `web.proxy.identity_header`, or `chi web --tunnel tailscale`), `--identity EMAIL` binds the link to that account:
+  it opens only through the proxy, signed in as EMAIL. A forwarded link opened by anyone else says "This review link
+  is for another account …", and its one-time code still works for EMAIL. `chi share` says `· bound to EMAIL`, `chi
+  share ls` `alex@corp · bound`, and the panel's Invite has an email field there. Without such a proxy `--identity`
+  is refused (the link could never open); with one, an unbound invite gets a warning line. Through `chi --remote`
+  it needs that chi web to have bound links (this version or newer), else it is refused before anything is issued.
+  See [configuration.md](configuration.md#inviting-colleagues).
 - The owner's own token and the `chi web --new-token` rotation are separate: rotating it ends no participant's link.
 - **In the attached terminal.** A participant's message reads `Alex ▸ review> is step 3 right?`, the name in that
   participant's own colour (queued, running, and the last exchange when you join); yours stay as they were. A line

data/docs/configuration.md

@@ -1608,7 +1608,11 @@ web:
 
 Experimental. `chi web` binds 127.0.0.1 only; to use it from elsewhere over https, put it behind a proxy that does TLS
 and, usually, a sign-in (oauth2-proxy, nginx `auth_request`, Caddy `forward_auth`, Cloudflare Access, Tailscale
-Serve; a work pod forwarding `https://<port>.<pod>.<domain>` through oauth2-proxy) and tell chi web its public URL:
+Serve; a work pod forwarding `https://<port>.<pod>.<domain>` through oauth2-proxy) and tell chi web its public URL.
+The proxy must run **on the same machine** as chi web: only a request from a loopback peer (127.0.0.0/8, ::1) counts
+as one through the proxy, with its identity header. A proxy on another host, reaching chi web on its LAN address
+(`web.host: lan`), isn't supported: its requests are LAN requests (the LAN token; a link bound to an account refused),
+since any LAN device could send the same headers.
 
 ```yaml
 web:
@@ -1649,20 +1653,20 @@ What changes once `web.public_url` is set:
   to the proxy, but it outlives the sign-in's redirects: the sign-in page sits at that URL (its scripts can read it)
   and it stays in the browser's history, which is why it holds a code that works once. The page trades the code for
   the cookie (`POST /api/token`) and drops it from the URL; a page that already has a session asks first, since the
-  trade replaces it. A code presented with the wrong identity is used up and gives nothing, so whoever already holds
-  a link can spend it (`chi web` again, or a new invite, makes another). The 401 page's paste box posts the token in
+  trade replaces it. An owner's code (or an unbound participant's) presented with the wrong identity is used up and
+  gives nothing, so whoever already holds a link can spend it (`chi web` again, or a new invite, makes another); a
+  link bound to one account ([Inviting colleagues](#inviting-colleagues)) is refused to anyone else and keeps its code. The 401 page's paste box posts the token in
   the request's body, never in the URL.
 - When the proxy's sign-in or chi's token ends, the page says so: it reloads once (the proxy's sign-in brings you
   back), and within a minute of that shows "Signed out … Reload" instead of a list that quietly stopped updating. Its
   API calls ask for JSON, so oauth2-proxy answers an ended sign-in with 401 instead of a redirect.
-- A session's Bridge (its worker's own port, unauthenticated) refuses a request that carries a proxy header such as
-  `X-Forwarded-For` or `Forwarded` (403 `proxied`). That is a heuristic, not a lock: a forward that adds no such header
-  (nginx's `proxy_pass` with its defaults, a plain TCP forward) still reaches a worker, as the owner.
+- A session's Bridge (its worker's own port) answers only a request that names its secret, which only chi's own
+  clients on this machine read (from the worker's 0600 `bridge.json`): a proxy or tunnel that forwards every local
+  port reaches the port but gets 403. It also refuses a request that carries a proxy header such as
+  `X-Forwarded-For` or `Forwarded` (403 `proxied`).
 - `chi --remote` to a chi web behind a sign-in proxy isn't supported yet.
-
-> **Warning.** Until Bridges get a secret of their own (planned), don't run chi web behind a proxy or tunnel that can
-> reach any local port, such as a pod forwarding every `https://<port>.<pod>…`, unless it adds `X-Forwarded-For` or
-> `Forwarded` to every request; and never one that also lets other people through its sign-in.
+  SSH to that machine works instead: forward its port and add it as a remote
+  ([Through an SSH tunnel](cli.md#through-an-ssh-tunnel)).
 
 Which header to trust: only one the proxy **sets** on every signed-in request **and replaces** when a client sends
 it. Check before setting `identity_header`: run an echo on a free port behind the same proxy (`python3 -c` with
@@ -1683,6 +1687,33 @@ one.
 
 Keep the state dir (`web-token`, the grants) out of any folder others can read, such as a team's shared folder.
 
+### Inviting colleagues
+
+Behind a proxy whose sign-in lets colleagues in (a work pod behind Okta and oauth2-proxy, a tailnet you share), give
+each reviewer a link bound to their account:
+
+```sh
+chi share 3f9a1c2e --name Alex --identity alex@corp.example
+# p_7c01d2aa  Alex (human, reviewer) · session 3f9a1c2e · expires … · cap $2.00 · bound to alex@corp.example
+# https://4567.pod.example.com/#code=chc_…&s=3f9a1c2e-…
+```
+
+- It needs `web.proxy.identity_header` (or `chi web --tunnel tailscale`): the link opens only through the proxy,
+  signed in as that email (any case). Opened by someone else (forwarded, pasted in the wrong chat), on the LAN or on
+  this machine, it says "This review link is for another account …", and its one-time code stays: Alex can still open
+  it. The refusal is in the session's participants audit with the identity that tried. Without an identity header
+  `--identity` is refused: the link could never open.
+- Run only chi 0.109 or newer on the same state dir: an older chi rewriting the grants store drops the binding and
+  makes every bound link open for anyone the proxy lets in.
+- An unbound link there opens for anyone the proxy lets in who has it; `chi share` warns when you make one. The web's
+  Invite has an email field behind such a proxy (the name defaults to the email's first part).
+- The identity is what the trusted header carries: the work email through Okta, the Tailscale login (`alex@github`)
+  through Tailscale Serve. Bind to the one your proxy sends. A tagged Tailscale device has no user login, so a bound
+  link refuses it.
+- The header is the proxy's word only for requests from this machine (the proxy is local; a LAN device's copy is
+  ignored): any program on this machine that reaches chi web's port directly can send it too. On a machine or pod only you use, that is you already; on a host
+  other users share, a bound link's identity isn't a boundary against them.
+
 ### Tailscale Serve (your tailnet)
 
 chi web on your phone away from the home Wi-Fi: [Tailscale](https://tailscale.com) Serve gives this Mac an https
@@ -1796,6 +1827,9 @@ What it needs:
 
 Turning it on, on the phone: open the `Proxied:` link in Safari → Share → **Add to Home Screen** → open the **Chi**
 app → tap the **bell** at the top → turn on **This device** in the sheet → Allow. A test notification arrives at once.
+The app opens on the project chi web starts in (`web.start_dir`; the header's `all` shows every project), but its
+notifications are every project's: opening it closes the ones whose question or card is no longer open and sets its
+badge for every project, whichever project the page shows.
 In a browser tab the bell stays the tab's own notifications (while the tab is in the background), as before.
 
 **The devices** (the bell's sheet in the app; a bottom sheet on the phone): this device first, with its switch (off
@@ -1807,6 +1841,8 @@ are never sent to; `chi web push rm ID` removes them. From the Mac: `chi web pus
 shows a recent delivery (Apple keeps accepting pushes for it): if one stops getting notifications, switch it off and on
 there; the new subscription replaces the dead one.
 
+- **What a tap opens**: the session, in its own project's view (the all view for a session in no repo), whichever
+  project the app was showing; an open app window moves there.
 - **What is sent**: the session's name and the reason ("needs approval", "needs an answer", "hit its step limit",
   "needs you", "turn failed", "done in N s"), never the question or the command, as the tab's notification on the
   Mac. The session's name shows on the lock screen and the Watch.
@@ -1968,6 +2004,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `web.working_set` | `true` | yes | The stage view's working set: the files, memories and URLs a turn brought into the model's context, in a rail in the stage, a footprint line under each finished turn and a `set N` chip in place of the mem chip; `false` brings the mem chip back. `?working_set=1` or `?working_set=0` on the page URL overrides it for that page load; the turn view ignores it. See [CLI: the working set](cli.md#the-working-set). |
 | `web.annotate_presets` | `Agreed\|Could you please elaborate?` | yes | Quick replies next to Annotate in `chi web`, `\|`-separated (a YAML list works too); `""` in the file or on the CLI leaves only Annotate (an empty env value means the default). See [CLI](cli.md#web-annotate-presets). |
 | `web.editor` | `vscode` | yes | What a file ref in `chi web` (a file tool row's title, a diff line) opens, for a viewer on this machine: a preset (`vscode`, `vscode-insiders`, `cursor`, `zed`) or a URL template with `{path}` and an optional `{line}`; `none` turns refs off. See [Opening files from chi web](#opening-files-from-chi-web). |
+| `web.start_dir` | the folder `chi web` runs in | | The folder `chi web` starts in (`chi web --start-dir DIR` for one run): its page (the printed link, a bare `/`, the LAN link and QR code, the Home Screen app) opens on that folder's project, outside a repo on every session, and a new session from the all view starts there; `/?scope=all` is every project. `~` and a relative path work; one that isn't a folder stops `chi web` from starting. `chi web` never changes its own folder. See [CLI](cli.md). |
 | `web.participants.expires` | `7d` | | How long a participant's link lasts unless `chi share --expires` says otherwise: `Nh` or `Nd`, 1h to 30d. See [participants](internals/participants.md). |
 | `web.participants.cap` | `2.0` | | What a participant's turns, and the side calls they cause, may cost you in dollars unless `chi share --cap` says otherwise ($0 to $1000); at the cap their next comment is refused (429 `cap_reached`) and you get a notice. `chi share cap ID P DOLLARS` changes one grant's. |
 | `web.participants.queue` | `3` | | How many of a participant's turns may wait behind their running one (0 to 20); one more is refused (429 `too_many_turns`). |