samagotchi 0.67.0 → 0.68.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58f42be965113cdd1f5736f77b9a5be8e9fbd77088b4a2013f9b7e86ae7ceb12
-  data.tar.gz: a093f0921d62e84c9e6c34ac10482e57e9e041a5a9d21eda41a88052e819cda1
+  metadata.gz: 66b4e4cd47fc55a5678ee1f1b799c029a52959bcc374b04337819164235a3e24
+  data.tar.gz: 150202d4f1e2c0d526736da39dec4eaf142a62cc365581deb200d2ef66f4555f
 SHA512:
-  metadata.gz: d02e8644b724765182cabb9a74eafcfaec94eb13781680e29cc33bfb1ee2bc850f55a7df4117b61d8a2889c7d48bf4792b88ba316676a1fb6be5632cc98d1a3f
-  data.tar.gz: a4397b9a00729a4eb230415e265c834f85f42b8b6ded242dc3c981ad6f3e543f367d7a9df00ed6d516aef12c2e2266a765b0f66c7025f575975c83fd4b556b86
+  metadata.gz: 649aeccb314f2e39cbd63b879c20a1006598dcb24dab76787c4906d5ce0c38aa86d3ca04e77dc57f7d04229f75132ee5cafbe71a3f5722328b204eacbaf4e550
+  data.tar.gz: 235f6ba63f7a59125698dab591ff4800e7b8abd0d6ddf49f519fdbf1a1ca449fe6d9319a76f7f01c92e9507ebae662cb99a6ff00cf57c0825c41fee3b8d935ea

data/CHANGELOG.md

@@ -8,6 +8,25 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.68.0] - 2026-10-14
+
+### Changed
+
+- Web: the settings popovers' selects (thinking level, LLM context strategy and apply) look the same in Safari, Chrome
+  and Firefox: chi's own box and caret instead of each browser's native control.
+- Web: the thinking chip comes before the LLM context chip, on the session bar (think, reasoning, llm ctx, tools) and
+  beside the start page's model picker.
+
+### Fixed
+
+- `/model` while the web or another terminal read `/stats` no longer leaves the new model on the old model's prompt
+  profile (its turns formatted for the wrong family until the next `/model`).
+- Web: the sessions strip no longer blinks when a session updates: a card fades in only when it is new to the list,
+  and a running or waiting card's dot keeps its pulse through the redraw. All sessions no longer re-fades on every
+  update or search keystroke either.
+
+Update with `chi update` (the system bundle 0.68.0), then restart `chi web`.
+
 ## [0.67.0] - 2026-10-14
 
 ### Added
@@ -2937,7 +2956,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.67.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.68.0...HEAD
+[0.68.0]: https://github.com/dm1try/samagotchi/compare/v0.67.0...v0.68.0
 [0.67.0]: https://github.com/dm1try/samagotchi/compare/v0.66.0...v0.67.0
 [0.66.0]: https://github.com/dm1try/samagotchi/compare/v0.65.0...v0.66.0
 [0.65.0]: https://github.com/dm1try/samagotchi/compare/v0.64.0...v0.65.0

data/docs/architecture.md

@@ -400,7 +400,9 @@ by one pure resolver, `ModelRef.parse` (host prefix, alias), given the configure
 hosts and aliases; `HostRegistry` routes a name that names no host (its model
 index after `/models`) and builds the `ModelTarget`.
 
-Engine picks the loop from the effective model's host (`HostRegistry#resolve`):
+Engine picks the loop from the effective model's host: `EffectiveModel.of` resolves it (`HostRegistry#resolve`)
+on every read, never kept, since config.yml and a model listing can move it without a `/model`
+([internals/engine.md](internals/engine.md), "EffectiveModel"):
 
 | Loop | Class | Host | Talks through |
 |---|---|---|---|
@@ -496,7 +498,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 
 | Component | Main file(s) | What it is |
 |---|---|---|
-| Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). |
+| Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). The session is saved from the turn's thread, Bridge threads and a signal's thread; `Session#save` takes a per-session lock around its snapshot and write, so an older snapshot never lands over a newer one. |
 | Config | `config.rb` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)). |
 | MemoryBundle | `memory_bundle.rb`, `memory_bundle/{installer,builder,installed_bundle,plugin_ref,bundle_hook}.rb` (`Installer`, `Builder`, `InstalledBundle`, `PluginRef`, `BundleHook`) | Installing, building and reading bundles of memories, hooks and plugins. |
 | Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/tool_spec.rb` (`Plugin::ToolSpec`: a checked tool declaration, how it is registered), `plugin/loader.rb` | What a bundle's plugin registers: tools, commands, annotation actions, hooks, services, toolkits, peer sources ([plugins.md](plugins.md)). |
@@ -515,7 +517,8 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
 | Steer delivery | `steer.rb` (`Steer`), `delivery.rb` (`Delivery`), `steer_cut.rb` (`SteerCut`), `generation_phase.rb`, `waiting_steer.rb`, `steer_cut_after.rb` (`SteerCutAfter`), `cut_policy.rb` (`CutPolicy`) | A message for a running turn: at the next boundary, cutting a thinking-only generation, or queued for the turn's end ([internals/engine.md](internals/engine.md)). |
 | Prompt files | `prompt_files.rb` (`PromptFiles`) | The AGENTS.md chain (root → cwd) and the appended files the system prompt carries. |
-| Model settings | `model_profile.rb` (`ModelProfile`), `model_settings.rb`, `sampling_settings.rb`, `model_catalog.rb` (`ModelCatalog`), `model_notes.rb` (`ModelNotes`) | A model's prompt format, its `models:` entry, its request parameters, the pickable model rows (`chi models`, `/api/models`), the notes its prompt loads. |
+| Model settings | `effective_model.rb` (`EffectiveModel`, `ModelChoice`), `model_profile.rb` (`ModelProfile`), `model_settings.rb`, `sampling_settings.rb`, `model_catalog.rb` (`ModelCatalog`), `model_notes.rb` (`ModelNotes`) | The effective model's settings as one snapshot per read, a model's prompt format, its `models:` entry, its request parameters, the pickable model rows (`chi models`, `/api/models`), the notes its prompt loads. |
+| Session settings | `session_setting.rb` (`SessionSetting`), `level_setting_command.rb` (`/thinking`, `/reasoning-history`), `llm_context_command.rb`, `toolkit_command.rb`, `thinking_notices.rb` (`ThinkingNotices`) | A session's own llm_context, thinking, reasoning_history and toolkit: their chips (session state, `/stats`, `:command_ran`, the web), the commands that set them, the thinking level's notices. |
 | Dialects | `llm/dialect.rb` (`LLM::Dialect`) | What an `api: anthropic` provider's `/v1/messages` does differently (`dialect: fireworks`) ([internals/anthropic.md](internals/anthropic.md)). |
 | Logging | `log.rb` (`Log`), `log_subscriber.rb` (`LogSubscriber`), `log_path.rb` (`LogPath`), `log_line.rb` | The debug log: tagged records, a session's event trail, where the file goes ([configuration.md](configuration.md#debug-log-file)). |
 | Stores | `reminder_store.rb` (`ReminderStore`), `recap_store.rb` (`RecapStore`) | A session's reminders, and its idle recap (`recap.json`). |

data/docs/internals/engine.md

@@ -34,7 +34,8 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     #                      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)
-  │     # turn.settings = LLM::TurnSettings (vision, sampling, thinking; model_name is set in generate)
+  │     # turn.settings = LLM::TurnSettings (vision, sampling, thinking; model_name is set in generate),
+  │     #   from one EffectiveModel; ThinkingNotices#turn_started keeps the level and says one the host can't do
   │     # announces guardrail load failures, starts and awaits plugin init tasks, applies staged tools,
   │     #   then the session's toolkit (apply_toolkit!: Registry#toolkit, a prompt rebuild when it changed)
   │     # fires the :session_start hook on the Engine's first turn, then the :before_turn hook
@@ -43,11 +44,12 @@ Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:,
   │     # Returns false when a Stop came during the probes or the init wait, else true
   │
   ├── generate(turn, max_iterations:, max_tool_output_chars:, pending_input:)
-  │     # sync_kernel_client!, then @kernel.turn_settings = turn.settings with model_name, window_setting,
-  │     #   llm_context (turn_llm_context: the session's, the model's/host's, else llm_context.strategy)
-  │     #   and price (turn_price: hosts.<name>.models.<id>.price), all read per turn
+  │     # one EffectiveModel (after the hooks, which may switch the model): sync_kernel_client!, then
+  │     #   @kernel.turn_settings = turn.settings with model_name, window_setting, llm_context (the
+  │     #   session's, the model's/host's, else llm_context.strategy) and price
+  │     #   (hosts.<name>.models.<id>.price), all read per turn
   │     # turn.limit = max_iterations or IterationLimit.for
-  │     # backend.complete(messages: turn.messages, ..., pending_input: turn_drain(pending_input))
+  │     # backend(model).complete(messages: turn.messages, ..., pending_input: turn_drain(pending_input))
   │     # Returns LLM::ModelResult (text, conversation, canceled?, exhausted?, tool_activity,
   │     #                          context_status, empty_steps, empty_retries)
   │
@@ -118,6 +120,16 @@ A worker's TERM, HUP or INT (WorkerSignals, trapped by a spawned worker only):
      loop left brings only that hard exit, and run_session_loop restores the default handlers
   → run_session_loop: exit 0, no discard; input queued behind the stopped turn wakes a new worker
 
+The effective model doesn't resolve (a broken host config, HostRegistry#resolve raising):
+  → the rescued readers give their fallback (Engine#model_setting) and log effective_model_unresolved;
+     a setting that fails on a resolved model gives its fallback and logs <setting>_unresolved
+     (sampling, thinking, reasoning_history, steer_cut_after, llm_context, window, price, served,
+     vision_adapter); served_probe_failed when asking the server for its served model fails;
+     alias_note_failed, thinking_notice_failed likewise
+  → WARN once per process for an (event, model, error class), DEBUG after (EffectiveModel::Unresolved)
+  → session_state_snapshot never raises (its model fields are nil); a turn, stats_snapshot,
+     chat_model? and system_prompt raise, as before
+
 Stopped before the model was asked (prepare_turn returned false):
   → stopped_before_model(turn) → end_turn(turn, "canceled")
   → nothing kept, :turn_canceled {cancellation_reason, cancelled_by, duration_ms}
@@ -129,7 +141,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(@host_registry.resolve(@effective_model_name))
+Engine#backend → backend_for(effective_model)    # EffectiveModel.of(@host_registry, @model_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
 ```
@@ -326,6 +338,38 @@ TurnState
 
 The lock is a leaf: nothing is called out while it is held.
 
+### EffectiveModel (a snapshot per read)
+
+`EffectiveModel.of(registry, choice)` resolves the model once (`HostRegistry#resolve`: host, client, the id
+sent) with its lookup names, and reads each setting from them (sampling, thinking, reasoning history, steer cut,
+LLM context, window, price, served model, vision, profile). It is built per read and never kept: config.yml is
+read live, a model listing can move a bare id to another host, and another process's saved model lists change
+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 `#model_setting`. 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).
+- 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.
+- `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
+session's own value, the commands that move each chip, its chip from an EffectiveModel or from the Engine's
+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.
+
+### ThinkingNotices
+
+What a turn's thinking level leads to, said once per session and host (`thinking_notices.rb`): an effort the
+host can't do, off the model didn't honour, a host refusing the thinking fields or the reasoning sent back. It
+keeps the turn's `[level, ModelTarget]` and whether the generation thought; `turn_settings` and the stream handler
+call it. Turn thread only.
+
 ### Turn (Engine::Turn)
 
 The turn as the Engine sees it (the KernelLoop has its own `Turn` struct):
@@ -435,7 +479,7 @@ 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, @effective_model_name; @client = @host_registry.resolve(...).client
+  @host_registry, @model_choice (ModelChoice: the name and the name as typed); @client = effective_model.client
   @given_profile = profile or nil (resolved on first need, so building an Engine makes no network call)
   @hook_routes (HookRoutes: notices, hook questions, stop_turn/stop_generation, steer attribution)
   @guardrail_wiring, @question_desk
@@ -453,8 +497,9 @@ Engine initialization (in this order, among other things):
   @session_observer with the metrics, the log subscriber and the thinking tails subscribed (subscribe_session_observers)
 
 Model switching, Engine#switch_model!(model_name, persist_default:, typed:):
-  → checks the host (ModelProfile.check_host!), sets @effective_model_name
-  → drops the given profile and the profile resolution (resolved again on first need)
+  → checks the host (ModelProfile.check_host!), sets @model_choice (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)
   → sync_kernel_client! (the kernel talks to the new host), the context window cache dropped
   → the kernel is never rebuilt; the next turn's backend follows the new host's api
@@ -608,6 +653,10 @@ Paths are under `lib/samagotchi/`.
 | `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 |
+| `effective_model.rb` | `EffectiveModel` (the effective model's settings, a snapshot per read; `.of_session`), `ModelChoice`, the fallbacks' log lines (`Unresolved`) |
+| `session_setting.rb` | `SessionSetting`: the per-session settings' descriptors (own value, chips, the web's fallback) |
+| `level_setting_command.rb`, `thinking_command.rb`, `reasoning_history_command.rb` | `/thinking` and `/reasoning-history` (`LevelSettingCommand` and its two Specs) |
+| `thinking_notices.rb` | `ThinkingNotices`: the notices a turn's thinking level leads to |
 | `steer_cut_after.rb`, `cut_policy.rb` | The model's cut wait (`SteerCutAfter.resolve`); the loops' cut path (`CutPolicy`) |
 | `steer.rb` | Queued input and steers at iteration boundaries |
 | `kernel_loop.rb` | Native loop: `#run` (format, generate, parse, dispatch, iterate) |

data/docs/sessions.md

@@ -76,7 +76,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 - `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
 - Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again). A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). A file in a tool row (a read, edit or write's title) and its diff lines are refs: hover one and click to open the current file in your editor at that line, on this machine only (`web.editor`; the browser's "always allow" for the page's port and VS Code's "allow opening local files" are asked once; see [Opening files from chi web](configuration.md#opening-files-from-chi-web)). So are an edit or write approval card's paths (at the first line the dry run changes) and its diff lines, before you approve, and the numbered lines of a read's output: `lines 40–60` under it opens the text as read, numbered, when the output is the file as-is (not the head/tail preview of a big file, an error or an image; no numbers after a cut). A `path:line` (or `path:line-line`) in an answer or a step's text is one too once the turn has ended, and after a reload, when it names a file a row or card on the page touched: the path under the session's folder, else the one touched file it ends with (a bare `app.js:12` when only one touched file is named so; two such files make it none); a path without a line counts only when it is a touched file exactly. Code blocks, links, bare URLs and inline code with more than the ref in it are left alone, and a file the session didn't touch is never linked; a link whose text is such a ref alone (github-pr's link to the PR diff) becomes a ref too, and its plain click still goes to the PR. A plugin's refs on an answer (an `after_turn` hook's, see [Refs on the answer](hooks.md#refs-on-the-answer-display-only)) are paired with its links and text whatever the rows touched: they can link a file the session didn't touch, or an issue or a commit, and add their own actions to the ref's menu. A plugin tool's row carries the refs its `refs:` gives (see [Refs on a tool's row](plugins.md#refs-on-a-tools-row)): its title opens the first, and its `▾` menu adds the others as `<ref> · <action>` (the URL on hover); their URL actions work on a phone too. A ref with more than one target shows a small `▾` on hover: it opens a menu of them, in order **PR diff** (a link's), **Open in editor**, **Show in turn** and **Copy path**, and a plain click runs the first (a link's own, else the editor, else show in turn). **Show in turn** scrolls to the tool row that touched the file (looked for in the ref's own step, then its own turn, then the rows before it, then the nearest after it; there, the last one showing the ref's line, else the last one), opens the steps, the stage's steps and the row's diff (or the read showing the line) and flashes the row and the line; an answer's or a step's ref and an approval card's path have it, not a row's own title or lines. It needs no editor, so a viewer without one (a phone on the LAN) gets an answer's refs with **Show in turn** as their click; a row's title and diff lines stay plain text there. On a touch screen a tap opens the menu. A ref with a target is a tab stop: Enter runs its first target, ↓ opens the menu (↑/↓ move, Enter picks, Esc closes back to the ref). Diff and read lines have their click only. The info bar copies `chi --attach <id>` for a terminal. A session whose prompt carried model notes has a `notes: deepseek` chip there (the names without `model_notes_`; the tooltip lists each with its scope and size; `session.prompt_notes` in `GET /api/sessions/:id`, the live worker's, else the session file's; see [Memory](memory.md#model-notes)). Its `llm ctx` chip names the LLM context strategy the next turn runs under (`llm ctx stale,forget · session`, in the accent colour when the session set its own; the tooltip gives each value's source), and its popover sets the session's own strategy, apply rule and budget, or follows the model again, by running `/llm-context` in the worker (the reply shows as a command bubble); `GET /api/sessions/:id`'s `session.llm_context` carries the values (the live worker's, else resolved from the session file), and a `command_ran` that changed them carries the new ones. Its `think` chip does the same for the thinking level (`/thinking`), and on a chat host its `reasoning` chip for the reasoning history (`reasoning all · session`, `/reasoning-history`; `session.reasoning_history`, null on a native host). A `/thinking` or `/reasoning-history` change that restarts the prompt cache asks first: the reply bubble has an **Apply (restarts the cache)** button that sends its `--yes` line (the chips' Set sends that line itself; see [Changes that restart the prompt cache](configuration.md#changes-that-restart-the-prompt-cache)). It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only (one estimated from a `hosts.<name>.models` price shows with `~`: `cost: ~$0.54 ($0.42 reported, ~$0.12 estimated)`), and the memory indexes its prompt holds (`memory index: ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`; see [Memory](memory.md#the-indexs-size)). The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first (an id the host declares under `hosts.<name>.models` first, noted `config`, its tooltip `served by config (hosts.<name>.models)`; a host that failed to list its models keeps those ids, greyed and noted `host down`, still pickable; a remembered or default model stays chosen even then, greyed on the button); typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, configured?, unavailable?, sampling?, llm_context?}], warning?}`; `configured: true` marks an id declared under `hosts.<name>.models`, listed first under its host, `unavailable: true` one whose host failed to list its models; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). Beside it, an `llm ctx` chip shows the LLM context the picked model starts under (each `GET /api/models` row's `llm_context`, as the info bar's); its form sets one for the new chat only, sent as `POST /api/sessions`'s `llm_context` and never remembered (see [configuration.md](configuration.md#llm-context-a-sessions-own-strategy)). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last model picked; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
 - Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
-- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it; `families()` groups delegates under their parent), `families_view.js` (a parent's family chip, its rows and the strip's popover; the chip and rows as lit-html templates), `keep_focus.js` (lit reuses a list's nodes by position: a redraw keeps the focus on the same item by its `data-id` / `data-name`), `chains.js` (session chains: the links from `continues`, the cards folded into the latest link's, its `day N` chip and rows as lit-html templates, the info bar's ← → links, a refused continue), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history), `commands.js` (session commands: which composer lines are commands, the page's own replies, a `command_ran`'s bubble, the page's command bubbles kept across a re-read), `composer.js` (where a composer line goes, `routeComposerLine`: /cut and /queue, the start page's own replies, a session command or `!cmd`, a typo hint, else a turn; and a session command sent from the composer or a chip), `delivery_line.js` (the composer's row above the text field in a session, always there so the composer keeps its height: the key hint while idle, and the delivery line while a turn runs: where a message typed now goes in, from the step's phase, clock and size, whether "cut in now" can land, and the queue link for a worker with the `delivery` feature, as a pure `deliveryLine`, its lit-html template and `createDeliveryControl`, which ticks it and keeps a choice armed from a link; see docs/cli.md, "Typing during a turn"), `restore.js` (a failed turn's prompt handed back into this tab's composer, before or after its `/turn` ack), `lists_view.js` (the session lists: the strip and its pill, all sessions with its search, count and select mode, their cards, the family and chain popovers; the cards, tile and pill as lit-html templates, drawn as new nodes each time, and the lists' orders as pure functions), `stream_handlers.js` (the open session's stream event handlers, by event type, over the page's views and hooks; a snapshot replays through them too), `info_bar.js` (the session bar's info line as a lit-html template over a plain model: id, status, model, chain links, chips, ctx, speed, clock, worker badge), `session_state.js` (what the page knows about the open session: its empty state, and `sessionStateFrom`, the fields a `GET /sessions/:id` payload sets), `refs.js` (refs: a kind and a target on the element, a plugin's ref data (label, http(s) URL actions) bound in a WeakMap by `bindRef`, the targets per kind, show in turn, one delegated set of click, key and hover listeners), `ref_menu.js` (a ref's `▾` and its menu), `ref_scan.js` (the `path:line` refs in an answer's or a step's text that name a file the session's rows touched), `answer_refs.js` (the refs a plugin attached to an answer, its `display_refs`: bound to the answer's bubble, paired with its links and text, bound with `bindRef`). Unit-tested via `npm test` (`spec/web/public/*.test.js`).
+- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it; `families()` groups delegates under their parent), `families_view.js` (a parent's family chip, its rows and the strip's popover; the chip and rows as lit-html templates), `keep_focus.js` (lit reuses a list's nodes by position: a redraw keeps the focus on the same item by its `data-id` / `data-name`), `chains.js` (session chains: the links from `continues`, the cards folded into the latest link's, its `day N` chip and rows as lit-html templates, the info bar's ← → links, a refused continue), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `bubbles.js` (the history's bubbles between the turns' rows: output chunks, end lines, every client's prompt bubbles by `enqueued_id` with their queued/steered badges, the idle recap, guardrail warnings, hooks' notices, plugins' steers, command and note bubbles; lit-html templates, put in the history with the sticky follow by `createBubbles`), `cards_place.js` (where plugin cards and a snapshot's notices go in the history: a card added or updated in place by its id, a running turn's into its step, a snapshot's each above the first turn after it, a finished turn's notice in its step's rows and its question resolved where it was asked; a card's action buttons), `format.js` (pure formatters such as `previewOf`), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history), `commands.js` (session commands: which composer lines are commands, the page's own replies, a `command_ran`'s bubble, the page's command bubbles kept across a re-read), `composer.js` (where a composer line goes, `routeComposerLine`: /cut and /queue, the start page's own replies, a session command or `!cmd`, a typo hint, else a turn; and a session command sent from the composer or a chip), `delivery_line.js` (the composer's row above the text field in a session, always there so the composer keeps its height: the key hint while idle, and the delivery line while a turn runs: where a message typed now goes in, from the step's phase, clock and size, whether "cut in now" can land, and the queue link for a worker with the `delivery` feature, as a pure `deliveryLine`, its lit-html template and `createDeliveryControl`, which ticks it and keeps a choice armed from a link; see docs/cli.md, "Typing during a turn"), `restore.js` (a failed turn's prompt handed back into this tab's composer, before or after its `/turn` ack), `lists_view.js` (the session lists: the strip and its pill, all sessions with its search, count and select mode, their cards, the family and chain popovers; the cards, tile and pill as lit-html templates, drawn as new nodes each time, and the lists' orders as pure functions), `stream_handlers.js` (the open session's stream event handlers, by event type, over the page's views and hooks; a snapshot replays through them too), `stage_view.js` (the stage view: the running turn pinned above the composer, then handed off into the history; its pure rules and texts in `stage_model.js`, its live slots (headline, now row, trail, ticks) in `stage_slots.js`, its cap and held height in `stage_frame.js`, the in-use watch that times the hand-off in `stage_watch.js`), `info_bar.js` (the session bar's info line as a lit-html template over a plain model: id, status, model, chain links, chips, ctx, speed, clock, worker badge), `info_bar_model.js` (that model and the bar's buttons' states, built from the page's session state, its list and its in-flight continues and restarts as pure functions; `app.js`'s `updateInfoBar` applies them every second while a turn runs), `session_state.js` (what the page knows about the open session: its empty state, and `sessionStateFrom`, the fields a `GET /sessions/:id` payload sets), `refs.js` (refs: a kind and a target on the element, a plugin's ref data (label, http(s) URL actions) bound in a WeakMap by `bindRef`, the targets per kind, show in turn, one delegated set of click, key and hover listeners), `ref_menu.js` (a ref's `▾` and its menu), `ref_scan.js` (the `path:line` refs in an answer's or a step's text that name a file the session's rows touched), `answer_refs.js` (the refs a plugin attached to an answer, its `display_refs`: bound to the answer's bubble, paired with its links and text, bound with `bindRef`). Unit-tested via `npm test` (`spec/web/public/*.test.js`).
 - Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).
 
 **Test-session hygiene:**

data/docs/testing.md

@@ -17,7 +17,7 @@ clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (We
 
 The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_view.js`,
 `turn_html.js`, `card.js`, `copy.js`, `images.js`, `scope.js`, `command_view.js`, `diff_view.js`, `read_view.js`,
-`question_cards.js`, `stream_handlers.js`, the chips, `info_bar.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
+`question_cards.js`, `stream_handlers.js`, `stage_view.js`, `bubbles.js`, `cards_place.js`, the chips, `info_bar.js`, `info_bar_model.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
 `chains.js`, `vendor/lit-html.js`) needs a DOM: `import "./dom_shim.js";` as its first import (happy-dom, a devDependency only,
 never shipped; lit reads `document` as it loads). The shim's `markupOf(template)`,
 `htmlOf(nodes)` and `canon(html)` compare markup without lit's marker comments; the DOM writes text with only `&`, `<`, `>`

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.67.0
+version: 0.68.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/effective_model.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require_relative "host_registry"
+require_relative "log"
+require_relative "context_window"
+require_relative "llm_context_strategy"
+require_relative "model_profile"
+require_relative "reasoning_history"
+require_relative "sampling_settings"
+require_relative "served_model"
+require_relative "steer_cut"
+require_relative "steer_cut_after"
+require_relative "thinking"
+require_relative "vision_support"
+
+module Samagotchi
+  # The model a session runs on, as set: the name (maybe an alias;
+  # HostRegistry#resolve applies it) and the name as typed at start or at
+  # the last /model. One value, swapped in one assignment, so a reader on
+  # another thread never pairs one model's name with another's typed name.
+  ModelChoice = Data.define(:name, :typed)
+
+  # The effective model resolved once (HostRegistry#resolve: its host and
+  # client, the id sent) with the names its models: entry may be under
+  # (HostRegistry#lookup_names), and its settings read from them. An
+  # immutable snapshot built per read, never kept across reads: config.yml,
+  # a model listing (which may move a bare id to another host) and another
+  # process's saved lists all change what a resolve gives without any
+  # /model. Frozen, so any thread may hold one.
+  #
+  # Each setting reader rescues its own failure and gives the fallback the
+  # Engine has always given (Unresolved); building one raises as
+  # HostRegistry#resolve does (the Engine's #model_setting gives the
+  # fallback then).
+  EffectiveModel = Data.define(:registry, :name, :typed, :target, :names) do
+    # @param registry [HostRegistry]
+    # @param choice [ModelChoice]
+    # @raise what HostRegistry#resolve raises
+    def self.of(registry, choice)
+      target = registry.resolve(choice.name)
+      new(registry: registry, name: choice.name, typed: choice.typed, target: target,
+          names: registry.lookup_names(choice.typed, resolved: choice.name, target: target))
+    end
+
+    # A saved session's model (no worker): its model name, the default when
+    # blank, and the name it was typed as.
+    # @param session [Session]
+    def self.of_session(session, registry:)
+      name = session.model_name.to_s.strip.empty? ? ModelProfile.required_model_name(nil) : session.model_name
+      of(registry, ModelChoice.new(name: name, typed: session.model_typed || name))
+    end
+
+    def entry = target.entry
+    def client = target.client
+    def bare = target.bare_model
+    def host_name = entry.name
+
+    # A chat host (api: openai or anthropic), whose loop uses no prompt profile.
+    def chat? = entry.chat?
+
+    # The resolved ref a session stores (ModelRef#ref): no resolve.
+    def ref = registry.model_ref(name).ref
+
+    # The configured request parameters (hosts: and models: sampling).
+    def sampling
+      SamplingSettings.for(target, names: names)
+    rescue StandardError => e
+      unresolved(:sampling_unresolved, e, SamplingSettings::EMPTY)
+    end
+
+    # "temperature=0.6 (hosts.work)", nil when none.
+    def sampling_summary
+      SamplingSettings.summary(target, names: names)
+    rescue StandardError => e
+      unresolved(:sampling_unresolved, e, nil)
+    end
+
+    # The thinking level (Thinking.resolve), the session's +own+ first.
+    def thinking(own:)
+      Thinking.resolve(target, names: names, session: own).first
+    rescue StandardError => e
+      unresolved(:thinking_unresolved, e, Thinking::DEFAULT)
+    end
+
+    # The thinking level with where it came from (SettingExplained), nil
+    # when it can't be resolved.
+    def thinking_explained(own:)
+      Thinking.explain(target, names: names, session: own)
+    rescue StandardError => e
+      unresolved(:thinking_unresolved, e, nil)
+    end
+
+    # What a thinking level change costs the prompt cache
+    # (Thinking.cache_cost); the block gives the prompt profile, asked only
+    # on a native host. Raises.
+    # @return [Symbol]
+    def thinking_cache_cost(&)
+      Thinking.cache_cost(target, profile: entry&.chat? ? nil : yield&.name)
+    end
+
+    # The reasoning_history level (ReasoningHistory.resolve), the session's
+    # +own+ first.
+    def reasoning_history(own:)
+      ReasoningHistory.resolve(target, names: names, session: own).first
+    rescue StandardError => e
+      unresolved(:reasoning_history_unresolved, e, ReasoningHistory::DEFAULT)
+    end
+
+    # The reasoning_history level with where it came from (SettingExplained);
+    # nil on a native host unless +native+ (its loop ignores the level), or
+    # when it can't be resolved.
+    def reasoning_history_explained(own:, native: false)
+      return nil unless native || entry&.chat?
+
+      ReasoningHistory.explain(target, names: names, session: own)
+    rescue StandardError => e
+      unresolved(:reasoning_history_unresolved, e, nil)
+    end
+
+    # "drop (models: qwen)"; nil for the default, on a native host, or when
+    # it can't be resolved.
+    def reasoning_history_summary(own:)
+      return nil unless entry&.chat?
+
+      level, source = ReasoningHistory.resolve(target, names: names, session: own)
+      source ? ReasoningHistory.label(level, source) : nil
+    rescue StandardError => e
+      unresolved(:reasoning_history_unresolved, e, nil)
+    end
+
+    # What a reasoning_history change from +from+ to +to+ costs the prompt
+    # cache, given +conversation+ (ReasoningHistory.cache_cost).
+    def reasoning_history_cache_cost(from, to, conversation:)
+      ReasoningHistory.cache_cost(from, to, target: target, conversation: conversation)
+    rescue StandardError => e
+      unresolved(:reasoning_history_unresolved, e, nil)
+    end
+
+    # [seconds, source] a cut waits for thinking (SteerCutAfter.resolve);
+    # the global and its name when it can't be resolved.
+    def steer_cut_after_explained
+      SteerCutAfter.resolve(target, names: names)
+    rescue StandardError => e
+      unresolved(:steer_cut_after_unresolved, e, [SteerCut.cut_after, "steer.cut_after"])
+    end
+
+    # The LLM context strategy with where each value came from
+    # (LLMContextStrategy.explain) under the session's +args+
+    # (LLMContextOverride#resolve_args), nil when it can't be resolved.
+    def llm_context_explained(args)
+      LLMContextStrategy.explain(target, names: names, **args)
+    rescue StandardError => e
+      unresolved(:llm_context_unresolved, e, nil)
+    end
+
+    # The LLM context layers its turns run under; [] when they can't be
+    # resolved.
+    def llm_context_layers(args)
+      LLMContextStrategy.resolve(target, names: names, **args).active_layers
+    rescue StandardError => e
+      unresolved(:llm_context_unresolved, e, [])
+    end
+
+    # models:/hosts: window_tokens (ContextWindow.setting), nil when unset.
+    def window_setting
+      ContextWindow.setting(target, names: names)
+    rescue StandardError => e
+      unresolved(:window_unresolved, e, nil)
+    end
+
+    # The window as its loop would see it (ChatLoop#context_window: a remote
+    # chat host has no /props, only its model list); nil when it can't be
+    # resolved.
+    def context_window
+      client = self.client
+      adapter = nil
+      if entry.chat?
+        adapter = registry.adapter_for(entry)
+        client = nil if adapter.remote?
+      end
+      ContextWindow.resolve(client: client, model: bare, adapter: adapter, setting: ContextWindow.setting(target, names: names))
+    rescue StandardError => e
+      unresolved(:window_unresolved, e, nil)
+    end
+
+    # Its price on its host (hosts.<name>.models.<id>.price), by the id
+    # asked for, never the one served; nil when none.
+    def price
+      entry.models&.dig(bare.to_s.strip.downcase)&.price
+    rescue StandardError => e
+      unresolved(:price_unresolved, e, nil)
+    end
+
+    # [served, +asked+] from llama.cpp's /props (one short cached probe),
+    # [nil, nil] for a remote chat host, without an answer, or when it
+    # can't be asked.
+    def served_from_props(asked)
+      if entry.chat? && registry.adapter_for(entry).remote?
+        return [nil, nil]
+      end
+
+      served = ServedModel.from_props(client.server_props(model: bare))
+      served ? [served, asked] : [nil, nil]
+    rescue StandardError => e
+      # The model resolved; asking its server failed (its /props, its adapter).
+      unresolved(:served_probe_failed, e, [nil, nil])
+    end
+
+    # The host whose hosts.<name>.models.<id>.served names +served+
+    # (ServedModel.expected_by), nil when none does.
+    def served_expected_by(served)
+      ServedModel.expected_by(target, served)
+    rescue StandardError => e
+      unresolved(:served_unresolved, e, nil)
+    end
+
+    # What a local native host's cached /props names when it isn't the
+    # model asked for; nil for a chat or remote host, or before any probe.
+    def prompt_served
+      return nil if entry.nil? || entry.chat? || entry.remote? || !client.respond_to?(:cached_server_props)
+
+      served = ServedModel.from_props(client.cached_server_props(model: bare))
+      served if ServedModel.differs?(bare, served)
+    rescue StandardError => e
+      unresolved(:served_unresolved, e, nil)
+    end
+
+    # Whether it sees images (VisionSupport.for) under +profile+.
+    def vision_support(profile)
+      VisionSupport.for(target, profile: profile, adapter: vision_adapter, names: names)
+    end
+
+    # A chat host's adapter (what it says of images), nil on a native host.
+    def vision_adapter
+      entry.chat? ? registry.adapter_for(entry) : nil
+    rescue StandardError => e
+      unresolved(:vision_adapter_unresolved, e, nil)
+    end
+
+    # Which prompt profile it gets (ModelProfile.resolve: may probe /props).
+    # Not cached here. Raises.
+    # @return [ModelProfile::Resolution]
+    def profile_resolution
+      ModelProfile.resolve(names: names, entry: entry, client: client, bare_model: bare)
+    end
+
+    # See Unresolved.fallback.
+    def unresolved(event, error, value) = EffectiveModel::Unresolved.fallback(event, self, error, value)
+    private :unresolved
+
+    # The name, typed name and host only: the default would print the
+    # registry and the client into any error message.
+    def inspect = "#<Samagotchi::EffectiveModel #{name.inspect} typed=#{typed.inspect} host=#{entry&.name.inspect}>"
+    alias_method :to_s, :inspect
+  end
+
+  class EffectiveModel
+    # The fallback an effective model's reader gives when its setting
+    # can't be resolved, with a log line: WARN the first time per process
+    # for an (event, model, error class), DEBUG after. The session state is
+    # read on every Bridge /state and SSE reset, so a broken host config
+    # would otherwise WARN per poll.
+    module Unresolved
+      @seen = Set.new
+      @mutex = Mutex.new
+
+      # @param event [Symbol] the log event (<setting>_unresolved)
+      # @param model [EffectiveModel, String] the model (or its name)
+      # @param error [StandardError]
+      # @return +value+
+      def self.fallback(event, model, error, value)
+        name = model.respond_to?(:name) ? model.name : model.to_s
+        first = @mutex.synchronize { @seen.add?([event, name, error.class.name]) }
+        fields = { model: name, error: error.class.name, msg: error.message.to_s[0, 200] }
+        first ? Log.warn(:model, event.to_s, **fields) : Log.debug(:model, event.to_s, **fields)
+        value
+      end
+
+      # Forget what was logged (specs).
+      def self.reset! = @mutex.synchronize { @seen.clear }
+    end
+  end
+end