samagotchi 0.108.0 → 0.110.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f63eb88d80157a6b77f733031284c1a4e376528356f8d099ffe356b4cd7e6c1
-  data.tar.gz: eab92f98b12468b5c882e5ee80524fdf151a1b479fd232ea54f8318bf952c2e3
+  metadata.gz: '097197f78e75225202f6e84b40f7449f063416402e3ac1820015a824c82fc64b'
+  data.tar.gz: 7ac596f01db65fc81761acccfade8c99c5543b963539083652cbb3022923ae13
 SHA512:
-  metadata.gz: c5df88fe266c32153072be45890e6c12f54bcab0492d367cabc0f0066e6dec41bfc8d54e800f08c610979c3ec66131f7082dbc8691ea3854498ce603f553ffec
-  data.tar.gz: e324e458bc5801eec9bc0f170ab5b839fbc4633ca33ce026566cac121deed90b53149a1052a9ec4607f67a7e3d284b4201c08309b5e8eeb1181bd1ff3ec65e31
+  metadata.gz: 3b5aca203f09584369fe954da86514837eabd3addf2e3bc91f3f74ae1202f726b4170c99c1b591a999ffb8c23da7ce3f51d2f746ecc81a84fabef376c238b7fb
+  data.tar.gz: d4df1f1ba87e37f81af6440c55c1aa3d0749c7abc734a53d9ec7356a35e9a513684495feb550138032f67c0e493cdacc97ce69ea29407fa407b1a07d7b22a20d

data/CHANGELOG.md

@@ -8,6 +8,69 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.110.0] - 2026-10-24
+
+### Added
+
+- Experimental: `chi web --tunnel tailscale`: chi web on your phone anywhere on your tailnet over https (Tailscale
+  Serve on this machine's `ts.net` name, never Funnel), with your Tailscale login as the owner (or
+  `web.proxy.owner`), for this run only (nothing written to config.yml). It checks Tailscale, the certificate and
+  what Serve already has on port 443 before it changes anything, adopts a serve left by an earlier run, refuses
+  anything else on 443, prints the owner link's QR code, warns when Tailnet Lock is off, and turns the serve off on
+  exit (only while 443 still serves exactly what it set). The proxied start line (`web.public_url`) also shows its
+  link's QR code at a terminal now. See docs/configuration.md (Tailscale Serve).
+- Sessions record when each message happened: prompts, lines merged into a turn, reminders, notes and the model's
+  replies carry `at` in the session file (never sent to the model); plugins see it in `ctx.messages`.
+- Reminders tell the model the local time they came due (`[SYSTEM: REMINDERS DUE 2026-10-24 14:32 local]`), so it
+  can reason about how long ago something happened.
+- Terminal (attached and the REPL): a dim `── 14:32 · 47 min later ──` divider before what comes after 10 minutes
+  or more of quiet, a `── last activity 14:32 · 47 min ago ──` line when attaching after such a gap, and the recap's
+  time in its head (`recap 14:32>`). See docs/cli.md (Time gaps).
+- Web: a dim `── 14:32 · 47 min later ──` line in the history where 10 minutes or more of quiet passed between
+  turns, notes or reminders (live and after a reload, the participant's review page too), each prompt, answer and
+  note's full time on hover, and the recap's time in its label (`recap · 14:32`).
+
+### Fixed
+
+- `chi send --wait` with no message on a running turn that has no turn id (a session's first prompt, a reminder
+  turn), and a `chi send --wait -m` whose message merged into the running turn, end `canceled` (`worker_stopped`)
+  when that turn's worker dies and the next worker settles it, instead of waiting until `--timeout`.
+- Attached TUI: joining an older session (one with no saved record of the call) shows a call the guardrails denied
+  as `blocked`, not `error`.
+
+Update with `chi update` (the system bundle 0.110.0), then restart `chi web`.
+
+## [0.109.0] - 2026-10-24
+
+### Added
+
+- Experimental: `chi web` behind an auth proxy (oauth2-proxy, nginx `auth_request`, Caddy `forward_auth`, Cloudflare
+  Access, Tailscale Serve, or a plain TLS proxy). `web.public_url` (an https origin) makes every request need the
+  access token, this machine's too; `web.proxy.identity_header` + `web.proxy.owner` also check the signed-in email
+  the proxy sends (owner = that identity AND the token; a repeated, comma, empty or underscore-twin header is
+  refused). Through the proxy the cookie is `__Host-chi_token` (Secure), a `?token=` page isn't traded (the paste box's
+  redirect is absolute from `web.public_url`), links (the start line, the web's and `chi share`'s invites) are `https://…/#code=…` with a
+  one-time code, never a token, and on this machine a request takes the token as `Authorization: Bearer` only. See
+  docs/configuration.md (Behind an auth proxy).
+- Experimental, with `web.public_url`: a link's `#code=` is traded for the cookie by the page (`POST /api/token`;
+  a page that already has a session asks first), and the 401 page's paste box posts the token, never puts it in the
+  URL; the page notices a lost sign-in (the proxy's session or chi's token ended:
+  a 401, a redirect to the sign-in page, the session list's stream giving up) and reloads once, then says "Signed out"
+  with Reload instead of going quietly stale. The page's API calls ask for JSON (`Accept: application/json`).
+
+### Changed
+
+- chi web's HTML answers can't be framed by another page (`X-Frame-Options: DENY`, `frame-ancestors 'none'`), and a
+  frame/embed/object load from another origin is refused (403 `framed`).
+- A session's Bridge refuses any request that came through a proxy (`X-Forwarded-*`, `Forwarded`, `X-Real-IP`,
+  `X-Auth-Request-*` and the like, underscore twins too: 403 `proxied`): an auth proxy that forwards every local port
+  and adds such a header no longer reaches a worker's unauthenticated Bridge (a forward that adds none still does).
+  chi's own clients never send these headers. A worker's `bridge.json` is now 0600.
+- `chi share`'s LAN link names the LAN address the running chi web reports only if it is one of this machine's own
+  addresses; else the link names 127.0.0.1 (whatever answers on chi web's port may be another user's listener).
+
+Update with `chi update` (the system bundle 0.109.0), then restart `chi web`.
+
 ## [0.108.0] - 2026-10-24
 
 ### Added
@@ -4165,7 +4228,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.108.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.110.0...HEAD
+[0.110.0]: https://github.com/dm1try/samagotchi/compare/v0.109.0...v0.110.0
+[0.109.0]: https://github.com/dm1try/samagotchi/compare/v0.108.0...v0.109.0
 [0.108.0]: https://github.com/dm1try/samagotchi/compare/v0.107.0...v0.108.0
 [0.107.0]: https://github.com/dm1try/samagotchi/compare/v0.106.0...v0.107.0
 [0.106.0]: https://github.com/dm1try/samagotchi/compare/v0.105.0...v0.106.0

data/bin/chi

@@ -120,6 +120,10 @@ if options[:new_token] && !web
   warn "Error: --new-token goes with chi web (chi web --new-token)"
   exit 1
 end
+if options[:tunnel] && !web
+  warn "Error: --tunnel goes with chi web (chi web --tunnel tailscale)"
+  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
@@ -208,7 +212,7 @@ if options[:web]
   markdown = Samagotchi::Config.get("web.markdown") if markdown.nil?
   view = Samagotchi::Config.get("web.view")
   exit Samagotchi::Web::Server.launch(port: port, scope: options[:scope] || "project", open_browser: options[:web_open],
-                                      markdown: markdown, view: view, new_token: options[:new_token],
+                                      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"))

data/docs/architecture.md

@@ -153,7 +153,7 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 | UI | `Samagotchi::TerminalUI` | Interactive REPL (Reline), rendering (ANSI, spinner, status line), REPL commands. Delegates all core work to an `Engine`. |
 | Model loops and adapters | `KernelLoop`, `LLM::ChatLoop`, `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | The model↔tool loops and the HTTP adapters they talk through (see "Model loops and adapters"). |
 | Bridge (SSE/HTTP) | `Samagotchi::Bridge`, `SessionManager` | The **single live client transport**: an SSE read stream + HTTP POST turn/cancel/answer surface that attaches to a worker's existing `Engine` via `Engine#subscribe`. Every session worker starts it (bound `127.0.0.1`, no auth, localhost-only). |
-| 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)). 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. `bin/chi web` entrypoint. |
+| Web (Rack) | `Samagotchi::Web::App`, `SessionManager` | Single-port `127.0.0.1:4567` control plane via `rack`+`webrick` (serve `index.html` + `/api/*`). With `web.host: lan` (or one of this machine's IPv4 addresses) the server also listens on that address, where every request 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. `bin/chi web` entrypoint. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File-based `~/.local/state/samagotchi/sessions/<uuid>.json` + sidecar `input/`/`output/`; retention (14d/500) + ordering (`updated_at desc`). |
 
 - `bin/chi` in REPL mode (see `LaunchMode` above) builds `TerminalUI`. `TerminalUI#run` is the single
@@ -387,7 +387,11 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
 - No browser: only chi's own clients talk to a Bridge. A request with an `Origin` header, a `Sec-Fetch-Site`
   other than `none`, or a `Host` that isn't loopback (a DNS-rebound page) is `403 cross_origin`
   (`Bridge#browser_request?`, before any route); there is no CORS and no `OPTIONS` route. The browser reaches a
-  worker only through `chi web`.
+  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.
 
 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
@@ -696,6 +700,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | LLM context strategies | `llm_context_strategy.rb`, `llm_context_view.rb`, `llm_context_stale.rb`, `llm_context_forget.rb` | What a request sends of the history (none, stale, forget) ([internals/llm-context-forget.md](internals/llm-context-forget.md)). |
 | Session chains | `session_continue.rb` (`SessionContinue`), `session_chain.rb` (`SessionChain`) | A session that continues an earlier one. `SessionChain.opener_for` gives the text web `continue →` prefills in the new link: the previous link's own first typed message when that link continues one itself, else nil (the 201's `opener`; not saved) ([sessions.md](sessions.md)). |
 | Review sessions | `review_start.rb` (`ReviewStart`), `session_review.rb` (`SessionReview`, the session's `review` field), `review_command.rb` (`ReviewCommand`, `chi review`), `review_apply.rb` (`ReviewApply`) | A session made to be shared: idle, its subjects project files checked by `Guardrails::ReviewPaths`, a fork of a working session from its recap (`--from`); Apply quotes a participant's review turn into the owner's composer ([sessions.md](sessions.md#review-sessions), [internals/participants.md](internals/participants.md)). |
+| Behind an auth proxy | `web/public_url.rb` (`Web::PublicUrl`: `web.public_url`, `web.proxy.identity_header`, `web.proxy.owner`), `web/proxy_gate.rb` (`Web::ProxyGate`, mixed into App; `RawHeaderNames`, prepended to WEBrick's request by `Web::Server`), `web/link_codes.rb` (`Web::LinkCodes`: the links' one-time codes), `proxy_trace.rb` (`ProxyTrace`), `web/public/token_fragment.js`, `web/public/auth_lost.js`, `web/tunnel.rb` + `web/tunnel/tailscale.rb` (`Web::Tunnel`, `Web::Tunnel::Tailscale`: `chi web --tunnel tailscale`, Tailscale Serve set for one run and the PublicUrl it makes) | Experimental: chi web behind an auth proxy. Every request needs the token; a proxied one's owner also needs the identity header (one clean value under one name); the `__Host-` cookie, an absolute `Location` from the public URL, https links with a one-time code in the fragment; the page's lost-sign-in banner. Bridges refuse proxy traces ([configuration.md](configuration.md#behind-an-auth-proxy)). |
 | Participants | `participants.rb` (`Participants`, the `participants.json` sidecar), `share_command.rb` (`ShareCommand`, `chi share`), `session_participants.rb`, `participants_watch.rb`, `web/grants.rb` (`Web::Grants`), `web/principal.rb` (`Web::Principal`), `web/participant_access.rb` (`Web::ParticipantAccess`: the participant's gate and routes), `web/participants_admin.rb` (`Web::ParticipantsAdmin`: the owner's invite, list, revoke, cap and Apply routes), `web/participant_review.rb` + `web/participant_view.rb` (`Web::ParticipantReview`, `Web::ParticipantView`), `web/participant_stream_filter.rb`, `guardrails/review_boundary.rb` + `guardrails/review_paths.rb` | The people or agents an owner invites to review one session through chi web: their grants and gate, what they read, their read-only review turns ([internals/participants.md](internals/participants.md), [guardrails.md](guardrails.md)). |
 | Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows); `session_metrics/cost.rb` (`SessionMetrics::Cost`): the spend `ctx.cost` reads; `session_metrics/usage.rb` (`SessionMetrics::Usage`): the work `ctx.usage` reads. `session_metrics/side_totals.rb` (`SessionMetrics::SideTotals`) and `side_usage.rb` (`SideUsage`): the side requests' sums, apart from the turns'. |
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |

data/docs/cli.md

@@ -13,6 +13,7 @@
 - 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 --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 --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 --web-markdown` — opt in to sanitized Markdown rendering for completed assistant messages, the stage's asking text and a resolved question card's reply
 - `chi web --web-view turn` — draw turns with the turn view (each turn as one block of steps, the running one at the bottom of the history) instead of the default stage view (the running turn pinned above the composer); `?view=stage|turn` on the page URL overrides it (see [Web views](#web-views))
 - `chi web --no-web-working-set` — turns the stage view's working set off (on by default; `--web-working-set` turns a config's `web.working_set: false` back on): what each turn brought into the model's context, in the stage and under each finished turn; `?working_set=1|0` on the page URL overrides it (see [The working set](#the-working-set))
@@ -1012,6 +1013,16 @@ steps saved before that have none, so they show no thinking. An `edit` or
 made (up to 120 lines or 8 KB), live and after a reload (see
 [Guardrails](guardrails.md#ask) for the diff an approval shows first).
 
+**When things happened**, in both views and on a participant's review page: where 10 minutes or
+more of quiet passed between the end of one activity and the start of the next (a turn, a context
+note, a reminder), the history has one dim centred line, `── 14:32 · 47 min later ──`; the date is
+added when the day changed or the turn wasn't today (`── Sat 24 Oct 09:10 · 13 h later ──`).
+Nothing marks active work: a long turn followed at once by the next has no line. Hovering a prompt,
+an answer, a note or a reminder shows its full local time, and the recap's label says when it was
+written (`recap · 14:32`). The times are the history entries' `at` (see
+[sessions.md](sessions.md)); a session saved before them takes its turns' times from their timing
+records, and shows no hover times.
+
 ### The working set
 
 The stage view shows what a turn brought into the model's context: the files
@@ -1164,6 +1175,9 @@ access token", paste the token there (the part of the link after
   office guest network), and run `chi web --new-token` if a link leaks.
 - On http the browser has no notifications: the bell is hidden on the phone,
   and the tab title still counts what needs you.
+- Off the home Wi-Fi: `chi web --tunnel tailscale` gives chi web an https
+  name on your tailnet (Tailscale Serve) for its run and prints its link's QR
+  code; see [Tailscale Serve](configuration.md#tailscale-serve-your-tailnet).
 
 ### Remote sessions
 
@@ -1332,7 +1346,10 @@ chi share revoke --all          # every link to every session
 - `chi --remote studio share …` invites on studio: the link names studio's LAN address. Locally, the link names
   this machine's running chi web, on the port it listens on (it records it in `$XDG_STATE_HOME/samagotchi/web.json`;
   `web.port` when none answers there); without one on the LAN, chi says the link opens on this machine only (as
-  the participant there too: a participant's link never opens as the owner).
+  the participant there too: a participant's link never opens as the owner). With `web.public_url` the link is
+  `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.
 - 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
@@ -1433,6 +1450,28 @@ working on, what came of it and what is still open, not a turn-by-turn log.
 - It uses the session's own model unless `recap:` names one;
   `recap: false` turns it off. See configuration.md.
 
+## Time gaps (terminal)
+
+Both terminals (attached and the REPL) show when things happened without a
+time on every line:
+
+- A dim divider marks a quiet gap of 10 minutes or more, before what comes
+  next: `── 14:32 · 47 min later ──`, the date added when the day changed
+  (`── Sat 24 Oct 09:10 · 13 h later ──`). The gap runs from the end of the
+  last activity (a turn's end, a reminder, a context note, a recap) to the
+  start of the next (a prompt, yours above its line or another UI's, a
+  reminder turn, a note, a recap), so nothing is marked during a turn or
+  between turns run back to back. A command (`/stats`, `!cmd`) is no
+  activity.
+- Attaching to a session whose last activity was 10 minutes ago or more
+  says when, after the join block: `── last activity 14:32 · 47 min ago ──`
+  (from the newest timed message, else the saved recap's time). With
+  `--resume` the REPL marks the gap before the first prompt instead.
+- A recap names the local time it was written: `recap 14:32>`, `recap 14:32
+  (before the last 2 turns)>`.
+- Only live activity and the join: neither terminal replays the history, so
+  older gaps aren't marked. `--non-interactive` prints none.
+
 ## Tool Activity Log
 
 Samagotchi now prints a concise, human-friendly tool activity log in normal

data/docs/configuration.md

@@ -1591,11 +1591,183 @@ web:
 - Only a viewer on this machine opens the editor: a loopback request, or this machine on its own LAN address
   (`web.host: lan`, the LAN URL or its QR code opened here). A phone gets the targets that need no editor (an
   answer's ref shows its row in the turn; see the refs in [sessions.md](sessions.md)); a row's title stays plain
-  text there. An SSH tunnel or a local reverse proxy (`tailscale serve`) looks like loopback, so a remote viewer
-  behind one gets an editor target that can't open.
+  text there. An SSH tunnel or a local reverse proxy (`tailscale serve`) looks like loopback unless `web.public_url`
+  is set (then a request through it is never this machine's viewer), so without it a remote viewer behind one gets an
+  editor target that can't open.
 - `GET /api/sessions/:id` (and its `?tail=1`) carries `capabilities.editor` (true for such a viewer) and
   `editor_url`, the template (null otherwise).
 
+## Behind an auth proxy
+
+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:
+
+```yaml
+web:
+  public_url: https://4567.pod.example.com     # the https origin people open: no path
+  proxy:
+    identity_header: X-Forwarded-Email         # optional: the header the proxy puts the signed-in email in
+    owner: me@example.com                      # optional, needs identity_header: you, as that header says it
+```
+
+What changes once `web.public_url` is set:
+
+- **Every request needs the access token**, this machine's too (`$XDG_STATE_HOME/samagotchi/web-token`, made at
+  start; `chi web --new-token` replaces it). A proxy that adds no header and rewrites Host (nginx's `proxy_pass` with
+  its defaults) would otherwise look like this machine. On this machine the page opens through the proxy too: a
+  request that didn't come through it takes the token only as `Authorization: Bearer` (no cookie: a cookie for
+  127.0.0.1 would go to every server on any local port; a phone on the LAN, with `web.host: lan`, keeps its LAN link
+  and cookie). chi's own probe of the port (a second `chi web`, `chi share`,
+  `chi update`) sends no token; chi web answers it the few fields it checks. Links and the start line come from this
+  machine's config, never from whatever answers on the port.
+- **A request through the proxy** (it carries `X-Forwarded-For`, `Forwarded`, `X-Real-IP`, a known identity header,
+  or the public Host) is the owner only with the token **and**, when `web.proxy.identity_header` is set, that header
+  being exactly `web.proxy.owner` (any case). A repeated, comma-separated or empty value, or the header sent under a
+  second spelling (`X_Forwarded_Email` next to `X-Forwarded-Email`), is refused (401, the reason in the answer's
+  detail). With `identity_header` unset the token alone decides: that works behind any proxy. `owner` without
+  `identity_header` stops `chi web` from starting.
+- Through the proxy the cookie is `__Host-chi_token` (Secure, Path=/, no Domain: other host names under the domain,
+  such as a pod's other ports `https://<port>.<pod>…`, don't get it; the LAN's `chi_token` is separate). Cookies aren't
+  scoped by port: another server on the **same host name** and a different port does get it, so give chi web a host
+  name of its own, or port 443. Through the proxy a `?token=` page isn't traded (it would ride the sign-in redirect,
+  and a crafted link could swap your session): a link's one-time code and the 401 page's paste box do it, the paste
+  box's redirect going to the public URL (never to a client-sent `X-Forwarded-Host`). The page accepts `POST`s from the public `https://` origin only (a sibling port on the same
+  domain, or `http://`, is refused). No page of chi web's may be framed by another (`X-Frame-Options: DENY`,
+  `frame-ancestors 'none'`, in every mode).
+- Links carry a **one-time code** in the fragment, never a token: `chi web` prints `Proxied: https://…/#code=chc_…`
+  (the owner's: once, within 10 minutes; `chi web` again prints a new one), and a participant's link (`chi share`,
+  the Invite dialog) is `https://<public url>/#code=chc_…&s=ID` (once, until the grant expires). A fragment isn't sent
+  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
+  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.
+- `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.
+
+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
+`http.server`, or any header-echo server), open it signed in, and send your own copies (`curl -H 'X-Forwarded-Email:
+evil@x' -H 'X_Forwarded_Email: evil@x' …` with your sign-in cookie): the header you trust must come back with your
+email only. chi warns once in its log when a proxied request carries a known identity header but not the configured
+one.
+
+| Setup | `identity_header` | Notes |
+|---|---|---|
+| oauth2-proxy (`--pass-user-headers`) | `X-Forwarded-Email` | Replaced, spelling variants dropped; `X-Forwarded-For` always added. **Not** `X-Auth-Request-Email`: oauth2-proxy puts that on its *response*, a client's copy reaches chi untouched. Checked against oauth2-proxy 7.15.5. |
+| nginx `auth_request` + oauth2-proxy (`--set-xauthrequest`) | `X-Auth-Request-Email` | Only as nginx sets it from the auth reply (`auth_request_set $email $upstream_http_x_auth_request_email; proxy_set_header X-Auth-Request-Email $email;`), which replaces a client's copy; nginx drops underscore spellings by default. Checked with nginx 1.27. |
+| Caddy `forward_auth` (`copy_headers X-Auth-Request-Email`) | the copied header | Replaced from the auth reply; Caddy passes an underscore spelling through, which chi refuses. Checked with Caddy 2.8. |
+| Cloudflare Access | `Cf-Access-Authenticated-User-Email` | Not checked yet: verify with an echo. chi trusts the header only; it doesn't validate the `Cf-Access-Jwt-Assertion` token. |
+| Tailscale Serve | `Tailscale-User-Login` | Replaced, not appended (`Tailscale-User-Name`, `X-Forwarded-For`, `X-Forwarded-Host` too); `X-Forwarded-For` = the requesting device's tailnet IP, Host = the public name. Tailnet only. Checked with Tailscale 1.104.2 (macOS). Not checked: Funnel and tagged-device requests; never use Funnel. See [Tailscale Serve](#tailscale-serve-your-tailnet). |
+| Authelia, Authentik (behind nginx, Caddy, Traefik) | `Remote-Email` (Authelia), `X-Authentik-Email` (Authentik) | Not checked yet; only as the front proxy copies it from the auth reply (the nginx and Caddy rows). |
+| A TLS proxy with no sign-in (nginx, Caddy, an SSH tunnel) | leave unset | The token alone decides. |
+
+Keep the state dir (`web-token`, the grants) out of any folder others can read, such as a team's shared folder.
+
+### 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
+name on your tailnet, `https://<machine>.<tailnet>.ts.net`, with a real certificate, and tells chi web who is asking
+(your Tailscale login, next to chi's token). Only devices on your tailnet reach it: with Tailscale off on the phone the
+name doesn't load. By hand, on the Mac that runs chi web (or steps 1–2, then
+[`chi web --tunnel tailscale`](#chi-web---tunnel-tailscale) does 3–5 for one run):
+
+1. Install Tailscale on the Mac and the phone and sign both in with the same login. **Rename the machines first**
+   (admin console → Machines): HTTPS certificates go into the public Certificate Transparency log, so the
+   `<machine>.<tailnet>.ts.net` name is public once a certificate is issued, and a later rename puts a new name there.
+2. Turn on HTTPS certificates (admin console → DNS; they need MagicDNS on).
+3. Serve chi web's port on the tailnet, never on the internet:
+
+   ```sh
+   tailscale serve --bg 4567
+   ```
+
+   On macOS the app's CLI is `/Applications/Tailscale.app/Contents/MacOS/Tailscale` unless you installed `tailscale`
+   on your PATH. `tailscale serve status` shows what it serves; `tailscale serve --https=443 off` turns it off. Turn
+   it off when you stop using it: while it is on, whatever listens on 127.0.0.1:4567 is reachable from your tailnet.
+4. Tell chi web its public name and whose login is the owner (config.yml; `chi web` reads it at start):
+
+   ```yaml
+   web:
+     public_url: https://chi-host.example-tailnet.ts.net
+     proxy:
+       identity_header: Tailscale-User-Login
+       owner: owner@example.com      # your Tailscale login
+   ```
+
+   Your login: `tailscale whois <the phone's 100.x IP>` (the User block), or `tailscale status --json`
+   (`User["<Self.UserID>"].LoginName`), or start without `owner` and read it off the 401 page's detail ("owner token
+   with identity …"). A login made with Sign in with Apple is a private-relay address (`…@privaterelay.appleid.com`):
+   it is stable, use it as it is. Every device signed in with that login (the phone, a laptop, an iPad) is the owner,
+   each with the token too.
+5. `chi web` prints `Proxied: https://chi-host.example-tailnet.ts.net/#code=chc_…`; open that link on the phone (copy,
+   AirDrop or type it). The code works once, within 10 minutes (`chi web` again prints a new one); the phone then
+   keeps the `__Host-chi_token` cookie.
+
+#### `chi web --tunnel tailscale`
+
+Steps 3–5 in one command, after steps 1–2 (Tailscale signed in, HTTPS certificates on):
+
+```sh
+chi web --tunnel tailscale
+```
+
+```
+Chi Web on http://127.0.0.1:4567/ (public: …)
+Proxied: https://chi-host.example-tailnet.ts.net/#code=chc_…   ← opens chi web as you once, within 10 minutes (…)
+         (owner owner@example.com by Tailscale-User-Login, and the token; …)
+         via Tailscale Serve (tailnet only), owner owner@example.com (this machine's Tailscale login)
+Tailnet Lock is off: a device Tailscale's servers add to your tailnet could reach this page; tailscale lock init turns it on (…)
+<the link's QR code>
+```
+
+- It checks before it changes anything: Tailscale is connected, this machine has its `ts.net` name and a certificate
+  for it, and what Serve already has on port 443. Nothing there: it runs
+  `tailscale serve --bg --https=443 http://127.0.0.1:<port>`. Exactly that one handler for this port (a leftover of an
+  earlier run killed hard, or step 3 done by hand): it adopts it. Anything else on 443 (another port, other paths, TCP
+  forwarding, Funnel) is refused and left alone. Serve's other ports are never touched.
+- The owner is `web.proxy.owner` if config.yml has it, else this machine's own Tailscale login (a tagged machine has
+  none: set `web.proxy.owner`). `public_url` and `identity_header` are the tunnel's for this run, never written to
+  config.yml: a `web.public_url` or `web.proxy.identity_header` that says otherwise (in config.yml or the environment)
+  is refused, so a config from step 4 with this machine's name works as it is.
+- On exit (Ctrl-C, a kill, closing the terminal) it runs `tailscale serve --https=443 off`, but only while 443 still
+  serves exactly what it set; if you changed 443 meanwhile it leaves it and says so. Killed hard (`kill -9`, a power
+  loss) the serve stays on: Serve answers 502 for the name while nothing listens on the port, and whatever later
+  listens on 127.0.0.1:<port> is reachable from your tailnet; the next `chi web --tunnel tailscale` adopts it and
+  turns it off on exit, a plain `chi web` doesn't look.
+- A chi web already on the port is refused ("stop that one first"): `--tunnel` starts its own.
+- The `tailscale` it runs: `SAMAGOTCHI_TAILSCALE_CLI` if set, else `tailscale` on PATH, else the macOS app's
+  `/Applications/Tailscale.app/Contents/MacOS/Tailscale`.
+- Tailnet Lock off is a warning line, never a refusal.
+
+- **Never Funnel** (`tailscale funnel`): it puts the name on the public internet. This recipe was checked on the
+  tailnet only; Funnel requests weren't.
+- Recommended: **Tailnet Lock** (`tailscale lock init`, see Tailscale's docs): new devices then need a signature from a
+  device you trust before they join, not only Tailscale's coordination server's say-so. chi web works either way.
+- What Serve sends (checked with Tailscale 1.104.2 on macOS): it **replaces** a client's `Tailscale-User-Login`,
+  `Tailscale-User-Name`, `X-Forwarded-For` and `X-Forwarded-Host` (never appends); `X-Forwarded-For` is the
+  requesting device's tailnet IP, Host the public name, and chi web's peer is 127.0.0.1. A process on this Mac can
+  still reach 127.0.0.1:4567 directly with headers of its own: there the token decides, as with any proxy.
+- While chi web isn't running Serve answers 502 for the name (checked). Not checked yet: requests from a tagged
+  device (expect no user login, so refused with `identity_header` set), and whether the serve stays on across a
+  reboot.
+- A participant's link (`chi share`, the Invite dialog) is a `https://<machine>.<tailnet>.ts.net/…` link too: it opens
+  only on a device on your tailnet (or one you shared this machine with in Tailscale); the grant still decides.
+- Without Serve, a plain tailnet IP (`web.host: 100.x.y.z`) works like the LAN (see
+  [chi web on your phone](cli.md#chi-web-on-your-phone)): token only, plain http in the browser (WireGuard encrypts
+  the path) so no `Secure` cookie and no notifications, and no identity.
+
 ## All settings
 
 Every setting below takes the three forms described in
@@ -1723,6 +1895,9 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `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`). |
+| `web.public_url` | | | Experimental. The https origin people open `chi web` at through an auth proxy (`https://host` or `https://host:port`, no path); set, every request needs the access token, this machine's too, and links use it. A value that isn't an https origin stops `chi web` from starting. See [Behind an auth proxy](#behind-an-auth-proxy). |
+| `web.proxy.identity_header` | | | Experimental. The request header the proxy puts the signed-in user's email in (`X-Forwarded-Email` for oauth2-proxy), checked next to the token: only one the proxy sets *and* replaces. Unset or `none`: the token alone decides. See [Behind an auth proxy](#behind-an-auth-proxy). |
+| `web.proxy.owner` | | | Experimental. Your email as the identity header carries it (any case): a proxied request is the owner only with this identity and the token. Unset: nobody is the owner by identity. Needs `web.proxy.identity_header`. |
 | `history.file` | state dir | | Prompt history path, shared by the TUI and the web composer. |
 | `no_interrupt` | `false` | `--no-interrupt` | Raise the step limit of a turn to 1000 (or `turn.max_iterations`, when larger); a top-level key. |
 | `no_default_input` | `false` | `--no-default-input` | Don't pre-fill `default.input`; a top-level key. |

data/docs/internals/engine.md

@@ -25,12 +25,14 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     # TurnState#begin!(controller:, sink:) (a new CancellationController when none is given),
   │     # a recap in flight invalidated, GuardrailWiring#begin_turn(origin)
   │     # Returns a Turn {session, prompt (nil on a continue), continue, on_event, controller,
-  │     #                 origin, started_at, id (the caller's id:, else a new uuid), resumed, resume_from}
+  │     #                 origin, started_at, id (the caller's id:, else a new uuid), resumed, resume_from,
+  │     #                 wall (MessageTime.now)}
   │
   ├── Client.swap_probe_cancel(turn.controller)   # a Stop cuts this turn's /props probes
   │
   ├── prepare_turn(turn, images)
-  │     # Emits :turn_started {session_id, prompt, turn_id, continue: true (only on a continue),
+  │     # Emits :turn_started {session_id, prompt, turn_id, at (the turn's wall time, Turn#wall: read once,
+  │     #                      the user message's and the reminders' stamp too), continue: true (only on a continue),
   │     #                      resumed: true (only on a step-limit Continue: resumed: given),
   │     #                      images (only when there are any), cut_after (the model's cut wait, s)}
   │     # refresh_profile! (may ask the server's /props once)
@@ -491,8 +493,8 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 
 | Event | When | Payload |
 |---|---|---|
-| `:turn_started` | `prepare_turn` | `{session_id, prompt, turn_id, continue?, resumed?, images?, cut_after}` (`resumed`: a step-limit Continue) |
-| `:reminder_injected` | due reminders went into the turn | `{reminders}` |
+| `:turn_started` | `prepare_turn` | `{session_id, prompt, turn_id, at, continue?, resumed?, images?, cut_after}` (`resumed`: a step-limit Continue; `at`: the turn's wall time, its prompt's stamp) |
+| `:reminder_injected` | due reminders went into the turn | `{reminders, at}` (`at`: the turn's wall time, the reminder message's stamp) |
 | `:context_status` | every request (unless `context.status` is off), the current estimate before it; and outside any turn after `/model` (or when a session is loaded on another model than its last turn ran on), to the observers only (`Engine#announce_switched_context!`) | `{iteration, status, usage, bucket, source}`; the switch's form has no `iteration`: `{usage, bucket, context_window_tokens, context_window_source}`, with `usage.source: "switch"`, and `usage` nil when the new window doesn't resolve (internals/context-telemetry.md) |
 | `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source, price, model_ref}` (`price`: the turn's `ModelPrice#to_h`, nil without one; `model_ref`: the turn's model, asked `host:model`, added by the Engine's stream handler from the model `#generate` resolved after the `before_turn` hooks, so a hook's switch is the one named; native adds `profile`, `profile_source`) |
 | `:generation_chunk` | each streamed chunk | `{iteration, content, text, thinking, payload, tool_call?}` (SSE clients get the Bridge's projection instead: `{iteration, text, thinking, tool_call?, counts?}`, architecture.md) |
@@ -655,6 +657,19 @@ logged). Both are display only: `AnswerDisplay::DISPLAY_ONLY` lists `display`, `
 after_generation), while `KernelLoop#sanitize_history` and `ChatLoop#plain` copy them so the stored conversation keeps
 them across turns. `Web::App#messages_for_display` sends `display_refs` re-validated (`AnswerRefs.for_display`).
 
+History stamps: user prompts, merged input and steers, reminders, context and task notes and the model's replies carry
+`at` (`MessageTime::KEY`, `message_time.rb`: a local-offset ISO time with milliseconds), when the entry happened. A
+turn reads the wall clock once (`Turn#wall`, `MessageTime.now`): `:turn_started`'s `at`, its prompt's and its
+reminders' stamps; `Steer::Merge#messages` stamps a merge at the boundary, `ContextNote.message` a note with its
+`created_at` (else now), `KernelLoop#iterate` / `#cancelled_result` and the chat loop's `Run#with_thinking` /
+`Run#canceled` each reply. Tool results, `!cmd` messages and TurnNote notes carry none. Like `display`, `at` must
+survive the two rebuilds: both model branches of `KernelLoop#sanitize_history` and `ChatLoop#plain` copy it (an
+allow-list that drops a key loses it for good on the next turn; `spec/message_time_history_spec.rb` checks both
+loops). It is display-only and never reaches the wire (prompt-caching.md, rule 7), but it is not in
+`AnswerDisplay::DISPLAY_ONLY`: hooks and `ctx.messages` see it. `:recap_ready` carries the saved recap's
+`created_at` (`Engine#emit_recap(created_at:)`, from `IdleRecap#collect`). The UIs' gap dividers come from
+`MessageTime.gap_line` (10 min, `GAP_SECONDS`).
+
 `:question_asked` (`QuestionAsked`, `question_asked.rb`) fires from the two Engine seams where a question of the
 model's opens, never from `QuestionDesk`: `Engine#request_question` (the kernel's `question_handler`, after
 `AskUserQuestion.validate`; not with `interface == :non_interactive`) and the guardrail wiring's `ask:` lambda

data/docs/internals/participants.md

@@ -7,9 +7,11 @@ limited and capped; and what they **see** (P4a): their page and its reads, all t
 experimental. An agent participant waits on its own turns' replies through the API. The code and docs say
 "participants" and "review", never "shared": `session.shared` already means "attached by default".
 
-Participants are a **LAN** feature for now (`web.host: lan`; a public URL, `web.public_url`, is planned, not a
-config key yet): a loopback peer with no token is
-the owner, and a reverse proxy on the same machine would make every visitor loopback. A participant's token is the
+Participants reach chi web on the **LAN** (`web.host: lan`), or **behind an auth proxy** with `web.public_url`
+(experimental; docs/configuration.md, "Behind an auth proxy"): there every request needs a token, this machine's too,
+and invite links are `https://<public url>/#code=chc_…&s=ID`: a one-time code (`Web::LinkCodes`, until the grant
+expires; the grant's token sealed under the code, so the store keeps no token) that the page trades for the cookie. Without either, a loopback peer with no token is the
+owner, and a reverse proxy on the same machine would make every visitor loopback. A participant's token is the
 participant's wherever it comes from: their link opened on this machine (or on a chi web not on the LAN, whose link
 works on this machine only) is the participant, never the owner.
 
@@ -47,11 +49,24 @@ participant** and **one role**, until it expires or is revoked.
   refused with one message naming the file (`Grants::Corrupt`: `chi share` exits 1, chi web answers 500 with it);
   an archive or delete still goes ahead. Fix the file, or move it aside to end every link.
 - Rotating the owner token (`chi web --new-token`) never touches grants; `chi share revoke --all` ends them all.
+- **Bound grants** (`identity`, an email in lower case; nil for any, and absent from the store then): a bound grant
+  is honoured only on a request through the proxy (`web.public_url`) whose identity header carries that email; on the
+  LAN or this machine it is refused (401). The gate checks it (`participant_principal(identity:, proxied:)`);
+  issuing one (`chi share --identity`, the Invite dialog's email) is shared-sessions P6.
 
 ## The gate
 
 `App#principal_for` resolves every request to a `Web::Principal`:
 
+0. With `web.public_url` (`Web::ProxyGate`; `chi web --tunnel tailscale` sets the same for its run, never in config:
+   public_url = the machine's `ts.net` name, identity_header `Tailscale-User-Login`, owner `web.proxy.owner` else this
+   machine's Tailscale login, `Web::Tunnel::Tailscale`), a **proxied** request (a proxy trace: `X-Forwarded-*`, `Forwarded`,
+   `X-Real-IP`, a known identity header, the configured one, or the public Host) is `#proxied_principal`'s: the owner
+   only with the owner's token **and**, when `web.proxy.identity_header` is set, that header being one clean value
+   (not repeated, no comma, not empty, under one name with no underscore: the raw header names) equal to
+   `web.proxy.owner`; a participant with a live grant (a bound one only for its identity); else 401, its reason in
+   the detail (only the requester's own identity). Unproxied, every request needs a token too (no "loopback is the
+   owner"): rule 3 doesn't apply.
 1. The owner's token (Bearer, then the cookie; `?token=` on the page's trade): the **owner**. Checked first, so the
    owner's requests never touch the grants store (measured: no change to an owner route's time).
 2. A `chp_` token (`Grants.token?`) whose grant is active: a **participant** (`Principal.new(kind: :participant,
@@ -63,7 +78,9 @@ participant** and **one role**, until it expires or is revoked.
    owner." / "This review link expired: ask the session's owner for a new one."), any other **401
    `unauthorized`** as before.
 
-The `?token=` trade sets the `chi_token` cookie to the token that was presented, the owner's or the participant's
+The `?token=` trade (and `POST /api/token`, with a link's one-time `{code}` or the 401 page's pasted `{token}`; with
+`web.public_url` only through the proxy, as a direct request takes Bearer only) sets the `chi_token` cookie (`__Host-chi_token`, Secure, on a proxied request) to the token that was
+presented, the owner's or the participant's
 (one at a time per browser: a participant link opened in the owner's browser replaces the owner's cookie there, and
 makes that browser the participant, on loopback too). A grant's token is traded on any peer; the owner's only where
 the gate asks for it. On a peer the gate doesn't ask, the 401 for a grant's cookie that no longer works clears the
@@ -189,12 +206,13 @@ made by `chi share revoke` in another process; the page then reads a 401 and sho
 D5 (a): prompts and replies with their authors, one-line tool rows, turn boundaries, the queue and waiting states.
 Not tool output or arguments, thinking, approvals' and questions' content, memories (text or names), context notes,
 plugin steers, automatic and delegate input, cards, command output, the working set (the user decided: not), cost,
-timing, host paths or the owner's prompt history. Every read a participant reaches goes through one module,
+timing (durations, records: only the wall time `at` of each prompt, reply and turn start, for the page's gap lines
+and hover times, D6 of the session-time-gaps plan), host paths or the owner's prompt history. Every read a participant reaches goes through one module,
 `Web::ParticipantView` (`lib/samagotchi/web/participant_view.rb`), whose every answer is a new hash built from named
 fields: a field added to an event later reaches nobody until it is named there.
 
 - **Events** (`.event`, the stream). `EVENTS` names the types a participant gets, each rebuilt by its own method:
-  `turn_started` (turn id, the author and name, `mine` for their own, the prompt only when a person sent the turn:
+  `turn_started` (turn id, its wall time `at`, the author and name, `mine` for their own, the prompt only when a person sent the turn:
   `ClientId.human?`, else `automatic`; `continue`), the turn's end (`turn_completed`, `turn_canceled`, `turn_failed`:
   type and turn id), `generation_chunk` (its visible `text` only; a thinking-only chunk is dropped),
   `generation_retrying` (`restarted`), `tool_call_started` (the tool's name, and for a file tool the path relative to
@@ -426,8 +444,10 @@ participant TUI in v1.
 
 ## Invariants
 
-- The owner is the owner's token, or a loopback peer (or a chi web not on the LAN) with no participant token; nothing
-  else. A participant token never widens to the owner, from any peer.
+- The owner is the owner's token, or a loopback peer (or a chi web not on the LAN, and without `web.public_url`) with
+  no participant token; nothing else. Through a proxy the owner is the token and, with an identity header
+  configured, that identity: never the identity alone, never a loopback peer. A participant token never widens to the
+  owner, from any peer.
 - A participant reaches one session, through the `:participant` rows only; another session is a 404.
 - No token is written anywhere: the grants store has digests, the sidecar and the audit trail have neither.
 - Owner sessions are unchanged: no sidecar, no audit file, no key in the session JSON until a grant exists.

data/docs/internals/prompt-caching.md

@@ -219,6 +219,11 @@ is prefilled once. The native and the chat loop use the same plan.
    `CacheConfirm.needed?` asks only for `:full`, `:provider` and `:history`, when the effective level changes and
    the session has a model reply. A new setting with a cost (a `/model` across templates, `/llm-context` turning
    forget on) adds its classifier and goes through the same step.
+7. **No wall-clock time rendered at wire time.** A history entry's `at` (`MessageTime::KEY`, when it happened) is
+   display-only: no wire format reads it, and a guard spec checks that `ChatLoop#wire_messages` and
+   `Prompt.format_with_images` give the same bytes with and without it (`spec/message_time_history_spec.rb`). A
+   time the model should read is baked into the message's content when the message is made (a context note's
+   frame, the reminders' header), so a replay sends the same bytes whatever the time zone or DST.
 
 ## Server-side settings worth knowing
 

data/docs/internals/remote-sessions.md

@@ -189,7 +189,10 @@ with a "Machine-local" comment; the rest branch on `@access.remote?` (`SendComma
 - **The token is the owner.** In LAN mode (`web.host: lan`) every non-loopback request needs the `Web::Token` access
   token, as the `chi_token` cookie or `Authorization: Bearer` (`App#token_gate`). This runs over plain http, which is
   fine on a home LAN, the same as the phone page. A loopback chi web without LAN mode needs no token
-  (`Remotes::Entry#token` is nil, and no header is sent).
+  (`Remotes::Entry#token` is nil, and no header is sent). Behind an auth proxy (`web.public_url`, experimental) every
+  request needs it, loopback too, and a proxied owner also the configured identity header
+  ([configuration.md: Behind an auth proxy](../configuration.md#behind-an-auth-proxy), `Web::ProxyGate`); `chi
+  --remote` through such a proxy isn't supported yet (the CLI can't pass its sign-in, and streams need TLS).
 - **Every request has a principal.** `App#principal_for` resolves who a request is, as a `Web::Principal`
   (`web/principal.rb`): `Principal::OWNER` for a peer the gate doesn't ask (no LAN mode, or a loopback peer) and for
   the access token; a participant for a live grant's `chp_` token; nil (a 401) for anyone else (`token_revoked` /
@@ -205,7 +208,8 @@ with a "Machine-local" comment; the rest branch on `@access.remote?` (`SendComma
 - **The token at rest.** `remotes.yml` is written through `AtomicFile.write(perm: 0o600)`, its read-modify-write (`Remotes.put` / `remove`) under `remotes.yml.lock`. `Entry#inspect` / `#to_s`
   redact the token. `chi remote ls` never prints it (JSON shows `token: true|false`). `HTTPTransport#inspect` and
   `Remote#inspect` show only the label.
-- **The Host check.** `local_host_header?` accepts only the loopback names and the exact LAN IP. `http://studio.local`
+- **The Host check.** `local_host_header?` accepts only the loopback names and the exact LAN IP (and, with
+  `web.public_url`, its host exactly, port included). `http://studio.local`
   gets a 403 `forbidden`, which the client words as "use the LAN IP". The check guards against DNS rebinding.
   `cross_site?` lets CLI clients through because they send no `Origin` or `Sec-Fetch-Site`.
 - **`client_id` only tightens.** `handle_question_answer` forwards `client_id` only when it is `ClientId::CLI_ANSWER`