samagotchi 0.110.0 → 0.111.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '097197f78e75225202f6e84b40f7449f063416402e3ac1820015a824c82fc64b'
-  data.tar.gz: 7ac596f01db65fc81761acccfade8c99c5543b963539083652cbb3022923ae13
+  metadata.gz: c3030ebe01072de864d730b27cfc709368d48948260f07b3e37fa83f8ba4b87a
+  data.tar.gz: 38f33d3c633d5467c8200817c2a12fc5fd0e287cf87cbd5233f0486326280eed
 SHA512:
-  metadata.gz: 3b5aca203f09584369fe954da86514837eabd3addf2e3bc91f3f74ae1202f726b4170c99c1b591a999ffb8c23da7ce3f51d2f746ecc81a84fabef376c238b7fb
-  data.tar.gz: d4df1f1ba87e37f81af6440c55c1aa3d0749c7abc734a53d9ec7356a35e9a513684495feb550138032f67c0e493cdacc97ce69ea29407fa407b1a07d7b22a20d
+  metadata.gz: af19fcb8e29f712f43098d68d466bb8e68bdfc3b87177d7a2f99e73a2b609a535322ab181cacae03d7cf00e774a2f28933ff5b3ba30446d3e4112724f213bf6f
+  data.tar.gz: 72fb51ec5f3d216a36e27a040643517104fc8988f8010b6bdc70ac4f3b2bd2db281a4cc629a54b75e88dfbe46b78d02014bfc65142f39e40e6952ab13c919f7f

data/CHANGELOG.md

@@ -8,6 +8,28 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.111.0] - 2026-10-24
+
+### Added
+
+- chi web: push notifications to a phone's Home Screen app (approvals and questions) over an https public URL
+  (`chi web --tunnel tailscale`): add chi web to the Home Screen, tap the bell. An answered question's notification goes
+  when the app opens (every push shows one: iOS drops an app that pushes silently). New settings `web.push.enabled` (default on) and `web.push.contact`. See
+  docs/configuration.md (Phone notifications).
+
+### Fixed
+
+- `chi send --new --wait` now knows the id of the turn the new session's first prompt runs, so a `--timeout` or
+  Ctrl-C there says `still running: chi send --wait --turn <T> <ID>` instead of the vaguer "waits again", and
+  `chi send --wait --turn <T> <ID>` gets that turn's reply (`--format json` carries its `turn_id`). chi web's
+  create answers the first turn's id as `first_turn_id`, so the same holds for `chi --remote … send --new --wait`.
+- Web: a session's stream dropping mid-turn (a phone briefly offline) no longer shows "canceled (worker exited)"
+  while the worker runs on; the page re-reads first and shows it only when no worker took the turn. A re-read that
+  fails (the network still down) is retried with a backoff, and a stage that lets go of a turn clears its status row
+  and chip, so it no longer reads "thinking · step 1" for a turn it stopped following.
+
+Update with `chi update` (the system bundle 0.111.0), then restart `chi web`.
+
 ## [0.110.0] - 2026-10-24
 
 ### Added
@@ -4228,7 +4250,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.110.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.111.0...HEAD
+[0.111.0]: https://github.com/dm1try/samagotchi/compare/v0.110.0...v0.111.0
 [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

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)). 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. |
+| 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`). |
 
 - `bin/chi` in REPL mode (see `LaunchMode` above) builds `TerminalUI`. `TerminalUI#run` is the single
@@ -530,7 +530,7 @@ model: [internals/remote-sessions.md](internals/remote-sessions.md).
 |---|---|---|---|---|
 | `GET /api/sessions/resolve?id=` | owner | an id or a unique prefix | 200 `{id}` | 404 `not_found`; 400 `ambiguous_id` with `ids` |
 | `GET /api/sessions/summaries` | owner | `dir` (a folder: its project; none: every project), `cwd`, `live=1`, `archived=1`, `tests=0`, `sort`, `order`, `limit` | 200: the rows `chi sessions list` prints (`SessionManager.session_summaries`: `status`, `live`, `busy`, `owner`, `recap`, `ctx_pct`, `waiting`, `waiting_id`, `title`, `preview`, …) | 400 `invalid_dir`, `invalid_cwd` |
-| `POST /api/sessions` (more fields) | owner | `toolkit`, `tools`, `no_tools`, `parent_answers`; `client_id` (`cli:send`/`cli:answer`: the first line is checked as chi send checks it); `check_vision: true` (images follow) | 201 adds `model_warning` and `parent_answers_warning` (a level looser than config.yml's, capped) | 400 `invalid_toolkit`, `invalid_parent_answers`, `invalid_continues` (beside `continues`); 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
+| `POST /api/sessions` (more fields) | owner | `toolkit`, `tools`, `no_tools`, `parent_answers`; `client_id` (`cli:send`/`cli:answer`: the first line is checked as chi send checks it); `check_vision: true` (images follow) | 201 adds `model_warning`, `parent_answers_warning` (a level looser than config.yml's, capped) and `first_turn_id` (the id the prompt it starts with gets for its turn; null for an `idle` create) | 400 `invalid_toolkit`, `invalid_parent_answers`, `invalid_continues` (beside `continues`); 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
 | `POST /api/sessions/:id/turn` (more fields) | owner | `client_id` as above; `check_vision: true` with `images` | as before | 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
 | `POST /api/sessions/:id/wait/prepare` | owner | `question_id` (absent: the pending one; `null`: none), `turn`, `created`, `busy` (+ `queue`) | 200 `{session_id, cursor, baseline: {messages, question_id, last_turn}, own_turn, known_turn, running, live, settled, last_turn_id}` (`WaitStart`) | 409 `busy`, `waiting` (`SendCommand::Busy`'s words, and its fields: `question`, `parent_strategy`) |
 | `POST /api/sessions/:id/wait` | owner | `cursor`, `baseline`, `turn`, `queued`, `ended_before`, `owner_grace`, `timeout` (capped at 30 s) | 200: `ReplyWait::Result`'s fields (`status`: `done`, `waiting_for_answer`, `no_reply`, `error`, `stopped`, `worker_gone`, or `timeout`: ask again; `text`, `file`, `question` as `PendingQuestion#to_file`, `outcome`, `limit`, `error_kind`, `retryable`, `cancel_reason`, `stopped_by`, `kept_steps`, `turn_id`, `origin`; never the session) and `parent_strategy` `{name, allowed, origin}` (`ParentReport.strategy_for`, this server's config.yml) | 400 `invalid_wait`; 503 `server_stopping` |
@@ -610,9 +610,10 @@ so later requests and resumed sessions pair them, and their reasoning (`thinking
 turn goes on from the run it resumes, `reasoning_since:`). It has its own system prompt
 (no raw-prompt tool declarations; the tools go as JSON schemas).
 
-`Engine#build_stream_event_handler` is the one seam both loops' streams pass
-through: with a `:generation_progress` hook registered it feeds a
-`Hooks::StreamWatch` each chunk's thinking and text after the UIs had it. A
+`Engine#build_stream_event_handler` (`EventFanout`'s, which the Engine forwards
+to) is the one seam both loops' streams pass through: with a
+`:generation_progress` hook registered it feeds a `Hooks::StreamWatch` each
+chunk's thinking and text after the UIs had it. A
 hook's `stop_generation` cancels the generation's own controller (a child of
 the turn's, `CancellationController#generation`), and each loop takes the cut
 as an empty answer and asks again.
@@ -700,6 +701,8 @@ 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)). |
+| chi web's routes | `web/app.rb` (`Web::App`: the gate, `ROUTES`, the shared helpers), `web/message_display.rb` (`Web::MessageDisplay`: saved messages and cards as display items, `POST /api/render`), `web/session_show.rb` (`Web::SessionShow`: `GET /api/sessions/:id` with its `cards`, `tail` and `timing` re-reads, `GET …/output`, the timing payload), `web/session_create.rb` (`Web::SessionCreate`: `POST /api/sessions`, a continue, a review fork), `web/session_control.rb` (`Web::SessionControl`: answer, command, turn and images, cancel, stop, restart, archive, delete), `web/push_routes.rb` (`Web::PushRoutes`: `/api/push`, its subscriptions and test) | The handlers `App`'s `ROUTES` name, in the file that holds their kind; each mixin is included in `App` and reads its helpers and ivars, so `app.send(:handle_show, …)` and the specs that stub `App` methods work as before. |
+| Web Push | `web/push.rb` (`Web::Push`: `Runtime`, `preflight!`, the `web.push.*` settings), `web/push/crypto.rb` (`Push::Crypto`: RFC 8291 aes128gcm, RFC 8292 VAPID), `web/push/store.rb` (`Push::Store`, `Store::Sub`: `web-push/vapid.pem`, `subscriptions.json`), `web/push/client.rb` (`Push::Client`, `Client::Result`), `web/push/attention.rb` (`Push::Attention`: notify.js's rules in Ruby), `web/push/notifier.rb` (`Push::Notifier`, a hub subscriber with a sender thread), `web/push_routes.rb` (`Web::PushRoutes`), `web/private_files.rb` (`Web::PrivateFiles`, shared with the grants), `public/sw.js`, `public/push.js`, `public/manifest.webmanifest` | chi web pushes approvals and questions to the owner's Home Screen app over an https public URL: the Notifier turns the hub's new approvals and questions into show pushes after a hold (each carries the keys still open, and the badge; no close push: every push shows a notification); the bell (`notifications.js`) subscribes the device, and the service worker and the page close the answered ones. See [internals/web-push.md](internals/web-push.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'. |

data/docs/cli.md

@@ -1178,6 +1178,9 @@ access token", paste the token there (the part of the link after
 - 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).
+- Notifications on the phone, also while chi web isn't open there: on the tunnel's https link, Add to Home Screen,
+  open the Chi app and tap its bell; approvals and questions then push to the phone (see
+  [Phone notifications](configuration.md#phone-notifications-web-push)).
 
 ### Remote sessions
 

data/docs/configuration.md

@@ -1768,6 +1768,47 @@ Tailnet Lock is off: a device Tailscale's servers add to your tailnet could reac
   [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.
 
+### Phone notifications (Web Push)
+
+chi web as an app on your iPhone's Home Screen that buzzes (the Watch too) when a session waits on an **approval** or
+a **question**, also while the app is closed. A tap opens that session; once it is answered anywhere (the Mac, the
+phone, `chi answer`), its notification goes when you open the app (or swipe it away). Every
+push shows a notification: iOS turns off an app's pushes after a few that show none.
+
+What it needs:
+
+- chi web on an **https** public URL: `chi web --tunnel tailscale` ([above](#chi-web---tunnel-tailscale)) or a
+  `web.public_url`. On the LAN's plain http there is no push (no secure context: the bell is hidden); use the tunnel.
+- iOS 16.4 or later, and chi web **added to the Home Screen**: iOS gives push to a Home Screen app only.
+- No Apple account or registration: chi web signs its pushes with a key of its own (VAPID).
+
+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 → Allow. A test notification arrives at once. Tap the
+bell again to turn it off on that phone. In a browser tab the bell stays the tab's own notifications (while the tab
+is in the background), as before.
+
+- **What is sent**: the session's name and the reason ("needs approval", "needs an answer"), 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.
+- **What Apple sees**: the push is end-to-end encrypted to the phone; Apple's push service sees that this machine
+  pushes to that device, and when. A subscription holds no device name and no personal data (an opaque address on
+  `web.push.apple.com` and two keys); chi names it itself ("iPhone · 2026-10-24", from the User-Agent's device class
+  and the date).
+- **When**: an approval or a question that is still open 3 s after it was asked (3.5 s for a delegated child's
+  approval, which its parent may relay instead); one push per question; a step-limit question, a failed or a long
+  turn don't push yet. A push arrives even while you look at the page (the phone can't tell chi web that it is in
+  front yet).
+- **The files**: `$XDG_STATE_HOME/samagotchi/web-push/` (next to `web-token`): `vapid.pem` (chi web's key) and
+  `subscriptions.json` (the devices), 0600 in a 0700 folder; chi web refuses to start when others can read them.
+  Subscriptions belong to the public URL they were made on: after renaming the machine or the tailnet, turn the bell
+  on again on the phone (the old ones are never sent to).
+- `web.push.enabled: false` turns it off; `web.push.contact` (a `mailto:` address or an `https://` URL; default:
+  the public URL) is the contact the push services see in chi web's key. A value that is neither stops `chi web`
+  (Apple refuses it); a `[chi web] the push service refused chi's VAPID token` line means the contact or the key was
+  refused, and pushes stop until chi web restarts.
+- The app keeps its own cookie (iOS copies Safari's when it is added, 400 days): `chi web --new-token` logs it out
+  (it shows the "needs chi web's access token" page; paste the token there). Pushes keep coming meanwhile.
+- chi web not running: no pushes (Serve answers 502; a tap couldn't open the page anyway).
+
 ## All settings
 
 Every setting below takes the three forms described in
@@ -1898,6 +1939,8 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `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`. |
+| `web.push.enabled` | `true` | | Push notifications to a phone's Home Screen app (approvals and questions) when the bell there is on. Does anything only with an https public URL (`web.public_url`, or `chi web --tunnel tailscale`'s) and once a device subscribed; `false` turns the pushes and the routes off. See [Phone notifications](#phone-notifications-web-push). |
+| `web.push.contact` | the public URL | | The contact the push services see in chi web's VAPID token: a `mailto:` address or an `https://` URL. Anything else stops `chi web` from starting (Apple refuses it). |
 | `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

@@ -93,7 +93,7 @@ StandardError in run_turn:
   → if turn.ended (it came from the after_turn/session_end hooks): logged as post_turn_error, re-raised
   → else: end_turn(turn, "failed", save: true) (a save that fails there is logged, turn_end_save_failed)
      # Both loops call LLM::FailedTurn.attach(e, conversation) before re-raising, so
-     # failed_messages keeps the loop's partial conversation (tool iterations included),
+     # failed_messages (TurnEndings) keeps the loop's partial conversation (tool iterations included),
      # else turn.messages, with TurnNote.failed(summary, continued: turn.continue) at the tail.
      # :turn_failed {error_class, message, duration_ms}; a provider error adds
      # error_kind, retryable, host and summary.
@@ -157,7 +157,7 @@ Stopped before the model was asked (prepare_turn returned false):
 The Engine does not talk to models directly. `Engine#backend` picks the loop the effective model's host speaks:
 
 ```
-Engine#backend → backend_for(effective_model)    # EffectiveModel.of(@host_registry, @model_choice)
+Engine#backend → backend_for(effective_model)    # EffectiveModel.of(@host_registry, @model_binding.choice)
   → host entry chat? (an api in LLM::Adapters::BY_API: openai, anthropic): LLM::ChatLoop (one per Engine, built on first use)
   → else:                                                     LLM::NativeBackend wrapping the Engine's KernelLoop
 ```
@@ -199,7 +199,9 @@ KernelLoop#run(messages, max_iterations:, on_stream_event:, cancel_controller:,
 
 `turn.conversation` is the loop's own copy, not the Engine's `turn.messages`. A failure attaches it to the error
 (`LLM::FailedTurn.attach`), so `Engine#failed_messages` can keep it; an Interrupt (Ctrl-C) too, for
-`Engine#ctrl_c_messages` (see Error paths).
+`Engine#ctrl_c_messages` (see Error paths). Both are `TurnEndings`', with the other pure builders of a turn's end
+(`kept_messages`, `failed_event`, `turn_summary`, `stop_facts`); the Engine forwards to it and keeps `end_turn`,
+`complete_turn`, `store_answer_display` and `record_last_turn`.
 
 ### ChatLoop (the chat APIs)
 
@@ -397,13 +399,14 @@ what a resolve gives, all without a `/model`. Frozen, so any thread may hold one
 - The Engine's readers take one (`Engine#effective_model`); those whose fallback always covered the resolve go
   through `SessionModelSettings#model_setting` (`session_model_settings.rb`: the Engine forwards its readers of the session's settings there). A turn takes one in `turn_settings` (before the hooks) and one in `generate` (after
   them); `system_prompt`, `steer_cut_after` (at `:turn_started`) and the turn-end warm-up take their own;
-  `stats_snapshot` and `session_state_snapshot` take one each (the latter nil-tolerant).
+  `stats_snapshot` and `session_state_snapshot` take one each (the latter nil-tolerant; both `EngineSnapshots`',
+  `engine_snapshots.rb`, which the Engine forwards to).
 - Never resolved (they hold on a broken resolve): `effective_model_ref`, `bare_model_name`,
   `guardrail_model_name`, `sync_model_key!`, `served_model(probe: false)` (`HostRegistry#model_ref`/`#bare_name`).
 - Readers on other threads: the Bridge (`/state`, `/stats`, the SSE reset, a steer's cut wait), the worker's
   command thread, the recap thread and plugin threads (`session_model_recap_target`), the REPL.
-- `ModelChoice` (`@model_choice`) holds the name and the typed name as one value, so a reader on another thread
-  never pairs one model's name with another's typed name.
+- `ModelChoice` (`ModelBinding#choice`) holds the name and the typed name as one value, so a reader on another
+  thread never pairs one model's name with another's typed name.
 - `EffectiveModel.of_session` builds a saved session's (no worker): `Web::App`, `LLMContextStrategy.for_session`.
 
 `SessionSetting` names the four per-session settings (llm_context, thinking, reasoning_history, toolkit): the
@@ -411,6 +414,21 @@ session's own value, the commands that move each chip, its chip from an Effectiv
 readers, a saved session's chip, and how the web takes a worker snapshot's. The session state, `/stats` (no
 toolkit), a `:command_ran` and the web's session JSON list them from it.
 
+### ModelBinding (the choice and its profile)
+
+`ModelBinding` (`model_binding.rb`) holds the session's model choice, the profile given to `Engine.new` (until a
+switch), the prompt profile resolved for the choice (kept as a `[choice, resolution]` pair) and the memory overlay
+keys (`#sync_model_key!`), under one mutex; it is ToolkitBinding's counterpart, and the Engine forwards
+`profile_resolution`, `refresh_profile!`, `store_profile`, `apply_profile`, `resolve_profile`, `sync_model_key!`
+and `model_key` to it.
+
+- `#switch!` (`Engine#switch_model!`'s swap) is one assignment under the mutex: a reader on another thread sees
+  the old pair or the new one. It drops the given profile and the kept resolution.
+- `#store_profile` keeps and applies a resolution only while the choice is still the one it was resolved for,
+  by identity (`equal?`, not `==`): a `/stats` probing on a Bridge thread while `/model` runs keeps nothing.
+- `#apply_profile` runs under the mutex: the system prompts built for another profile are dropped, then
+  `KernelLoop#use_profile!`. Nothing else takes the mutex.
+
 ### ThinkingNotices
 
 What a turn's thinking level leads to, said once per session and host (`thinking_notices.rb`): an effort the
@@ -476,7 +494,8 @@ drain hands the message to the model at a boundary, or until the turn ends (`Ste
 
 ### The turn's sink (`on_event`) and the observers
 
-`Engine#emit_event` sends each turn event to the turn's sink (`on_event`, the REPL's renderer) and then to the
+`Engine#emit_event` (`EventFanout#emit_event`, `event_fanout.rb`, which also builds the loops' stream handler and
+emits the working set) sends each turn event to the turn's sink (`on_event`, the REPL's renderer) and then to the
 persistent observers (`Engine#subscribe`), which get a copy with a monotonic `event_seq`. The observers are the
 metrics, the debug log, the thinking tails, and in a worker the Bridge, which streams to the web and the attached
 TUI. Errors in the sink or an observer are caught; they never break the turn.
@@ -584,8 +603,11 @@ hook registry (`@hooks.fire`), not on the sink or the observers. The other hook
 ```
 Engine initialization (in this order, among other things):
   @turn_state, @steer_cut (SteerCut: its GenerationPhase and WaitingSteer)
-  @host_registry, @model_choice (ModelChoice: the name and the name as typed); @model_settings (SessionModelSettings: the choice and the session read at use); @client = effective_model.client
-  @given_profile = profile or nil (resolved on first need, so building an Engine makes no network call)
+  @event_fanout (EventFanout: emit_event, the stream handler, the working set; its lookups read at call time)
+  @turn_endings (TurnEndings: the turn endings' builders)
+  @host_registry, @model_binding (ModelBinding: the ModelChoice, i.e. the name and the name as typed, and the given
+    profile or nil: resolved on first need, so building an Engine makes no network call); @model_settings
+    (SessionModelSettings: the choice and the session read at use); @client = effective_model.client
   MemoryBundle::SystemBundle.ensure! (the shipped system bundle installed; a failure is logged, not raised)
   @event_routes (EventRoutes: where a card or a notice goes: held while the plugins load, an anytime command's, an init task's, a turn event, else announced or held)
   @hook_routes (HookRoutes: notices (through @event_routes), hook questions, stop_turn/stop_generation, steer attribution)
@@ -609,9 +631,12 @@ Engine initialization (in this order, among other things):
   @native_backend = LLM::NativeBackend.new(kernel: @kernel)
   @prompt_builder = SystemPrompt.new(...)
   @session_observer with the metrics, the log subscriber and the thinking tails subscribed (subscribe_session_observers)
+  @engine_snapshots (EngineSnapshots: session_state_snapshot and stats_snapshot), built last: nothing reads a
+    snapshot while the Engine is built
 
 Model switching, Engine#switch_model!(model_name, persist_default:, typed:):
-  → checks the host (ModelProfile.check_host!), sets @model_choice (name and typed name in one assignment)
+  → checks the host (ModelProfile.check_host!), sets the choice (ModelBinding#switch!: name and typed name in
+    one assignment)
   → drops the given profile and the profile resolution (resolved again on first need; one that another
     thread finishes for the old model is neither kept nor applied: #store_profile)
   → sync_model_key!, @prompt_builder.reset! (the system prompt is built again)
@@ -810,6 +835,10 @@ Paths are under `lib/samagotchi/`.
 | File | Role |
 |---|---|
 | `engine.rb` | Engine: turn lifecycle, event emission, plugins, model switching |
+| `event_fanout.rb` | `EventFanout`: how an event reaches the turn's sink and the observers (`emit_event`), the loops' stream handler, the working set's emit and dedupe; the Engine forwards |
+| `engine_snapshots.rb` | `EngineSnapshots`: the UIs' read model, `session_state_snapshot` (cheap, never raises) and `stats_snapshot` (may probe `/props`); the Engine forwards |
+| `model_binding.rb` | `ModelBinding`: the model choice and the prompt profile resolved for it, under one mutex, and the overlay keys; the Engine forwards |
+| `turn_endings.rb` | `TurnEndings`: what each turn ending keeps and announces (the kept messages and their `TurnNote`, `failed_event`, `turn_summary`, `stop_facts`); the Engine forwards |
 | `turn_state.rb` | Cross-thread turn state (running, controller, sink, steers, activity clock) |
 | `steer_cut.rb` | `SteerCut`: the Engine's seam for a message cutting the generation |
 | `generation_phase.rb`, `waiting_steer.rb` | Whether a steer may cut the running generation, and the steer that waits to |

data/docs/internals/participants.md

@@ -234,7 +234,7 @@ fields: a field added to an event later reaches nobody until it is named there.
   and never after a key word whose value is still to come, `Redact::OPEN_VALUE`; past 1600 with no such space,
   the line's last unbroken run and the rest of that line go out as one `[redacted]`). The owner's stream never
   goes through it (a byte pipe).
-- **The conversation** (`.messages`, over `App#messages_for_display(parts: true)`): a user message only when it is a
+- **The conversation** (`.messages`, over `App#messages_for_display(parts: true)`, `Web::MessageDisplay`): a user message only when it is a
   turn's prompt (it has the turn's id) or a person's merged line, and never one from a source that isn't a person's;
   so the owner's `!` line and its output, a delegate's report (a wake turn's too), and the notes chi adds (a declined
   Continue) never show. A turn no person sent (its record's `automatic`, `SessionMetrics`: a task's or a plugin's,

data/docs/internals/remote-sessions.md

@@ -166,12 +166,12 @@ with a "Machine-local" comment; the rest branch on `@access.remote?` (`SendComma
 | Check | Local (in the command) | Under `--remote` |
 |---|---|---|
 | Images to a model that can't see them (`SendCommand#vision_refusal`) | client | server: `check_vision: true` on the create and turn routes → 422 `no_vision` |
-| A parent's `/continue yes`, a loosening `/parent-answers` (`SendCommand::ParentGate`) | client, before any target | server: `App#parent_gate` on create/turn for a `cli:send`/`cli:answer` `client_id` → 403; each target refuses its own |
+| A parent's `/continue yes`, a loosening `/parent-answers` (`SendCommand::ParentGate`) | client, before any target | server: `App#parent_gate` (`Web::SessionCreate`) on create/turn for a `cli:send`/`cli:answer` `client_id` → 403; each target refuses its own |
 | `--parent-answers` looser than config.yml (`Guardrails::ParentPolicy.capped_note`) | client | server: the create's `parent_answers_warning` |
 | A parent's option on `chi answer` (`AnswerCommand#parent_refusal`) | client, then the worker | skipped on the client; the worker checks (the answer route forwards `cli:answer`), and its 403 `parent_answer_refused` passes through |
 | What a parent may pick, for the report (`ParentReport.strategy_for`) | client | server: the wait route's `parent_strategy` |
 | `send --wait` busy check (`SendCommand::Busy`) | client | server: `wait/prepare` with `busy: true` → 409 `busy`/`waiting` with the `Busy` fields (`question`, `parent_strategy`); the client words it (`Busy#message(via:)`) |
-| `--continues`' previous link and model (`SendCommand#continued_model`) | client | server: `handle_continue` |
+| `--continues`' previous link and model (`SendCommand#continued_model`) | client | server: `handle_continue` (`Web::SessionCreate`) |
 | `--toolkit`, `--tool`, `--set` (`Toolkit.from_flags`, `SessionConfig.from_flags`) | client | server: sent as `SetupWords` → 400 `invalid_*` → exit 2 |
 | `--dir` (default: the cwd) | client, `File.directory?` | required and absolute on the client (`remote_new_options`); chi web's `scope_dir` checks it exists |
 | `sessions list`'s default project (`ProjectScope.root_for(Dir.pwd)`) | client | every project's; `--scope=project` needs `--cwd` (a folder there) |
@@ -212,7 +212,7 @@ with a "Machine-local" comment; the rest branch on `@access.remote?` (`SendComma
   `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`
+- **`client_id` only tightens.** `handle_question_answer` (`Web::SessionControl`) forwards `client_id` only when it is `ClientId::CLI_ANSWER`
   and drops any other value, so a remote answer is held to the parent rules and can't pass for the user's own. On
   create and turn, a `cli:send` / `cli:answer` id adds checks (`CLI_SEND_IDS`) and never removes any.
 - **A remote attach's `client_id`** (`tui:<pid>@<host>`, P4-D6) is forwarded as given on `/turn` and `/command`, as

data/docs/internals/web-push.md

@@ -0,0 +1,200 @@
+# Web Push (internals)
+
+chi web pushes to the owner's phone when a session waits on an approval or a question: the phone runs chi web as a
+Home Screen app (iOS 16.4+), its bell subscribes the device, and chi web, the only sender, pushes through the
+device's push service (Apple's `web.push.apple.com`). The user side is in
+[configuration.md](../configuration.md#phone-notifications-web-push). This page is how it is built (P1 of the plan:
+approvals and questions; the step-limit question, cards, failed and done turns, presence and the device list come
+later).
+
+```
+SessionHub ──emit──▶ Notifier#call(event) ──Queue──▶ sender thread
+                         Attention rules               hold 3 s → still open?
+                                                       Crypto.encrypt + VAPID → Client#deliver(endpoint)
+                                                       201 ok · 404/410 drop the device · 403 BadJwtToken stop + log
+service worker ◀── Apple (web.push.apple.com) ◀──────── {v, kind: show, tag, title, body, url, badge, open?}
+```
+
+**Every push chi sends shows a notification.** WebKit removes a subscription after 3 pushes that show no
+notification ("Enforce silent push quota", WebKit commit 108ccb44), and Apple keeps answering 201 for it (Apple
+Developer Forums 719990), so chi can't see it happen. The user check of 2026-10-24 lost its subscription this way:
+7 question pushes and 6 close pushes in ~6 min, then a question push and a test push both answered 201 and never
+showed. So there is no close push and no badge-only push: answered notifications leave the lock screen through the
+next show's `open` list (the service worker) or when the app opens (the page).
+
+## The crypto (`web/push/crypto.rb`)
+
+OpenSSL only, no gem (the `web-push` gem would bring `jwt` and the `openssl` gem for ~60 lines); it runs on Ruby 3.3's
+openssl gem (`KDF.hkdf`, `PKey::EC#derive`, `to_octet_string`). Base64url is `pack("m0")` (`base64` is no default
+gem from Ruby 3.4).
+
+- `Crypto.encrypt(plaintext, p256dh:, auth:)`: RFC 8291 §3.4 on RFC 8188's aes128gcm, one record (rs 4096, the 0x02
+  last-record delimiter, no padding), a fresh salt and sender key per message. `spec/web/push/crypto_spec.rb` pins
+  RFC 8291 Appendix A byte for byte (the RFC's fixed sender key and salt).
+- `Crypto.vapid_authorization(endpoint, key:, sub:)`: RFC 8292, `vapid t=<JWT>, k=<public key>`; the JWT is ES256
+  (OpenSSL's DER signature turned into r‖s), `aud` the endpoint's origin, `exp` now + 12 h, `sub` the contact.
+- `Crypto.valid_sub?`: a `mailto:` with an `@` or an `https://` URL with a host. Apple answers 403
+  `{"reason":"BadJwtToken"}` for anything else (the spike: `chi@localhost`), and 201 for the public origin, which is
+  the default contact (`web.push.contact` overrides it).
+
+`spec/support/web_push_receiver.rb` is a device's side for the specs (its key pair, decryption, the JWT check), so a
+spec reads what chi web sent rather than trusting it.
+
+## The store (`web/push/store.rb`)
+
+`$XDG_STATE_HOME/samagotchi/web-push/` (`Store.dir`: Grants' rule, next to the sessions dir), a 0700 folder with 0600
+files, one per machine, never in config.yml:
+
+- `vapid.pem`: chi web's one P-256 key, made the first time (`Store#vapid_key`). Replacing it makes every device's
+  subscription useless (the push services tie it to the key): the bell's subscribe drops a subscription made with
+  another key and makes a new one.
+- `subscriptions.json`: `{"version": 1, "subscriptions": [{id, endpoint, keys: {p256dh, auth}, origin, label,
+  created_at, last_ok_at, last_error, prefs}]}`, read as `Store::Sub` values. `id` is the first 8 hex of the
+  endpoint's SHA-256: the only name of a device outside the store. `Sub#public_h` and `#inspect` never carry the
+  endpoint or the keys; neither do the log lines.
+
+`Store#add` checks what `pushManager.subscribe` gave, one message per refusal (the route answers it as 400
+`invalid_subscription`): an endpoint and both keys; https on port 443 without userinfo, at most 2048 bytes; a host in
+`Store::PUSH_SERVICES` (Apple, Google's FCM, Mozilla, `*.notify.windows.com`; a `services:` seam for specs, not
+config): chi web POSTs to that URL, so it never takes an arbitrary host; `p256dh` a 65-byte uncompressed point,
+`auth` 16 bytes. The same endpoint again replaces the old entry. Every write is a read-change-write under
+`store.lock` (chi web's request threads and the sender thread both write). A `subscriptions.json` that doesn't read
+lists no device and is never written over. `Store#check_permissions!` uses `Web::PrivateFiles.check!`, the check the
+grants use, worded with what the folder holds; `Server.launch` runs it (`Push.preflight!`, with the contact and the
+key) before any tunnel goes up, and a refusal is one `Error:` line, exit 1.
+
+Each subscription keeps the public origin it was made on; the Notifier sends only to this run's. A renamed machine or
+tailnet leaves the old ones stale (never sent to: a tap would open an origin that no longer serves chi).
+
+## The client (`web/push/client.rb`)
+
+`Client#deliver(sub, payload, ttl:, urgency:)` encrypts the payload's JSON, POSTs it over TLS (open 5 s, read 10 s,
+no redirects, no retry) with `Content-Encoding: aes128gcm`, `TTL`, `Urgency` and the VAPID header, and answers a
+`Client::Result`: `:ok` (200/201/202), `:gone` (404/410: the device dropped it), `:bad_jwt` (403 with
+`BadJwtToken`), `:failed` (anything else; a connection error as its class name or `timeout`, never its message). The
+transport is injectable: `spec/web/push/client_spec.rb` runs a fake push service (WEBrick, plain http through the
+injected transport) that decrypts each body with the device's key and checks the headers and the JWT.
+
+## The payload and the service worker
+
+The service worker is the only reader of the payload (JSON, at most `Notifier::OPEN_LIMIT`, 3000 bytes, with
+`open`; one aes128gcm record leaves 3993 bytes of plaintext under Web Push's 4096: 86 header, 1 delimiter, 16 tag):
+
+- `{"v":1,"kind":"show","tag":KEY,"title":…,"body":…,"url":"/#/s/<id>","badge":N,"open":[KEY…]}`: TTL 12 h,
+  `Urgency: high`. `open` only while the whole list fits the limit; the test push (`chi:test`) has neither `open`
+  nor `badge`.
+
+`badge` and `open` are the keys still open in the Notifier's summaries (`Attention.open_keys`: a pending approval
+or question, a hook's too, not relayed), so an approval pushed by an earlier chi web run still counts after a
+restart. `public/sw.js` is a classic script (module service workers on iOS are unverified) at scope `/`. Every push
+event ends in `showNotification`: a payload that isn't a readable v1 show (no data, bad JSON, another `v`, a stale
+`close` from an older chi web, any other kind) shows a fallback (`chi` / "open chi", tag `chi:other`, url `/`), and a
+show iOS refuses is shown once more without its icon and data. A show calls `showNotification(title, {body, tag,
+icon, data: {url}})` first; then, when `open` is an array, closes every `getNotifications()` whose tag is a
+question's `"<sid>:<qid>"` (never `chi:*`), isn't the new one and isn't in `open` (after the show: closing before it
+fails on iOS; errors are swallowed); then `setAppBadge(badge)` when `badge` is a number. A tap focuses the app's first window and navigates it to the url, else opens one (only a path of chi web's); `install`
+skips waiting, `activate` claims the clients. No fetch handler and no caching: chi web has no offline mode, and a
+fetch handler would change how the page loads. `spec/web/public/sw.test.js` runs it in a `vm` with a fake worker
+scope.
+
+The manifest, `sw.js` and the icons are `App::GATE_FREE_PATHS` (exact paths, still after the Host, cross-site and
+frame checks): Chrome fetches a manifest without credentials, and none of them holds a secret. The icons are
+rendered from `favicon.svg` by `script/render-icons` (Playwright's Chromium), full bleed and opaque (iOS fills
+transparency with black).
+
+## The Notifier (`web/push/notifier.rb`) and its rules (`web/push/attention.rb`)
+
+`Push::Attention` is the server's port of `web/public/notify.js` for what P1 pushes, so a push and the tab's
+notification ring for the same thing under the same key:
+
+- `Attention.for(prev, next)`: a new `pending_question` id that isn't `relayed_to` (absent when nil: the summary
+  compacts it), whose **reason** (notify.js `questionReason`: `approval`, `continue`, anything else incl. `hook` is
+  a question) is approval or question. Filtering on the reason, never on `kind == "question"`, keeps hook questions.
+  A delegated child's (`parent_id`) approval or hook question holds `RELAY_HOLD` 3.5 s (notify.js `RELAY_HOLD_MS`):
+  its parent may relay it. The key is `"<sid>:<qid>"`.
+- `Attention.closed_keys(prev, next)`: the question answered, replaced, newly relayed, or the session gone.
+- `Attention.text(summary, reason)`: notify.js `attentionText`'s words: the session's title, first preview or last
+  prompt clipped to 61, and "needs approval" / "needs an answer". Never the question or the command.
+
+`Notifier#call(event)` is a `SessionHub` sink. **The hub calls it under its Monitor**, from the tick thread and also
+from chi web's request threads (`SessionHub#touch`, from the stop/archive/delete routes), so it only enqueues: a push
+is a 0.5 s https call. `emit` already rescues a raising sink. The sink keeps the last summary per session and turns
+each `session` / `session_gone` event into a `Show` (with its text) or a `Close` (it was answered anywhere) on a
+Queue.
+
+**Seeding**: `Notifier#start(hub)` subscribes with `snapshot: true` and takes the summaries as the seed, so what is
+open already never pushes. The hub's projection is empty before its first scan, so `Server.start` runs `hub.scan`
+once after the `chi` line's subscribe and before `notifier.start(hub)`, then `hub.start`. Events that reach the sink
+before the seed is in (they are newer than the snapshot) are applied after it.
+
+The sender thread holds each show (`HOLD` 3 s, or the event's own), then pushes it only while its key is still in
+`Attention.open_keys` of the summaries (read under the sink's mutex at flush time), to every subscription on this
+run's origin, with that list as `open` and its size as `badge`. A close only drops a show still in its hold: it
+pushes nothing. Results: `:ok` stamps the device's
+`last_ok_at`; `:gone` removes it; `:failed` keeps its code in `last_error` and logs `push_failed`; `:bad_jwt` logs
+one `push_bad_jwt` warning (on chi web's terminal too) and stops all pushes until chi web restarts. Log lines carry
+`device:` (the short id), `code:`, `ms:`, `kind:`: never the endpoint, keys or text. `#stop` drops pending holds and
+joins with a timeout; `Server.start`'s ensure calls it. Specs drive `#pump` with a moved clock
+(`start(hub, sender: false)`), and one example runs the real thread with a client that blocks.
+
+## The routes (`web/push_routes.rb`)
+
+`:owner` rows in `App::ROUTES` (so `participant_gate_spec` refuses each to a participant), handlers in
+`Web::PushRoutes`; `@push` is the run's `Push::Runtime` (store, client, origin), nil when push is off (no https
+public URL, or `web.push.enabled: false`):
+
+- `GET /api/push[?endpoint=E]` → `{enabled, public_key, origin, this: {id, label}|null}`; off: `enabled: false` and
+  no key.
+- `POST /api/push/subscriptions {subscription: {endpoint, keys}}` → 201 `{id, label}`; the label is chi's own
+  ("iPhone · <date>", from the User-Agent's device class: iPhone, iPad, Mac, else Browser).
+- `DELETE /api/push/subscriptions {endpoint}` → 204.
+- `POST /api/push/test {endpoint?}` → a test push to that device or every one on this origin, answered per device
+  (`{devices: [{id, label, status, code, ms}]}`); the bell sends one after subscribing.
+
+With push off the three writes answer 409 `push_off`.
+
+## The page (`public/push.js`, `public/notifications.js`)
+
+`push.js` holds the pure parts: `pushSupported({win, nav})` (a secure context, `serviceWorker`, `PushManager`, and a
+standalone app: `matchMedia("(display-mode: standalone)")` or iOS's `navigator.standalone`), `urlBase64ToBytes`,
+`subscribe({reg, key, post})` (drops a subscription made with another key), `unsubscribe({reg, del})`. In the Home
+Screen app the bell (`notifications.js`) registers `/sw.js`, asks `GET /api/push` with its subscription's endpoint,
+and is "push to this phone" when chi web pushes: on while chi web has this device. A tap asks permission from the tap
+(iOS asks only from a user gesture), subscribes, posts it and sends a test push; a tap when on unsubscribes and
+deletes. The tab's own OS notification is left to the push there; the title count stays. In a browser tab, or with
+chi web not pushing, the bell is the in-tab one, unchanged (no duplicate desktop pushes).
+
+**The device's tidy-up** (`syncDevice`, the Home Screen app with the bell on): closes the shown notifications whose
+tag is a question's (`push.js isQuestionTag`, so `chi:test` stays) and isn't open in the page's `byId`
+(`push.js openPushKeys`: `Attention.open_keys`'s rule, with notify.js's `questionReason`), and sets or clears the app
+badge (`navigator.setAppBadge` / `clearAppBadge`); the bell turned off clears it. It runs once push is known, when
+the page comes back in front, and after each hub frame while visible (so answering on the Mac with the app open
+clears it at once), one at a time with one rerun. Never before the first snapshot (an empty `byId` would close
+everything) and never on a project's page (`createNotifications({scoped})`, app.js passes `!!scope.dir`: its
+`/api/events?dir=` leaves out the other projects' sessions).
+
+Accepted staleness: an approval answered elsewhere keeps its banner until the app opens (the worker's cleanup on the next push doesn't work on iOS yet: see iOS facts)
+(or a swipe), and the icon badge may be too high until then; a show already handed to Apple just before its answer
+can land after the page's tidy-up and stay until the next one. Unverified on iOS: `getNotifications()` and
+`setAppBadge` from the page (a Window); the worker's cleanup still runs on the next push if they do nothing.
+
+## iOS facts (the spike, 2026-10-24, on an iPhone)
+
+- **Close by tag lookup** (the P1b phone check, 2026-10-24, iOS 26): inside a push handler, after `showNotification`,
+  the unfiltered `getNotifications()` lists the shown ones with their tags, but `close()` on one from that list left
+  it on the lock screen; one from `getNotifications({tag})` closed. So `sw.js`'s cleanup reads the tags from the list
+  and closes through the tag lookup. Not yet known whether that is a WebKit bug (unfiltered close never probed alone). **But** on a real
+  question pair (A shown, answered, B pushed ~6 s later, the new worker confirmed) A's banner still stayed: the tag
+  lookup closed a banner minutes old (the probe) but not a seconds-old one. So the worker's cleanup doesn't work on iOS
+  yet (cause unknown: timing, or the banner still presenting); the page's cleanup when the app opens does.
+- **No replace by `tag`**: two notifications with one tag both stay, and closing same-tag ones inside the push
+  handler before `showNotification` doesn't remove the older one. A separate close push that only closed
+  `getNotifications({tag})` did, but it shows nothing (see the quota below), so the worker now closes after its show.
+- **The service worker can't see the app in front** (`clients.matchAll` gave 0 windows with the app open) and a
+  banner shows anyway: "don't push while I'm looking" has to be decided server-side, from the pages' presence (P2).
+- **Silent pushes**: the spike's 4 close pushes in a row didn't revoke the subscription, but that was luck or lazy
+  enforcement: the user check's 6 did (WebKit's quota is 3 pushes that show nothing; see the top of this page).
+- iOS sent the cookie with the manifest, `sw.js` and icon fetches, but Chrome fetches manifests without credentials:
+  they are gate-free rather than relying on that.
+- `navigator.setAppBadge(n)` from the service worker sets the icon's badge; a push mirrors to the Watch.
+- The Home Screen app copies Safari's cookie when it is added and keeps its own jar after (400 days).

data/docs/internals/working-set.md

@@ -99,9 +99,9 @@ when it has outputs and none is `sent`. An edit-only item, a failed run's file o
 ## Delivery
 
 **The event.** The Engine emits `{type: :working_set_updated, items:, at:}` (and `adds:` while the user's adds are
-pending: [Steering: add and unadd](#steering-add-and-unadd)) (`Engine#emit_working_set`):
-- after each `:generation_started`, in `build_stream_event_handler`, from the running turn's conversation
-  (`Engine#live_conversation`, read on the turn's thread) under the turn's strategy
+pending: [Steering: add and unadd](#steering-add-and-unadd)) (`Engine#emit_working_set`, `EventFanout`'s):
+- after each `:generation_started`, in `build_stream_event_handler` (`EventFanout`), from the running turn's
+  conversation (`Engine#live_conversation`, read on the turn's thread) under the turn's strategy
   (`@kernel.turn_settings.llm_context`). Both loops start a generation after `apply_llm_context!`, so the set is
   what that request sends;
 - once in `Engine#end_turn`, after `replace_session_messages` and before the end event, from the kept messages (the
@@ -122,7 +122,7 @@ smaller set reaches the page then, not at the next request. It goes out whatever
 the Bridge (`ClientEvent.project`) passes it on unchanged, and the attached TUI ignores it.
 
 **The route.** `GET /api/sessions/:id/working_set` (`Web::App#handle_working_set`) answers the snapshot's `to_h`
-and `running`. With a live worker it builds from the worker's snapshot messages (as `handle_show` reads them, keys
+and `running`. With a live worker it builds from the worker's snapshot messages (as `handle_show` (`Web::SessionShow`) reads them, keys
 symbolized) and the worker's llm ctx chip. Without one it builds from the session file and its saved chip
 (`SessionSetting::LLM_CONTEXT`). The folder is the session's `working_directory`. `running` is true when the
 snapshot has a turn in progress (`current_turn`).
@@ -206,8 +206,9 @@ projection), on both loops. It costs one model step; a model may skip it (the no
 - **The projection**: the pending adds are not items (nothing of them is sent), but the snapshot carries them:
   `WorkingSet.pending_adds` reads the pending note (`WorkingSet.pending_note_index` / `pending_ops`, which
   `WorkingSetSteer` delegates to) into `Snapshot#adds` (`WorkingSet::Add`: `kind`, `key`, `label`), and `to_h` adds
-  `adds:` while any is pending. `Engine#emit_working_set` compares the items and the adds, so an add announces a new
-  set and the next turn's first request (the note sent, no adds) emits again, which clears the page's pending add.
+  `adds:` while any is pending. `Engine#emit_working_set` (`EventFanout`, which keeps the last one emitted) compares
+  the items and the adds, so an add announces a new set and the next turn's first request (the note sent, no adds)
+  emits again, which clears the page's pending add.
   A running turn's set has none (the note was sent when it started), so the Bridge snapshot's `working_set` and the
   GET's `running` answer leave it out.
 

data/docs/sessions.md

@@ -225,7 +225,7 @@ chi send --new --continues last:3fa2 -m "new day"      # the next link of 3fa2's
   (`SAMAGOTCHI_THINKING_LEVEL=low chi send --new …`) only reaches the worker this call spawns: when the session's
   worker is woken later (by `chi web`, a delivery) without that env, the level is gone. Use `--thinking`.
 - `--new` prints `<full id>  started` on stdout. With `--wait` that line (and the `sent` line for an existing session) goes to stderr, so stdout is exactly the answer: the reply of the turn the message started, in full. It is the worker's `output/` file, the same one `delegate` reads; a turn that ends with only tool calls and no text has none.
-- `--wait` takes one session: `--new` or one id. A session with a running turn is refused (`busy: a turn is running; --queue runs the message after it, chi send --wait ID waits for it, chi --attach ID shows it`, exit 1): the message would merge into it, and its reply would come back as the answer. To an idle session (or with `--new`) the wait is for the message's own turn (the ack's `enqueued_id`; one merged into a turn that started at that moment gets that turn's reply). `--queue --wait` is the way in: the message runs as a turn of its own after the running one, and the wait is for that turn alone (the ack's `enqueued_id` names its reply file and its `last_turn`), so the running turn's reply and end, and a question it asks meanwhile, are not the answer (it keeps waiting through them; its `--timeout` still applies); a question its own turn asks is (exit 3). Two queued waits each get their own turn's answer. A session waiting for an answer is still refused. `--format json` adds `delivery`: `queue`, or `next_step` when the running turn ended before the message went in (it then ran at once, and the answer is still its own).
+- `--wait` takes one session: `--new` or one id. A session with a running turn is refused (`busy: a turn is running; --queue runs the message after it, chi send --wait ID waits for it, chi --attach ID shows it`, exit 1): the message would merge into it, and its reply would come back as the answer. To an idle session (or with `--new`) the wait is for the message's own turn (the ack's `enqueued_id`, or, for a `--new` that starts with the message, the id its create gives that first turn — `first_turn_id` in chi web's 201, `turn_id` in `--format json`; one merged into a turn that started at that moment gets that turn's reply). `--queue --wait` is the way in: the message runs as a turn of its own after the running one, and the wait is for that turn alone (the ack's `enqueued_id` names its reply file and its `last_turn`), so the running turn's reply and end, and a question it asks meanwhile, are not the answer (it keeps waiting through them; its `--timeout` still applies); a question its own turn asks is (exit 3). Two queued waits each get their own turn's answer. A session waiting for an answer is still refused. `--format json` adds `delivery`: `queue`, or `next_step` when the running turn ended before the message went in (it then ran at once, and the answer is still its own).
 - Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question, a guardrail approval, or the step-limit question: see [chi as a sub-agent](sub-agent.md#the-step-limit)), and the session keeps waiting: stderr gets the whole question (`waiting for an answer (approval): …`, its text, the numbered options, whether free text is allowed) and how to answer it (`chi answer ID --question QID --option N`, or `chi --attach ID`, the web); 4 `--timeout S` passed with the turn still running (it goes on; wait again); 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, or the session was stopped; 130 on Ctrl-C, which leaves the turn running (`still running: chi send --wait --turn T ID` for a turn whose id is known, else `chi send --wait ID waits again; chi --attach ID shows it`, as after a `--timeout`). There is no default timeout.
 - `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `removed` (a `--queue --wait` message taken back before it ran), `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1); `failed` adds `error_kind` and `retryable`, `canceled` adds `cancel_reason` (`worker_stopped`: the turn waited for died with its worker and the next worker settled it) and `stopped_by`, when known. A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
 - `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. With a turn running, that turn's reply (its `interrupted_turn` mark names it), not a turn's queued behind it; with the step-limit question standing, the reply of the turn its Continue runs; with an idle session whose last turn already ended, that ended turn is the answer: its reply, or its end when it left no reply — a turn that finished in the gap between waits is reported, not waited for. With none of those (or a worker whose `bridge.json` lacks `turn_ids`), the next reply of any turn. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).