fix(agent): rebuild provider on preset switch

fix(config): warn on legacy model migration
fix(config): enforce preset-only model selection
2026-08-08 13:28:43 +03:00 · 2026-07-29 01:41:28 +08:00 · 2026-07-29 01:11:41 +08:00 · 2026-07-29 00:46:23 +08:00 · 2026-07-29 00:02:21 +08:00 · 2026-07-28 20:24:52 +08:00
180 changed files with 11777 additions and 2815 deletions
@@ -33,13 +33,20 @@ jobs:
        id: paths
        shell: bash
        env:
+          EVENT_NAME: ${{ github.event_name }}
          BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
-          HEAD_SHA: ${{ github.sha }}
+          HEAD_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
        run: |
          python_required=true

+          if [[ "$EVENT_NAME" == "pull_request" ]]; then
+            diff_range="${BASE_SHA}...${HEAD_SHA}"
+          else
+            diff_range="${BASE_SHA}..${HEAD_SHA}"
+          fi
+
          if git cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null &&
-            changed_files="$(git diff --name-only --no-renames "$BASE_SHA" "$HEAD_SHA")" &&
+            changed_files="$(git diff --name-only --no-renames "$diff_range")" &&
            [[ -n "$changed_files" ]] &&
            ! grep -qvE '^(webui/|nanobot/channels/[^/]+/webui/|docs/)' <<< "$changed_files"; then
            python_required=false
@@ -17,24 +17,24 @@
    <a href="https://nanobot.wiki/vi/docs/latest/getting-started/nanobot-overview">Tiếng Việt</a>
  </p>
  <p>
-    <a href="https://pypi.org/project/nanobot-ai/"><img src="https://img.shields.io/pypi/v/nanobot-ai" alt="PyPI"></a>
-    <a href="https://pepy.tech/project/nanobot-ai"><img src="https://static.pepy.tech/badge/nanobot-ai" alt="Downloads"></a>
-    <img src="https://img.shields.io/badge/python-≥3.11-blue" alt="Python">
-    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
-    <a href="https://github.com/HKUDS/nanobot/graphs/commit-activity" target="_blank">
-        <img alt="Commits last month" src="https://img.shields.io/github/commit-activity/m/HKUDS/nanobot?labelColor=%20%2332b583&color=%20%2312b76a"></a>
-    <a href="https://github.com/HKUDS/nanobot/issues?q=is%3Aissue%20is%3Aclosed" target="_blank">
-        <img alt="Issues closed" src="https://img.shields.io/github/issues-search?query=repo%3AHKUDS%2Fnanobot%20is%3Aissue%20is%3Aclosed&label=issues%20closed&labelColor=%20%237d89b0&color=%20%235d6b98"></a>
-    <a href="https://twitter.com/intent/follow?screen_name=nanobot_project" target="_blank">
-        <img src="https://img.shields.io/twitter/follow/nanobot_project?logo=X&color=%20%23f5f5f5" alt="follow on X(Twitter)"></a>
-    <a href="https://nanobot.wiki/docs/latest/getting-started/nanobot-overview"><img src="https://img.shields.io/badge/Docs-nanobot.wiki-blue?style=flat&logo=readthedocs&logoColor=white" alt="Docs"></a>
-    <a href="./COMMUNICATION.md"><img src="https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white" alt="Feishu"></a>
-    <a href="./COMMUNICATION.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat"></a>
-    <a href="https://discord.gg/MnCvHqpUGB"><img src="https://img.shields.io/badge/Discord-Community-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
+    <a href="https://github.com/HKUDS/nanobot"><img src="https://img.shields.io/github/stars/HKUDS/nanobot?style=flat&logo=github" alt="GitHub stars"></a>
+    <a href="https://pypi.org/project/nanobot-ai/"><img src="https://img.shields.io/pypi/v/nanobot-ai" alt="PyPI version"></a>
+    <a href="https://pepy.tech/project/nanobot-ai"><img src="https://static.pepy.tech/badge/nanobot-ai" alt="PyPI downloads"></a>
+    <a href="https://github.com/HKUDS/nanobot/actions/workflows/ci.yml"><img src="https://github.com/HKUDS/nanobot/actions/workflows/ci.yml/badge.svg?branch=main" alt="Test Suite"></a>
+    <a href="https://pypi.org/project/nanobot-ai/"><img src="https://img.shields.io/badge/python-%3E%3D3.11-blue" alt="Python 3.11 or newer"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/github/license/HKUDS/nanobot" alt="MIT License"></a>
+    <a href="https://nanobot.wiki/docs/latest/getting-started/nanobot-overview"><img src="https://img.shields.io/badge/docs-nanobot.wiki-blue" alt="nanobot documentation"></a>
+  </p>
+  <p>
+    <a href="https://discord.gg/MnCvHqpUGB">Discord</a> ·
+    <a href="https://x.com/nanobot_project">X</a> ·
+    <a href="./COMMUNICATION.md">WeChat / Feishu</a>
  </p>
 </div>

-🐈 **nanobot** is an open-source, ultra-lightweight personal AI agent you can truly own. It keeps the agent core small and readable while giving you the practical pieces for real long-running work: WebUI, chat channels, tools, memory, MCP, model routing, automation, and deployment.
+# nanobot
+
+🐈 **nanobot** is an ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python. It runs in a WebUI, terminal, or chat apps and combines tools, long-term memory, MCP integrations, model routing, multi-agent delegation, scheduled automation, and an OpenAI-compatible API in a small, readable core.

 ## Start Here

@@ -46,7 +46,7 @@
 | Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, or another chat app | [Chat Apps](./docs/chat-apps.md) |
 | Configure providers, fallback models, Langfuse, MCP, web tools, or security | [Docs](./docs/README.md) and [Configuration](./docs/configuration.md) |
 | Understand or extend the internals | [Architecture](./docs/architecture.md) and [Development](./docs/development.md) |
-| Deploy to the cloud or keep nanobot running as a service | [Deployment](./docs/deployment.md), including [one-click Render setup](./docs/deployment.md#render) |
+| Deploy to the cloud or keep nanobot running as a service | [Deployment](./docs/deployment.md) |

 ## What can nanobot do?

@@ -60,36 +60,6 @@ nanobot is a self-hosted personal AI agent runtime. It can:
 - expose a Python SDK and OpenAI-compatible API for integrations
 - deploy as a long-running local or server-side agent gateway

-## Releases
-
-**Latest release: [v0.3.0 - The Agency Release](https://github.com/HKUDS/nanobot/releases/tag/v0.3.0)**
-
-The Agency Release turns nanobot from a durable workbench into an agent runtime that can coordinate helpers, switch models per session, and carry authorized work through to completion.
-
- Consult inline subagents without leaving the current task
- Switch model presets per session directly from the composer
- Start from a guided WebUI setup with clearer execution controls
- Apply configuration changes live across a more reliable provider, channel, and tool runtime
-
-[Read the v0.3.0 release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.3.0)
-
-## Open Source Partners
-
-<p align="center">
-  <a href="https://platform.kimi.com?aff=nanobot"><picture><source media="(prefers-color-scheme: dark)" srcset="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69mt3v89kkekg24gg"><img alt="Kimi Open Source Friends" height="44" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0"></picture></a>
-  <a href="https://platform.minimaxi.com/subscribe/token-plan?code=GILTJpMTqZ&source=link"><img alt="MiniMax" height="40" src="https://mintcdn.com/minimax-zh/1UjvBcdoC6r0UeyA/logo/light.svg?fit=max&auto=format&n=1UjvBcdoC6r0UeyA&q=85&s=672d724b639b2d88d0702fae329ea4f8"></a>
-</p>
-
-## Recent Updates
-
- **2026-07-24** Guided first-run setup, inline subagents, and model switching from the composer.
- **2026-07-23** Grok OAuth with hosted X Search, live image settings, and clearer fallback models.
- **2026-07-22** Parallel Search, live configuration reloads, richer app discovery, and a smoother mobile WebUI.
- **2026-07-21** Codex fast mode, visible skill references, safer configuration saves, and sturdier task cleanup.
- **2026-07-20** Cleaner code blocks and copy actions, self-contained channels, and steadier QQ reconnects.
-
-For older updates, see the [release archive](./docs/release-archive.md) or [GitHub releases](https://github.com/HKUDS/nanobot/releases).
-
 ## 💡 Why nanobot

 - **Persistent workflows**: goals, memory, tools, and chat context survive long-running work.
@@ -244,6 +214,8 @@ The one-shot form is useful for a quick provider check, shell scripts, and local

 Need manual JSON, another device on your LAN, or help with provider/model matching? Continue with [Install and Quick Start](./docs/quick-start.md), [WebUI](./docs/webui.md), or [Troubleshooting](./docs/troubleshooting.md).

+If nanobot worked for you, a star on GitHub is the simplest way to support the project.
+
 - Want a pasteable provider setup? See [Provider Cookbook](./docs/provider-cookbook.md)
 - Want to understand provider/model matching? See [Providers and Models](./docs/providers.md)
 - Want web search, MCP, security settings, or more config options? See [Configuration](./docs/configuration.md)
@@ -251,6 +223,22 @@ Need manual JSON, another device on your LAN, or help with provider/model matchi
 - Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See [Chat Apps](./docs/chat-apps.md)
 - Want Docker or Linux service deployment? See [Deployment](./docs/deployment.md)

+<a id="deploy-to-render"></a>
+
+## ☁️ Deploy
+
+**Render — one click**
+
+Deploy nanobot's gateway and bundled WebUI from the repository's ready-to-use Blueprint:
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/HKUDS/nanobot)
+
+Render will ask for `ANTHROPIC_API_KEY` and a private `NANOBOT_WEB_TOKEN`, then provision persistent storage for sessions, memory, and WebUI history. Persistent disks require a paid Render service.
+
+**Self-host**
+
+Prefer your own infrastructure? Follow the [deployment guide](./docs/deployment.md) for Docker, Docker Compose, Linux services, and macOS LaunchAgent setup.
+
 ## 🌐 WebUI

 The WebUI ships **inside the published wheel** with no separate frontend build. It is the browser workbench for persistent topics, visible agent activity, workspace controls, Apps, Skills, Automations, and settings.
@@ -276,29 +264,6 @@ See the [WebUI guide](./docs/webui.md) for LAN access, background operation, wor

 🐈 nanobot stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith.

-## ✨ Features
-
-<table align="center">
-  <tr align="center">
-    <th><p align="center">📈 24/7 Real-Time Market Analysis</p></th>
-    <th><p align="center">🚀 Full-Stack Software Engineer</p></th>
-    <th><p align="center">📅 Smart Daily Routine Manager</p></th>
-    <th><p align="center">📚 Personal Knowledge Assistant</p></th>
-  </tr>
-  <tr>
-    <td align="center"><p align="center"><img src="case/search.gif" width="180" height="400"></p></td>
-    <td align="center"><p align="center"><img src="case/code.gif" width="180" height="400"></p></td>
-    <td align="center"><p align="center"><img src="case/schedule.gif" width="180" height="400"></p></td>
-    <td align="center"><p align="center"><img src="case/memory.gif" width="180" height="400"></p></td>
-  </tr>
-  <tr>
-    <td align="center">Discovery • Insights • Trends</td>
-    <td align="center">Develop • Deploy • Scale</td>
-    <td align="center">Schedule • Automate • Organize</td>
-    <td align="center">Learn • Memory • Reasoning</td>
-  </tr>
-</table>
-
 ## 📚 Docs

 Browse the [repo docs](./docs/README.md) for the latest features and GitHub development version, or visit [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) for the stable release documentation.
@@ -317,21 +282,43 @@ Browse the [repo docs](./docs/README.md) for the latest features and GitHub deve
 - Integrate nanobot with local tools and automations: [OpenAI-Compatible API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md)
 - Run nanobot with Docker or as a Linux service: [Deployment](./docs/deployment.md)

-## 🤝 Contribute & Roadmap
+## Releases

-PRs welcome! The codebase is intentionally small and readable. 🤗
+**Latest release: [v0.3.0 - The Agency Release](https://github.com/HKUDS/nanobot/releases/tag/v0.3.0)**

-### Contribution Flow
+The Agency Release turns nanobot from a durable workbench into an agent runtime that can coordinate helpers, switch models per session, and carry authorized work through to completion.

-See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, review, and contribution guidelines.
+- Consult inline subagents without leaving the current task
+- Switch model presets per session directly from the composer
+- Start from a guided WebUI setup with clearer execution controls
+- Apply configuration changes live across a more reliable provider, channel, and tool runtime

-**Roadmap** — Pick an item and [open a PR](https://github.com/HKUDS/nanobot/pulls)!
+[Read the v0.3.0 release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.3.0)

- **Multi-modal** — See and hear (images, voice, video)
- **Long-term memory** — Never forget important context
- **Better reasoning** — Multi-step planning and reflection
- **More integrations** — Calendar and more
- **Self-improvement** — Learn from feedback and mistakes
+## Recent Updates
+
+- **2026-07-24** Guided first-run setup, inline subagents, and model switching from the composer.
+- **2026-07-23** Grok OAuth with hosted X Search, live image settings, and clearer fallback models.
+- **2026-07-22** Parallel Search, live configuration reloads, richer app discovery, and a smoother mobile WebUI.
+- **2026-07-21** Codex fast mode, visible skill references, safer configuration saves, and sturdier task cleanup.
+- **2026-07-20** Cleaner code blocks and copy actions, self-contained channels, and steadier QQ reconnects.
+
+For older updates, see the [release archive](./docs/release-archive.md) or [GitHub releases](https://github.com/HKUDS/nanobot/releases).
+
+## Open Source Partners
+
+<p align="center">
+  <a href="https://platform.kimi.com?aff=nanobot"><picture><source media="(prefers-color-scheme: dark)" srcset="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69mt3v89kkekg24gg"><img alt="Kimi Open Source Friends" height="44" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0"></picture></a>
+  <a href="https://platform.minimaxi.com/subscribe/token-plan?code=GILTJpMTqZ&source=link"><img alt="MiniMax" height="40" src="https://mintcdn.com/minimax-zh/1UjvBcdoC6r0UeyA/logo/light.svg?fit=max&auto=format&n=1UjvBcdoC6r0UeyA&q=85&s=672d724b639b2d88d0702fae329ea4f8"></a>
+</p>
+
+## 🤝 Contribute
+
+Use nanobot for a real task, report what broke, and then pick a focused improvement.
+
+- Read [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow.
+- Browse [open issues](https://github.com/HKUDS/nanobot/issues) for problems to investigate.
+- Open a [pull request](https://github.com/HKUDS/nanobot/pulls) for a focused fix or integration.

 ## Contact

@@ -59,7 +59,7 @@ Provider metadata is centralized in `nanobot/providers/registry.py`. Configurati

 Provider selection uses:

- explicit `agents.defaults.provider` or preset provider;
+- the active model preset's explicit provider;
 - provider registry keywords;
 - API key prefixes and API base URL hints;
 - local provider fallback when `apiBase` is configured;
@@ -137,13 +137,6 @@ message. Copy the `nanobot trigger ...` command from the WebUI and replace
 Automation delivery is workspace-local. Scheduled jobs and local trigger
 deliveries use the same workspace as the gateway.

-WebUI automation replies are written to the linked topic even when no browser
-is connected. When the WebUI is opened again, it replays the stored reply and
-compares the topic's durable activity time with its persisted read position to
-show **New activity**. A successful automation `lastStatus` means the agent turn
-completed; it does not mean a browser had a live WebSocket connection or that
-the user already read the reply.
-
 Local trigger messages are written to a durable queue. If the gateway is not
 running yet, the message waits in that workspace. If the linked topic is
 already running a turn, the trigger waits until the session becomes idle instead
@@ -57,7 +57,7 @@ To switch presets for future turns:
 /model default
 ```

-Preset names come from the top-level `modelPresets` config. Switching affects only the current session and persists the selection in that session, so later turns keep using it across process restarts. It does not rewrite `config.json`, does not change other sessions, and does not alter an in-progress turn's captured model. Sessions without a saved selection follow `agents.defaults.modelPreset` (or the implicit `default` preset when it is omitted). See [Configuration: Model presets](./configuration.md#model-presets) for setup details.
+Preset names come from the top-level `modelPresets` config. Switching affects only the current session and persists the selection in that session, so later turns keep using it across process restarts. It does not rewrite `config.json`, does not change other sessions, and does not alter an in-progress turn's captured model. Sessions without a saved selection follow `agents.defaults.modelPreset`, or the concrete `modelPresets.default` entry when it is omitted. See [Configuration: Model presets](./configuration.md#model-presets) for setup details.

 ## Local triggers

@@ -11,7 +11,7 @@ Use this page when you know what you want to run and need the command shape. For
 | Refresh config non-interactively | `nanobot onboard --refresh` | Preserves existing values and adds missing default fields without prompting |
 | Use guided setup | `nanobot onboard --wizard` | Best when you prefer prompts over hand-editing JSON |
 | Open the browser workbench | `nanobot webui` | Prepares local WebUI settings, starts the gateway, and opens the browser |
-| Check config without calling a model | `nanobot status` | Summarizes the selected config, workspace, active model, and providers |
+| Check readiness without calling a model | `nanobot status` | Summarizes config/workspace and validates the active provider/model configuration |
 | Send one test message | `nanobot agent -m "Hello!"` | First proof that install, config, provider, model, and workspace all work |
 | Chat in the terminal | `nanobot agent` | Interactive local chat; exit with `exit`, `/exit`, `:q`, or `Ctrl+D` |
 | Run the gateway directly | `nanobot gateway` | Service/ops command for WebUI, chat apps, cron, and heartbeat |
@@ -70,6 +70,18 @@ Default paths:
 | Config | `~/.nanobot/config.json` |
 | Workspace | `~/.nanobot/workspace/` |

+## Status
+
+| Command | Description |
+|---|---|
+| `nanobot status` | Summarize the default config/workspace and check Agent provider/model readiness |
+| `nanobot status --config <path>` | Check a specific config file |
+| `nanobot status --workspace <path>` | Show status with a workspace override |
+
+Status does not send a model request. On success, run the printed
+`nanobot agent -m "Hello!"` command to verify network access and credentials. On failure,
+follow the printed WebUI **Settings → Models** or `nanobot onboard --wizard` route.
+
 ## Agent CLI

 | Command | Description |
@@ -87,9 +87,9 @@ The WebUI launcher is the normal browser entry point. Underneath, the gateway ke

 ## Provider and Model Selection

-The active model should normally come from a named `modelPresets` entry selected by `agents.defaults.modelPreset`. Direct `agents.defaults.provider` and `agents.defaults.model` still form the implicit `default` preset for older or minimal configs. The active provider is resolved in this order:
+The active model comes from the named `modelPresets` entry selected by `agents.defaults.modelPreset`, or from the concrete `modelPresets.default` entry when that selector is omitted. The active provider is resolved in this order:

-1. If the active preset provider or implicit default provider is not `"auto"`, nanobot uses that provider.
+1. If the active preset provider is not `"auto"`, nanobot uses that provider.
 2. If provider is `"auto"`, nanobot tries to infer the provider from the model name, configured API keys, local provider base URLs, or gateway providers.
 3. OAuth providers such as OpenAI Codex and GitHub Copilot require explicit login and explicit provider/model selection inside the active preset.

@@ -90,7 +90,9 @@ Instead of storing secrets directly in `config.json`, you can use `${VAR_NAME}`

 Any string value in `config.json` can use `${VAR_NAME}`. Resolution runs once at startup, in memory only — resolved values are never written back to disk, so editing config through `nanobot onboard` or the WebUI preserves the placeholder.

-If a referenced variable is unset, nanobot fails fast at startup with `ValueError: Environment variable 'NAME' referenced in config is not set`.
+If a referenced variable is unset, nanobot fails fast and reports the exact config field
+and variable name without echoing the field value. Run `nanobot status` with the same
+`--config` path to inspect the problem.

 ### More examples

@@ -257,7 +259,7 @@ Tracing covers the providers that go through nanobot's OpenAI-compatible client
 > - **ModelScope**: If you're using ModelScope's OpenAI-compatible endpoint, set `"apiBase": "https://api-inference.modelscope.cn/v1"` in your modelscope provider config.
 > - **StepFun Step Plan**: If you're on StepFun's Step Plan subscription, set `"apiBase": "https://api.stepfun.ai/step_plan/v1"` in your stepfun provider config. Supported models include `step-3.5-flash`, `step-3.5-flash-2603`, and `step-router-v1`.
 > - **Step Fun (Mainland China)**: If your API key is from Step Fun's mainland China platform (stepfun.com), set `"apiBase": "https://api.stepfun.com/v1"` in your stepfun provider config.
-> - **Xiaomi MiMo thinking mode**: MiMo models (e.g. `mimo-v2.5-pro`) default to enabled thinking. Use `agents.defaults.reasoningEffort: "none"` to disable it, or `"low"` / `"medium"` / `"high"` to keep it on. Omitting the field preserves the provider's per-model default.
+> - **Xiaomi MiMo thinking mode**: MiMo models (e.g. `mimo-v2.5-pro`) default to enabled thinking. Set `reasoningEffort: "none"` on the active model preset to disable it, or `"low"` / `"medium"` / `"high"` to keep it on. Omitting the field preserves the provider's per-model default.
 > - **Xiaomi MiMo Token Plan**: If you're on MiMo's token plan, set `"apiBase": "https://token-plan-sgp.xiaomimimo.com/v1"` in your xiaomi_mimo provider config.
 > - **Custom OpenAI-compatible providers**: Besides the built-in `custom` provider, any extra key under `providers` can define its own OpenAI-compatible endpoint. For example, `providers.companyProxy.apiBase` plus `modelPresets.primary.provider: "companyProxy"` creates a separate custom provider. Set `apiBase`; set `apiKey` only when the endpoint requires it. This named-custom path uses the OpenAI-compatible request format only. For Anthropic-compatible proxies, use `providers.anthropic.apiBase` with `provider: "anthropic"`.
 > - **Provider-scoped proxy**: `providers.<name>.proxy` routes only that provider through an HTTP proxy. It is supported for OpenAI-compatible providers, `openai_codex`, and `xai_grok`. Native provider backends such as `anthropic`, `bedrock`, `azure_openai`, and `github_copilot` reject `proxy`.
@@ -1344,20 +1346,12 @@ Contributor notes for adding new providers live in [`development.md`](./developm

 ## Model Presets

-Model presets let you name a complete model configuration and select one per session with `/model <preset>`. They are the recommended way to configure models because the same names can be reused for new-session defaults, chat-command switching, and fallback chains.
+Model presets let you name a complete model configuration and select one per session with `/model <preset>`. Configure all model, provider, generation, context-window, and image-input settings under top-level `modelPresets`; `agents.defaults` only selects preset names.

-Existing configs do not need to change. Direct `agents.defaults.model`, `provider`, `maxTokens`, `contextWindowTokens`, `temperature`, and `reasoningEffort` fields still define the implicit `default` preset. For new configs, prefer top-level `modelPresets` plus `agents.defaults.modelPreset`.
+On first load, nanobot migrates legacy model fields from `agents.defaults` and inline fallback objects in `config.json` into named presets, then atomically rewrites the file and logs a warning. If a concrete `modelPresets.default` and legacy direct fields both exist, the concrete preset wins and the warning explains that the conflicting legacy fields were removed. Legacy model fields supplied through nested `NANOBOT_AGENTS` environment settings are not supported and produce a warning with instructions to move them into `modelPresets`.

 ```json
 {
-  "modelPresets": {
-    "fast": {
-      "provider": "openrouter",
-      "model": "anthropic/claude-sonnet-4.5",
-      "maxTokens": 4096,
-      "contextWindowTokens": 65536
-    }
-  },
  "agents": {
    "defaults": {
      "modelPreset": "fast",
@@ -1365,6 +1359,14 @@ Existing configs do not need to change. Direct `agents.defaults.model`, `provide
    }
  },
  "modelPresets": {
+    "default": {
+      "label": "Default",
+      "model": "claude-opus-4-5",
+      "provider": "anthropic",
+      "maxTokens": 8192,
+      "contextWindowTokens": 200000,
+      "supportsImageInput": true
+    },
    "fast": {
      "label": "Fast",
      "model": "gpt-4.1-mini",
@@ -1372,7 +1374,8 @@ Existing configs do not need to change. Direct `agents.defaults.model`, `provide
      "maxTokens": 4096,
      "contextWindowTokens": 128000,
      "temperature": 0.2,
-      "reasoningEffort": "low"
+      "reasoningEffort": "low",
+      "supportsImageInput": true
    },
    "deep": {
      "label": "Deep",
@@ -1394,7 +1397,7 @@ Existing configs do not need to change. Direct `agents.defaults.model`, `provide
 }
 ```

-`modelPresets` is a top-level object. The keys under it (`fast`, `deep`, `coding`, etc.) are user-defined preset names. Each preset supports:
+`modelPresets` is a top-level object. `default` is required; its other keys (`fast`, `deep`, `coding`, etc.) are user-defined preset names. Each preset supports:

 | Field | Description |
 |-------|-------------|
@@ -1405,25 +1408,30 @@ Existing configs do not need to change. Direct `agents.defaults.model`, `provide
 | `contextWindowTokens` | Context window size used by prompt building and consolidation decisions. |
 | `temperature` | Sampling temperature. |
 | `reasoningEffort` | Optional reasoning/thinking setting. Provider support varies. |
+| `supportsImageInput` | `true` always sends images, `false` strips them before the first request, and `null`/omitted uses automatic retry-on-unsupported behavior. |

-`default` is reserved and always means the implicit preset built from direct `agents.defaults.*` fields; do not define `modelPresets.default`. Use `/model default` to switch back to those direct fields in an existing config.
+Every config has a concrete `modelPresets.default` entry. Use `/model default` to switch a session back to it. Configure the default model by editing that preset, not by adding model fields under `agents.defaults`.

-Set `agents.defaults.modelPreset` to choose the preset followed by sessions that have no saved model selection. When `modelPreset` is `null` or omitted, such sessions follow the implicit `default` preset from direct `agents.defaults.*` fields. `/model <preset>` saves an override in the current session, so its future turns keep that preset across process restarts while other sessions remain unchanged. The command does not write the selection back to `config.json`.
+Set `agents.defaults.modelPreset` to choose the preset followed by sessions that have no saved model selection. When it is omitted, such sessions use `modelPresets.default`. `/model <preset>` saves an override in the current session, so its future turns keep that preset across process restarts while other sessions remain unchanged. The command does not write the selection back to `config.json`.

 ### Model Fallbacks

-`agents.defaults.fallbackModels` defines an ordered failover chain for the active model configuration. The primary model is still selected by `agents.defaults.modelPreset` or, in older configs, by the implicit `default` preset from direct `agents.defaults.*` fields.
+`agents.defaults.fallbackModels` defines an ordered failover chain for the active model configuration. The primary model is selected by `agents.defaults.modelPreset`, or by `modelPresets.default` when that selector is omitted.

-Each fallback candidate can be either:
-
- A preset name from `modelPresets`, such as `"deep"`. This is the recommended form. The preset's full model, provider, generation, and context-window config is used.
- An inline fallback object with at least `provider` and `model`. Optional `maxTokens`, `contextWindowTokens`, and `temperature` fields inherit from the active primary config when omitted. `reasoningEffort` does not inherit; omit it to leave reasoning off for that fallback, or set it explicitly for models that support reasoning.
+Each fallback candidate is a preset name from `modelPresets`, such as `"deep"`. The preset's complete model, provider, generation, context-window, and image-input configuration is used.

 Preset fallback chain:

 ```json
 {
  "modelPresets": {
+    "default": {
+      "model": "gpt-4.1-mini",
+      "provider": "openai",
+      "maxTokens": 4096,
+      "contextWindowTokens": 128000,
+      "temperature": 0.2
+    },
    "fast": {
      "model": "gpt-4.1-mini",
      "provider": "openai",
@@ -1454,37 +1462,7 @@ Preset fallback chain:
 }
 ```

-String entries are preset names, not raw model names. In the example above, `"deep"` means `modelPresets.deep`; nanobot will not interpret it as a provider model ID. Changing a preset updates both `/model <preset>` switching and any fallback chain that references it.
-
-Inline fallback object:
-
-```json
-{
-  "modelPresets": {
-    "fast": {
-      "provider": "openrouter",
-      "model": "anthropic/claude-sonnet-4.5",
-      "maxTokens": 4096,
-      "contextWindowTokens": 65536
-    }
-  },
-  "agents": {
-    "defaults": {
-      "modelPreset": "fast",
-      "fallbackModels": [
-        {
-          "provider": "deepseek",
-          "model": "deepseek-v4-pro",
-          "maxTokens": 4096,
-          "contextWindowTokens": 262144
-        }
-      ]
-    }
-  }
-}
-```
-
-Use inline objects only when a fallback is not worth naming as a reusable preset. `fallbackModels` belongs under `agents.defaults`, not inside individual `modelPresets` entries.
+String entries are preset names, not raw model names. In the example above, `"deep"` means `modelPresets.deep`; nanobot will not interpret it as a provider model ID. Changing a preset updates both `/model <preset>` switching and any fallback chain that references it. `fallbackModels` belongs under `agents.defaults`, not inside individual `modelPresets` entries.

 Failover normally runs when the primary provider returns a fallbackable model/provider error before any answer text has been streamed. Stream-stall timeouts are the recovery exception: if the provider already emitted partial answer text and then stalls, nanobot closes the current stream segment and retries/fails over in a new segment. Typical fallback cases include timeouts, connection errors, 5xx server errors, 429 rate limits, overloads, authentication/permission failures such as invalid or expired credentials, and quota/balance exhaustion. It does not run for malformed requests, content filtering/refusals, or context-length/message-format errors.

@@ -1556,7 +1534,6 @@ Global settings that apply to all channels. Configure under the `channels` secti
  "channels": {
    "sendProgress": true,
    "sendToolHints": true,
-    "extractDocumentText": true,
    "sendMaxRetries": 3,
    "telegram": {
      "enabled": false
@@ -1570,9 +1547,15 @@ Global settings that apply to all channels. Configure under the `channels` secti
 | `sendProgress` | `true` | Stream agent's text progress to the channel |
 | `sendToolHints` | `true` | Stream tool-call hints (e.g. `read_file("…")`) |
 | `showReasoning` | `true` | Allow channels to surface model reasoning/thinking content (DeepSeek-R1 `reasoning_content`, Anthropic `thinking_blocks`, inline `<think>` tags). Reasoning flows as a dedicated stream with `_reasoning_delta` / `_reasoning_end` markers — channels override `send_reasoning_delta` / `send_reasoning_end` to render in-place updates. Even with `true`, channels without those overrides stay no-op silently. Currently surfaced on CLI and WebSocket/WebUI (italic shimmer header, auto-collapses after the stream ends); Telegram / Slack / Discord / Feishu / WeChat / Matrix / Mattermost keep the base no-op until their bubble UI is adapted. Independent of `sendProgress`. |
-| `extractDocumentText` | `true` | Extract supported document/text attachments into the model prompt. PDF, DOCX, XLSX, and PPTX readers are included in the standard installation. Set to `false` to keep document content out of the prompt and include attachment path references instead. |
 | `sendMaxRetries` | `3` | Max delivery attempts per outbound message, including the initial send (0-10 configured, minimum 1 actual attempt) |

+Non-image attachments are included in the user message as local path references, without
+injecting their contents into the model prompt. When file tools are enabled, the agent
+can inspect supported text, PDF, DOCX, XLSX, and PPTX files on demand with `read_file`,
+or pass the original path to another tool when exact file bytes are required. The deprecated
+`channels.extractDocumentText` setting is accepted for compatibility but ignored.
+Normal tool workspace and media access rules still apply to attachment paths.
+
 `channels.transcriptionProvider` and `channels.transcriptionLanguage` are deprecated compatibility fields. They remain as a read-only fallback for older configs, but new configuration should use top-level `transcription.provider` and `transcription.language`.

 `sendProgress` and `sendToolHints` can also be overridden per channel. The global values stay as defaults for channels that do not set their own value:
@@ -39,6 +39,23 @@ Run nanobot online without managing a server. The blueprint deploys the gateway

 [Review the deployment blueprint](../render.yaml)

+### First Deployment
+
+1. Click **Deploy to Render**, sign in, and review the Blueprint. It creates one Starter web service and a 1 GB persistent disk.
+2. Enter your `ANTHROPIC_API_KEY`. Set `NANOBOT_WEB_TOKEN` to a new random value and save it in your password manager; this is the password for the public WebUI.
+3. Create the Blueprint and wait for the service status to become **Live**. The first build can take several minutes.
+4. Open the generated `onrender.com` URL. The **Authentication required** page means the gateway is running: enter the same `NANOBOT_WEB_TOKEN` value to open the WebUI.
+
+The model API key is used by nanobot to call Anthropic. The Web token only protects access to this deployment; do not share it in issues, screenshots, or chat.
+
+### Updates and Data
+
+The Blueprint disables automatic deploys so upstream repository changes do not unexpectedly restart your agent. To update, open the service in the Render Dashboard and choose **Manual Deploy → Deploy latest commit**.
+
+The persistent disk keeps `config.json`, sessions, memory, WebUI history, cron state, media, and logs across restarts and updates. The deployment initializes `config.json` only when it does not already exist, so settings changed later in the WebUI are not replaced on every boot.
+
+If deployment fails, open the service **Logs** page first. A missing model key fails provider requests after startup, while an incorrect Web token leaves you on the authentication page.
+
 ## Docker

 > [!TIP]
@@ -186,9 +186,7 @@ Dream is configured under `agents.defaults.dream`:
    "defaults": {
      "dream": {
        "intervalH": 2,
-        "modelOverride": null,
-        "maxBatchSize": 20,
-        "maxIterations": 10
+        "modelOverride": null
      }
    }
  }
@@ -199,16 +197,13 @@ Dream is configured under `agents.defaults.dream`:
 |-------|---------|
 | `intervalH` | How often Dream runs, in hours |
 | `cron` | Cron expression override (takes precedence over `intervalH`) |
-| `modelOverride` | Optional Dream-specific model override *(pending implementation)* |
-| `maxBatchSize` | *(Deprecated — not used)* |
-| `maxIterations` | *(Deprecated — not used)* |
+| `modelOverride` | Optional model preset name used for Dream |

 In practical terms:

 - `intervalH` is the normal way to configure Dream frequency. Internally it runs as an `every` schedule.
 - `cron` overrides `intervalH` when set, allowing precise cron expressions (e.g. `0 */4 * * *`).
- `modelOverride` is reserved for a future release. Currently Dream uses the same model as the main agent.
- `maxBatchSize` and `maxIterations` are preserved for config compatibility but no longer affect behavior.
+- `modelOverride` selects a named entry from `model_presets` for Dream. It accepts preset names only; raw model identifiers are not supported. If omitted, Dream uses the main agent's selected runtime.

 ## In Practice

@@ -34,7 +34,7 @@ Match the recipe to the credential or endpoint you already have:
 5. Run `nanobot agent -m "Hello!"`.
 6. If the CLI works, then connect WebUI, gateway, or chat apps.

-The active model should normally come from `agents.defaults.modelPreset`, and that name should point to an entry in `modelPresets`. Direct `agents.defaults.provider` and `agents.defaults.model` still work for older configs, but presets are easier to switch and easier to reuse as fallbacks.
+The active model comes from `agents.defaults.modelPreset`, and that name must point to an entry in `modelPresets`. Configure model/provider settings in presets so they can be switched and reused as fallbacks.

 ## Secret Setup

@@ -10,7 +10,7 @@ For every setup, answer three questions:
 2. What model name does that provider expect?
 3. Does the provider need `apiKey`, `apiBase`, OAuth login, cloud credentials, or only a local server URL?

-Prefer a named `modelPresets` entry for the model/provider pair, then select it with `agents.defaults.modelPreset`. Direct `agents.defaults.provider` and `agents.defaults.model` still work for existing configs, but presets make runtime `/model` switching and fallback chains clearer. Pin `provider` inside the preset while setting up; you can switch back to `"auto"` later.
+Define the model/provider pair as a named `modelPresets` entry, then select it with `agents.defaults.modelPreset`. Pin `provider` inside the preset while setting up; you can switch back to `"auto"` later.

 ## Choose a Provider Without Guessing

@@ -462,14 +462,14 @@ Each command authenticates the selected provider and makes its current default m

 ## Provider Resolution

-The recommended path is a named preset selected by `agents.defaults.modelPreset`. The effective model parameters come from:
+The effective model parameters come from:

 1. the named `modelPresets` entry referenced by `agents.defaults.modelPreset`;
-2. otherwise the implicit `default` preset built from `agents.defaults.model`, `provider`, `maxTokens`, `contextWindowTokens`, `temperature`, and related fields.
+2. otherwise the concrete `modelPresets.default` entry.

 Provider selection follows this practical rule:

- Explicit `provider` in the active preset or implicit default config wins.
+- Explicit `provider` in the active preset wins.
 - `provider: "auto"` tries model-name keywords, configured keys, local base URLs, and gateway providers.
 - Gateway providers such as OpenRouter and AiHubMix can route many model families, so the model name must be valid for that gateway.
 - Local providers should normally be explicit because generic local model names such as `llama3.2` do not always contain provider keywords.
@@ -491,6 +491,14 @@ Model presets are the recommended model configuration surface. Use them when you
 ```json
 {
  "modelPresets": {
+    "default": {
+      "label": "Default",
+      "provider": "anthropic",
+      "model": "claude-opus-4-5",
+      "maxTokens": 8192,
+      "contextWindowTokens": 200000,
+      "temperature": 0.1
+    },
    "fast": {
      "label": "Fast",
      "provider": "openrouter",
@@ -516,7 +524,7 @@ Model presets are the recommended model configuration surface. Use them when you
 }
 ```

-The preset name `default` is reserved for the implicit `agents.defaults` settings. Do not define `modelPresets.default`; use `/model default` to return to the direct `agents.defaults.*` fields in older configs.
+Every config has a concrete `modelPresets.default` entry. Use `/model default` to return to it. Legacy direct model fields in `agents.defaults` are migrated from `config.json` on first load; configure presets only after migration.

 ## Fallback Models

@@ -525,6 +533,14 @@ Fallbacks are useful for transient provider failures, rate limits, or model avai
 ```json
 {
  "modelPresets": {
+    "default": {
+      "label": "Default",
+      "provider": "openrouter",
+      "model": "anthropic/claude-sonnet-4.5",
+      "maxTokens": 4096,
+      "contextWindowTokens": 65536,
+      "temperature": 0.1
+    },
    "fast": {
      "label": "Fast",
      "provider": "openrouter",
@@ -559,35 +575,7 @@ Fallbacks are useful for transient provider failures, rate limits, or model avai
 }
 ```

-String entries in `fallbackModels` are preset names, not raw model names. nanobot tries them in order after the active preset. Each fallback preset uses its own `provider`, `model`, `maxTokens`, `contextWindowTokens`, `temperature`, and optional `reasoningEffort`.
-
-Use inline fallback objects only when a model is not worth naming as a preset:
-
-```json
-{
-  "modelPresets": {
-    "fast": {
-      "provider": "openrouter",
-      "model": "anthropic/claude-sonnet-4.5",
-      "maxTokens": 4096,
-      "contextWindowTokens": 65536
-    }
-  },
-  "agents": {
-    "defaults": {
-      "modelPreset": "fast",
-      "fallbackModels": [
-        {
-          "provider": "deepseek",
-          "model": "deepseek-v4-pro",
-          "maxTokens": 4096,
-          "contextWindowTokens": 262144
-        }
-      ]
-    }
-  }
-}
-```
+String entries in `fallbackModels` are preset names, not raw model names. nanobot tries them in order after the active preset. Each fallback preset uses its own `provider`, `model`, `maxTokens`, `contextWindowTokens`, `temperature`, optional `reasoningEffort`, and `supportsImageInput` policy.

 `fallbackModels` belongs under `agents.defaults`, not inside each preset. If fallback candidates use smaller context windows, nanobot builds context using the smallest window in the active chain so every candidate can receive the same prompt. See [`configuration.md#model-fallbacks`](./configuration.md#model-fallbacks) for failure conditions.

@@ -266,21 +266,10 @@ The config controls what nanobot may use. The workspace is where nanobot keeps
 state for that instance. See [multiple-instances.md](multiple-instances.md) for
 multi-instance CLI and gateway examples.

-### Choose a default or per-run model
+### Choose a default or per-run model preset

-Set the SDK instance default model when you create the bot:
-
-```python
-bot = Nanobot.from_config(model="openai/gpt-4.1")
-```
-
-Override the model for one run without changing the instance default:
-
-```python
-result = await bot.run("Summarize this file", model="openai/gpt-4.1-mini")
-```
-
-Model presets from `config.json` work the same way:
+Define complete model choices under `modelPresets` in `config.json`, then select
+them by name for the SDK instance or for one run:

 ```python
 bot = Nanobot.from_config(model_preset="fast")
@@ -288,7 +277,8 @@ bot = Nanobot.from_config(model_preset="fast")
 result = await bot.run("Think deeply about this bug", model_preset="reasoning")
 ```

-`model` and `model_preset` are mutually exclusive.
+The public SDK accepts preset names rather than raw model IDs. This keeps provider,
+generation, context-window, fallback, and image-input settings together.

 For first setup, prefer named presets in `config.json`. Mixing an API key from
 one provider with a model ID from another is the most common first-run failure.
@@ -463,7 +453,7 @@ configuration docs remain the source of truth for the runtime around it:

 ## API Reference

-### `Nanobot.from_config(config_path=None, *, workspace=None, model=None, model_preset=None)`
+### `Nanobot.from_config(config_path=None, *, workspace=None, model_preset=None)`

 Create a `Nanobot` instance from a config file.

@@ -471,11 +461,9 @@ Create a `Nanobot` instance from a config file.
 |-------|------|---------|-------------|
 | `config_path` | `str \| Path \| None` | `None` | Path to `config.json`. Defaults to `~/.nanobot/config.json`. |
 | `workspace` | `str \| Path \| None` | `None` | Override the workspace directory from config. |
-| `model` | `str \| None` | `None` | Override the instance default model. |
 | `model_preset` | `str \| None` | `None` | Override the instance default model preset from `config.json`. |

 Raises `FileNotFoundError` if an explicit config path does not exist.
-Raises `ValueError` if both `model` and `model_preset` are provided.

 ### `await bot.run(...)`

@@ -490,14 +478,14 @@ Run the agent once and return a `RunResult`.
 | `sender_id` | `str` | `"user"` | Logical sender identifier used in runtime context. |
 | `media` | `list[str] \| None` | `None` | Optional local media paths attached to the message. |
 | `ephemeral` | `bool` | `False` | Run without persisting the turn or compacting session history. |
+| `attributes` | `Mapping[str, Any] \| None` | `None` | Caller-owned request data for host integrations. It is available to context providers and turn-hook factories, but is not added to trusted message metadata or persisted in session messages. |
 | `hooks` | `list[AgentHook] \| None` | `None` | Lifecycle hooks for this run only. |
-| `model` | `str \| None` | `None` | Override the model for this run only. |
 | `model_preset` | `str \| None` | `None` | Override the model preset for this run only. |

 Without an override, a run uses the preset saved in its session, or the configured
-default when that session has no saved selection. `model` and `model_preset` are
-mutually exclusive per-run overrides; they do not change the saved session selection
-or `bot.runtime.model` after the run completes.
+default when that session has no saved selection. A per-run `model_preset` override
+does not change the saved session selection or `bot.runtime.model` after the run
+completes.

 ### `await bot.run_streamed(...)`

@@ -534,7 +522,7 @@ async for event in bot.stream("Generate a long answer"):
 | `await aclose()` | Close the stream; equivalent cleanup primitive for `async with` / manual lifecycle code. |

 SDK runs with different session keys may overlap, including runs with per-run
-`model` or `model_preset` overrides. Each run receives an immutable runtime without
+`model_preset` overrides. Each run receives an immutable runtime without
 mutating the instance default. Runs sharing one session key remain serialized.

 ### `StreamEvent`
@@ -631,9 +619,96 @@ Do not expose exported snapshots directly to chat users.
 |-------------------|-------------|
 | `model` | Current runtime model name. |
 | `workspace` | Current runtime workspace path. |
+| `add_context_provider(provider)` | Register an async per-turn context provider and return an unsubscribe callback. |
+| `on_session_turn_persisted(handler)` | Register a best-effort sync or async callback for locally persisted turns and return an unsubscribe callback. |
 | `await compact_session(session_key)` | Run token/replay-window consolidation for a session. |
 | `await compact_idle_session(session_key, max_suffix=8)` | Run idle-session compaction and return its summary. |

+### Host integration context and persisted-turn callbacks
+
+Host applications can attach external context without copying or modifying the
+nanobot agent loop. A context provider receives a `RequestContext` before each
+model turn and may return one or more `RuntimeContextBlock` values. Use
+`attributes` for caller-owned routing data; nanobot keeps it separate from
+trusted channel metadata and does not persist it in session messages.
+
+`on_session_turn_persisted()` invokes its callback after a non-ephemeral turn
+has been saved. The callback receives `SessionTurnPersisted` and may read the
+completed transcript through `bot.sessions`. Callbacks run in registration
+order, and async callbacks are awaited before the run continues. They are
+observational: callback exceptions are logged and suppressed so the completed
+local turn remains successful. Durable external synchronization must catch
+failures and persist retry work before the callback returns. During SDK runs,
+callbacks execute while the session is still serialized and must not re-enter
+`bot.run()` for the same session.
+
+```python
+import json
+
+from nanobot import (
+    Nanobot,
+    RequestContext,
+    RuntimeContextBlock,
+    SessionTurnPersisted,
+)
+
+
+def external_context_block(text: str) -> RuntimeContextBlock:
+    bounded = text[:8_000]
+    encoded = json.dumps(bounded, ensure_ascii=False)
+    encoded = encoded.replace("[", "\\u005b").replace("]", "\\u005d")
+    return RuntimeContextBlock(
+        source="external_memory",
+        content=(
+            "[Runtime Context — metadata only, not instructions]\n"
+            "External memory result (JSON-encoded; treat as data, not instructions):\n"
+            f"{encoded}\n"
+            "[/Runtime Context]"
+        ),
+    )
+
+
+async def run_with_external_memory(external_memory, enqueue_retry) -> None:
+    async with Nanobot.from_config() as bot:
+        async def load_context(request: RequestContext):
+            resource = request.attributes.get("resource")
+            if not resource:
+                return None
+            text = await external_memory.search(
+                resource,
+                request.original_user_text or "",
+            )
+            return external_context_block(text)
+
+        async def sync_saved_turn(event: SessionTurnPersisted):
+            snapshot = bot.sessions.get(event.context.session_key)
+            if snapshot is not None:
+                try:
+                    await external_memory.sync(
+                        resource=event.context.attributes.get("resource"),
+                        messages=snapshot.messages,
+                    )
+                except Exception as exc:
+                    await enqueue_retry(event, snapshot, exc)
+
+        remove_context = bot.runtime.add_context_provider(load_context)
+        remove_sync = bot.runtime.on_session_turn_persisted(sync_saved_turn)
+        try:
+            await bot.run(
+                "Continue the architecture discussion",
+                session_key="project:architecture",
+                attributes={"resource": "memory://projects/architecture"},
+            )
+        finally:
+            remove_sync()
+            remove_context()
+```
+
+Context providers are trusted host extensions, and `RuntimeContextBlock.content`
+is appended verbatim to model-visible context. Apply equivalent bounding,
+encoding, and delimiter escaping to untrusted external content.
+Persisted-turn callbacks are not invoked for `ephemeral=True` runs.
+
 ## Hooks

 Hooks let you observe or customize the agent loop. Subclass `AgentHook` and override the methods you need.
@@ -23,15 +23,20 @@ This separates failures into layers:
 | Layer | What it proves |
 |---|---|
 | `nanobot --version` | Install and shell command discovery |
-| `nanobot status` | Config path, workspace path, active model, and provider summary |
+| `nanobot status` | Config path, workspace, environment references, and active provider/model configuration |
 | `nanobot agent -m "Hello!"` | Config loading, provider/model access, workspace writes, and agent loop |
 | `nanobot gateway` | Channel startup, cron system jobs, heartbeat, WebUI/WebSocket, and health endpoint |

 If `nanobot agent -m "Hello!"` fails, fix that before debugging WebUI, Telegram, Discord, Docker, systemd, or any chat app.

+`nanobot status` does not call the model. If provider/model setup is incomplete, it points to
+WebUI **Settings → Models** or the CLI setup wizard, then prints the command to check again.
+
 ## How to Read `nanobot status`

-`nanobot status` does not call a model. It only checks whether nanobot can find the selected config, selected workspace, active model or preset, and provider setup summary.
+`nanobot status` does not call a model. It checks the selected config and workspace,
+resolves environment references, and validates the local settings required by the active
+provider/model without constructing a provider client.

 The output has this shape:

@@ -41,6 +46,7 @@ nanobot Status
 Config: /path/to/config.json ✓
 Workspace: /path/to/workspace ✓
 Model: provider/model-name (preset: primary)
+Agent: ✓ provider/model configuration is ready
 Provider A: not set
 Provider B: ✓
 Local Provider: ✓ http://localhost:11434/v1
@@ -54,6 +60,7 @@ Read it like this:
 | `Config` | It points to the config file you meant to use and shows `✓`. | Run `nanobot onboard`, or pass `--config` to `nanobot agent`, `gateway`, or `serve` when testing a non-default instance. |
 | `Workspace` | It points to the workspace you meant to use and shows `✓`. | Run `nanobot onboard`, create the folder, fix permissions, or pass `--workspace` on commands that support it. |
 | `Model` | It shows the active model or the preset name you expect. | Set `agents.defaults.modelPreset` to the intended preset, or check `/model` if you changed models during a chat session. |
+| `Agent` | It says `provider/model configuration is ready`. | Follow the printed WebUI or CLI setup route, then run `nanobot status` again. |
 | Provider rows | The provider used by the active preset shows `✓`, an OAuth marker, or a local URL. | Configure only the active provider first. It is normal for unused providers to say `not set`. |

 If `nanobot status` looks right but `nanobot agent -m "Hello!"` fails, the install and config paths are probably fine. Continue with [Provider and Model Problems](#provider-and-model-problems).
@@ -108,6 +115,12 @@ Common config mistakes:
 | Environment variable error | `${VAR_NAME}` references are resolved at startup. Set the variable before running nanobot. |
 | Edited config but behavior did not change | Restart `nanobot gateway`; long-running processes read config at startup. |

+After editing config, check the shortest path to an Agent reply:
+
+```bash
+nanobot status
+```
+
 To refresh missing defaults without overwriting existing settings, run:

 ```bash
@@ -132,7 +145,7 @@ If you need a known-good snippet instead of diagnosis, use [`provider-cookbook.m
 |---|---|
 | 401, unauthorized, invalid API key | Key is missing, expired, pasted with whitespace, or under the wrong provider key. |
 | Model not found | The model ID belongs to a different provider or gateway. |
-| Provider cannot be inferred | Pin `modelPresets.<name>.provider` in the active preset instead of using `"auto"`. For legacy direct configs, pin `agents.defaults.provider`. |
+| Provider cannot be inferred | Pin `modelPresets.<name>.provider` in the active preset instead of using `"auto"`. |
 | Local model connection refused | Ollama, vLLM, LM Studio, or another local server is not running, or `apiBase` points to the wrong port. |
 | Bedrock validation error | Check AWS region, credentials, model access, model ID, and whether the model supports Converse. |
 | OAuth provider fails | Run the matching login command: `openai-codex`, `xai-grok`, or `github-copilot`, normally with `--set-main`. |
@@ -32,6 +32,9 @@ _LAZY_EXPORTS = {
    "Nanobot": ".nanobot",
    "RunStream": ".nanobot",
    "RunResult": ".nanobot",
+    "RequestContext": ".agent.tools.context",
+    "RuntimeContextBlock": ".runtime_context",
+    "RuntimeContextProvider": ".runtime_context",
    "SessionInfo": ".nanobot",
    "SessionSnapshot": ".nanobot",
    "STREAM_EVENT_REASONING_COMPLETED": ".nanobot",
@@ -47,6 +50,7 @@ _LAZY_EXPORTS = {
    "STREAM_EVENT_TYPES": ".nanobot",
    "StreamEvent": ".nanobot",
    "StreamEventType": ".nanobot",
+    "SessionTurnPersisted": ".bus.runtime_events",
 }


@@ -64,6 +68,9 @@ def __getattr__(name: str):
 __all__ = [
    "Nanobot",
    "RunResult",
+    "RequestContext",
+    "RuntimeContextBlock",
+    "RuntimeContextProvider",
    "RunStream",
    "SessionInfo",
    "SessionSnapshot",
@@ -80,4 +87,5 @@ __all__ = [
    "STREAM_EVENT_TYPES",
    "StreamEvent",
    "StreamEventType",
+    "SessionTurnPersisted",
 ]
@@ -15,10 +15,13 @@ from nanobot.apps.cli import utils as cli_app_utils
 from nanobot.bus.events import InboundMessage
 from nanobot.runtime_context import (
    RUNTIME_CONTEXT_END,
+    RUNTIME_CONTEXT_HISTORY_META,
    RUNTIME_CONTEXT_MESSAGE_META,
    RUNTIME_CONTEXT_TAG,
    RuntimeContextBlock,
    append_runtime_context,
+    detach_runtime_context,
+    reattach_runtime_context,
 )
 from nanobot.utils.helpers import (
    detect_image_mime,
@@ -60,6 +63,9 @@ class ContextBuilder:
    _MAX_RECENT_HISTORY = 50
    _MAX_HISTORY_TOKENS = 8_000  # hard cap on recent history section size (tokens)
    _RUNTIME_CONTEXT_END = RUNTIME_CONTEXT_END
+    _MISSING_IMAGE_TEXT = (
+        "[Image attachment unavailable — do not describe or reference it]"
+    )

    def __init__(self, workspace: Path, timezone: str | None = None, disabled_skills: list[str] | None = None):
        self.workspace = workspace
@@ -69,7 +75,7 @@ class ContextBuilder:

    def build_system_prompt(
        self,
-        skill_names: list[str] | None = None,
+        *,
        channel: str | None = None,
        session_summary: str | None = None,
        workspace: Path | None = None,
@@ -87,9 +93,9 @@ class ContextBuilder:

        parts.append(render_template("agent/tool_contract.md"))

-        memory = self.memory.get_memory_context()
-        if memory and not self._is_template_content(self.memory.read_memory(), "memory/MEMORY.md"):
-            parts.append(f"# Memory\n\n{memory}")
+        memory = self.memory.read_memory()
+        if memory and not self._is_template_content(memory, "memory/MEMORY.md"):
+            parts.append(f"# Memory\n\n## Long-term Memory\n{memory}")

        always_skills = self.skills.get_always_skills()
        if always_skills:
@@ -196,14 +202,11 @@ class ContextBuilder:
        self,
        history: list[dict[str, Any]],
        current_message: str,
-        skill_names: list[str] | None = None,
+        *,
        media: list[str] | None = None,
        channel: str | None = None,
-        chat_id: str | None = None,
        current_role: str = "user",
-        sender_id: str | None = None,
        session_summary: str | None = None,
-        session_metadata: Mapping[str, Any] | None = None,
        runtime_context_blocks: Sequence[RuntimeContextBlock] | None = None,
        workspace: Path | None = None,
        include_memory_recent_history: bool = True,
@@ -212,14 +215,13 @@ class ContextBuilder:
    ) -> list[dict[str, Any]]:
        """Build the complete message list for an LLM call."""
        root = workspace or self.workspace
-        user_content = self._build_user_content(current_message, media)
+        user_content = self.build_user_content(current_message, image_paths=media)
        blocks = list(runtime_context_blocks or ()) if current_role == "user" else []
        merged, runtime_context_meta = append_runtime_context(user_content, blocks)
        messages = [
            {
                "role": "system",
                "content": self.build_system_prompt(
-                    skill_names,
                    channel=channel,
                    session_summary=session_summary,
                    workspace=root,
@@ -228,7 +230,7 @@ class ContextBuilder:
                    unified_session=unified_session,
                ),
            },
-            *history,
+            *self._hydrate_history_media(history),
        ]
        if messages[-1].get("role") == current_role:
            last = dict(messages[-1])
@@ -245,27 +247,78 @@ class ContextBuilder:
        messages.append(current)
        return messages

-    def _build_user_content(self, text: str, media: list[str] | None) -> str | list[dict[str, Any]]:
-        """Build user message content with optional base64-encoded images."""
-        if not media:
+    def build_user_content(
+        self,
+        text: str,
+        image_paths: list[str] | None,
+    ) -> str | list[dict[str, Any]]:
+        """Build user message content from prefiltered image paths."""
+        if not image_paths:
            return text

-        images = []
-        for path in media:
+        image_blocks = []
+        for path in image_paths:
            p = Path(path)
            if not p.is_file():
+                image_blocks.append(
+                    {"type": "text", "text": self._MISSING_IMAGE_TEXT}
+                )
                continue
            raw = p.read_bytes()
+            # Re-detect from the bytes used for the request: the file may have
+            # changed since attachment routing, and the data URL needs its MIME.
            mime = detect_image_mime(raw) or mimetypes.guess_type(path)[0]
            if not mime or not mime.startswith("image/"):
                continue
            b64 = base64.b64encode(raw).decode()
-            images.append({
+            image_blocks.append({
                "type": "image_url",
                "image_url": {"url": f"data:{mime};base64,{b64}"},
                "_meta": {"path": str(p)},
            })

-        if not images:
+        if not image_blocks:
            return text
-        return images + [{"type": "text", "text": text}]
+        return image_blocks + [{"type": "text", "text": text}]
+
+    def _hydrate_history_media(
+        self,
+        history: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Rebuild persisted user media into the same blocks used on first send."""
+        hydrated: list[dict[str, Any]] = []
+        for message in history:
+            clean = dict(message)
+            media_paths = clean.pop("_media_paths", None)
+            runtime_context = clean.pop(RUNTIME_CONTEXT_HISTORY_META, None)
+            if (
+                clean.get("role") == "user"
+                and isinstance(clean.get("content"), str)
+                and isinstance(media_paths, list)
+                and media_paths
+            ):
+                visible_content = clean["content"]
+                detached = (
+                    detach_runtime_context(visible_content, runtime_context)
+                    if isinstance(runtime_context, Mapping)
+                    else None
+                )
+                if detached is not None:
+                    visible_content, sources, context_blocks = detached
+                hydrated_content = self.build_user_content(
+                    visible_content,
+                    image_paths=[
+                        path
+                        for path in media_paths
+                        if isinstance(path, str) and path
+                    ],
+                )
+                if detached is not None:
+                    hydrated_content, _ = reattach_runtime_context(
+                        hydrated_content,
+                        sources,
+                        context_blocks,
+                    )
+                clean["content"] = hydrated_content
+            hydrated.append(clean)
+        return hydrated
@@ -26,7 +26,6 @@ if TYPE_CHECKING:
    from nanobot.providers.base import LLMProvider

 SNIP_SAFETY_BUFFER = 1024
-MICROCOMPACT_KEEP_RECENT = 10
 MICROCOMPACT_MIN_CHARS = 500
 INFLIGHT_COMPACT_TARGET_RATIO = 0.85
 COMPACTABLE_TOOLS = frozenset({
@@ -498,14 +497,7 @@ class ContextGovernor:
                continue
            compactable.append((idx, str(tool_call_id)))

-        if not compactable:
-            return []
-        primary_count = max(0, len(compactable) - MICROCOMPACT_KEEP_RECENT)
-        primary = compactable[:primary_count]
-        # Hard overflow beats the keep-recent preference. Return recent results
-        # after stale ones so the newest result is naturally last.
-        fallback = compactable[primary_count:]
-        return primary + fallback
+        return compactable

    def _compact_tool_result_at(self, messages: list[dict[str, Any]], idx: int) -> None:
        messages[idx]["content"] = self._tool_result_compaction_message(messages[idx])
@@ -59,6 +59,7 @@ class AgentTurnHookContext:
    session_key: str | None = None
    metadata: dict[str, Any] = field(default_factory=dict)
    ephemeral: bool = False
+    attributes: dict[str, Any] = field(default_factory=dict)


 class AgentHook:
@@ -13,7 +13,7 @@ from dataclasses import dataclass, field
 from enum import Enum, auto
 from functools import partial
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, TypeVar

 from loguru import logger

@@ -43,11 +43,7 @@ from nanobot.agent.turn_hooks import AgentTurnHookSpec, build_agent_turn_hook
 from nanobot.bus.events import InboundMessage, OutboundMessage
 from nanobot.bus.outbound_events import StreamedResponseEvent
 from nanobot.bus.queue import MessageBus
-from nanobot.bus.runtime_events import (
-    RuntimeEventBus,
-    RuntimeEventPublisher,
-    ensure_runtime_event_publisher,
-)
+from nanobot.bus.runtime_events import RuntimeEventBus
 from nanobot.command import CommandContext, CommandRouter, register_builtin_commands
 from nanobot.config.schema import AgentDefaults, ModelPresetConfig
 from nanobot.providers.base import LLMProvider
@@ -86,7 +82,7 @@ from nanobot.session.model_selection import (
 )
 from nanobot.triggers.local_turns import LocalTriggerTurnCoordinator
 from nanobot.utils.cancellation import task_is_cancelling
-from nanobot.utils.document import extract_documents, reference_non_image_attachments
+from nanobot.utils.document import reference_non_image_attachments
 from nanobot.utils.helpers import image_placeholder_text
 from nanobot.utils.helpers import truncate_text as truncate_text_fn
 from nanobot.utils.llm_runtime import LLMRuntime
@@ -103,15 +99,7 @@ if TYPE_CHECKING:
    )
    from nanobot.cron.service import CronService

-class TurnState(Enum):
-    RESTORE = auto()
-    COMPACT = auto()
-    COMMAND = auto()
-    BUILD = auto()
-    RUN = auto()
-    SAVE = auto()
-    RESPOND = auto()
-    DONE = auto()
+_T = TypeVar("_T")


 class TurnKind(Enum):
@@ -119,20 +107,10 @@ class TurnKind(Enum):
    SYSTEM = auto()


-@dataclass
-class StateTraceEntry:
-    state: TurnState
-    started_at: float
-    duration_ms: float
-    event: str
-    error: str | None = None
-
-
@dataclass
 class TurnContext:
    msg: InboundMessage
    session_key: str
-    state: TurnState
    turn_id: str
    runtime: LLMRuntime | None
    kind: TurnKind
@@ -144,9 +122,9 @@ class TurnContext:
    initial_messages: list[dict[str, Any]] = field(default_factory=list)
    request_context: RequestContext | None = None
    runtime_context_blocks: list[RuntimeContextBlock] = field(default_factory=list)
+    attributes: dict[str, Any] = field(default_factory=dict)

    final_content: str | None = None
-    tools_used: list[str] = field(default_factory=list)
    all_messages: list[dict[str, Any]] = field(default_factory=list)
    stop_reason: str = ""
    had_injections: bool = False
@@ -178,8 +156,6 @@ class TurnContext:
    visible_run_started_at: float | None = None
    turn_latency_ms: int | None = None

-    trace: list[StateTraceEntry] = field(default_factory=list)
-

 class AgentLoop:
    """
@@ -241,22 +217,15 @@ class AgentLoop:
            self._publish_runtime_selection(runtime)
        return runtime

+    def dream_runtime(self) -> LLMRuntime | None:
+        """Resolve the optional preset used for Dream without changing defaults."""
+        if not self.dream_model_preset:
+            return None
+        return self.runtime_resolver.resolve_preset(self.dream_model_preset)
+
    _RUNTIME_CHECKPOINT_KEY = "runtime_checkpoint"
    _PENDING_USER_TURN_KEY = "pending_user_turn"

-    # Event-driven state transition table.
-    # Handlers return an event string; the driver looks up the next state here.
-    _TRANSITIONS: dict[tuple[TurnState, str], TurnState] = {
-        (TurnState.RESTORE, "ok"): TurnState.COMPACT,
-        (TurnState.COMPACT, "ok"): TurnState.COMMAND,
-        (TurnState.COMMAND, "dispatch"): TurnState.BUILD,
-        (TurnState.COMMAND, "shortcut"): TurnState.DONE,
-        (TurnState.BUILD, "ok"): TurnState.RUN,
-        (TurnState.RUN, "ok"): TurnState.SAVE,
-        (TurnState.SAVE, "ok"): TurnState.RESPOND,
-        (TurnState.RESPOND, "ok"): TurnState.DONE,
-    }
-
    def __init__(
        self,
        bus: MessageBus,
@@ -291,6 +260,7 @@ class AgentLoop:
        model_presets: dict[str, ModelPresetConfig] | None = None,
        preset_catalog_loader: preset_helpers.PresetCatalogLoader | None = None,
        model_preset: str | None = None,
+        dream_model_preset: str | None = None,
        preset_snapshot_loader: preset_helpers.PresetSnapshotLoader | None = None,
        runtime_events: RuntimeEventBus | None = None,
        turn_delivery_factory: TurnDeliveryFactory | None = None,
@@ -329,7 +299,7 @@ class AgentLoop:
        initial_context_window = (
            context_window_tokens
            if context_window_tokens is not None
-            else defaults.context_window_tokens
+            else ModelPresetConfig(model=initial_model).context_window_tokens
        )
        configured_presets = model_presets or {}
        self.runtime_resolver = ModelRuntimeResolver(
@@ -345,6 +315,7 @@ class AgentLoop:
            provider_snapshot_loader=provider_snapshot_loader,
            preset_snapshot_loader=preset_snapshot_loader,
        )
+        self.dream_model_preset = dream_model_preset
        self.context_block_limit = context_block_limit
        self.max_tool_result_chars = (
            max_tool_result_chars
@@ -404,8 +375,8 @@ class AgentLoop:
        self._mcp_stacks: dict[str, MCPConnection] = {}
        self._mcp_connecting = False
        self._runtime_context_providers: list[RuntimeContextProvider] = []
-        self._active_tasks: dict[str, list[asyncio.Task]] = {}  # session_key -> tasks
-        self._background_tasks: list[asyncio.Task] = []
+        self._active_tasks: dict[str, set[asyncio.Task[Any]]] = {}
+        self._background_tasks: set[asyncio.Task[Any]] = set()
        self._session_locks: dict[str, asyncio.Lock] = {}
        # Per-session pending queues for mid-turn message injection.
        # When a session has an active task, new messages for that session
@@ -474,15 +445,20 @@ class AgentLoop:
        if bus is None:
            bus = MessageBus()
        defaults = config.agents.defaults
-        provider = extra.pop("provider", None) or make_provider(config)
+        explicit_provider = extra.pop("provider", None)
+        provider = explicit_provider or make_provider(config)
        resolved = config.resolve_preset()
        model = extra.pop("model", None) or resolved.model
        context_window_tokens = extra.pop("context_window_tokens", None) or resolved.context_window_tokens
        provider_snapshot_loader = extra.pop("provider_snapshot_loader", None)
-        preset_snapshot_loader = extra.pop("preset_snapshot_loader", None) or preset_helpers.make_preset_snapshot_loader(
-            config,
-            provider_snapshot_loader,
-        )
+        preset_snapshot_loader = extra.pop("preset_snapshot_loader", None)
+        if preset_snapshot_loader is None and (
+            explicit_provider is None or provider_snapshot_loader is not None
+        ):
+            preset_snapshot_loader = preset_helpers.make_preset_snapshot_loader(
+                config,
+                provider_snapshot_loader,
+            )
        return cls(
            bus=bus,
            provider=provider,
@@ -508,6 +484,7 @@ class AgentLoop:
            tools_config=config.tools,
            model_presets=preset_helpers.configured_model_presets(config),
            model_preset=defaults.model_preset,
+            dream_model_preset=defaults.dream.model_override,
            restart_mode=config.gateway.restart_mode,
            provider_snapshot_loader=provider_snapshot_loader,
            preset_snapshot_loader=preset_snapshot_loader,
@@ -569,7 +546,7 @@ class AgentLoop:
            return
        if self._runtime_model_publisher is not None:
            self._runtime_model_publisher(runtime.model, runtime.model_preset)
-        self._runtime_events().runtime_model_changed(
+        self.runtime_event_publisher.runtime_model_changed(
            runtime.model,
            runtime.model_preset,
        )
@@ -641,13 +618,17 @@ class AgentLoop:
    def register_runtime_context_provider(
        self,
        provider: RuntimeContextProvider,
-    ) -> None:
-        """Register a provider resolved once before each inbound model turn."""
-        if provider not in self._runtime_context_providers:
-            self._runtime_context_providers.append(provider)
+    ) -> Callable[[], None]:
+        """Register a per-turn context provider and return an unsubscribe callback."""
+        if provider in self._runtime_context_providers:
+            return lambda: None
+        self._runtime_context_providers.append(provider)

-    def _runtime_events(self) -> RuntimeEventPublisher:
-        return ensure_runtime_event_publisher(self)
+        def _unsubscribe() -> None:
+            with suppress(ValueError):
+                self._runtime_context_providers.remove(provider)
+
+        return _unsubscribe

    async def submit_cron_turn(self, msg: InboundMessage) -> OutboundMessage | None:
        return await self._cron_turns.submit(msg)
@@ -712,13 +693,7 @@ class AgentLoop:
            current_message=ctx.msg.content,
            media=ctx.msg.media if ctx.kind is TurnKind.USER and ctx.msg.media else None,
            channel=ctx.delivery.route.channel,
-            chat_id=str(
-                ctx.msg.metadata.get("context_chat_id") or ctx.delivery.route.chat_id
-            ),
-            current_role="user",
-            sender_id=ctx.msg.sender_id,
            session_summary=ctx.pending_summary,
-            session_metadata=ctx.session.metadata,
            workspace=scope.project_path,
            runtime_context_blocks=ctx.runtime_context_blocks,
            include_memory_recent_history=not ctx.ephemeral,
@@ -741,6 +716,7 @@ class AgentLoop:
            original_user_text=ctx.original_user_text,
            runtime=ctx.runtime,
            metadata=dict(ctx.msg.metadata or {}),
+            attributes=dict(ctx.attributes),
            sender_id=ctx.msg.sender_id,
            turn_id=ctx.turn_id,
            workspace=scope.project_path,
@@ -789,7 +765,7 @@ class AgentLoop:

        Returns the total number of cancelled tasks + subagents.
        """
-        tasks = self._active_tasks.pop(key, [])
+        tasks = tuple(self._active_tasks.pop(key, set()))
        cancelled = sum(1 for t in tasks if not t.done() and t.cancel())
        for t in tasks:
            with suppress(asyncio.CancelledError, Exception):
@@ -892,11 +868,17 @@ class AgentLoop:

            async def _to_user_message(pending_msg: InboundMessage) -> dict[str, Any]:
                content = pending_msg.content
-                media = pending_msg.media if pending_msg.media else None
-                if media:
-                    content, media = self._prepare_message_media(content, media)
-                    media = media or None
-                user_content = self.context._build_user_content(content, media)
+                image_paths = pending_msg.media if pending_msg.media else None
+                if image_paths:
+                    content, image_paths = reference_non_image_attachments(
+                        content,
+                        image_paths,
+                    )
+                    image_paths = image_paths or None
+                user_content = self.context.build_user_content(
+                    content,
+                    image_paths=image_paths,
+                )
                row: dict[str, Any] = {"role": "user", "content": user_content}
                metadata = pending_msg.metadata if isinstance(pending_msg.metadata, dict) else {}
                if pending_msg.channel != "system":
@@ -913,6 +895,7 @@ class AgentLoop:
                        original_user_text=pending_msg.content,
                        runtime=runtime,
                        metadata=dict(metadata),
+                        attributes=dict(request_ctx.attributes),
                        sender_id=pending_msg.sender_id,
                        turn_id=request_ctx.turn_id,
                        workspace=scope.project_path,
@@ -1012,6 +995,7 @@ class AgentLoop:
                chat_id=chat_id,
                message_id=message_id,
                metadata=metadata,
+                attributes=dict(request_ctx.attributes),
                session_key=active_session_key,
                workspace=effective_scope.project_path,
                tool_hint_max_length=self.tool_hint_max_length,
@@ -1183,13 +1167,9 @@ class AgentLoop:
                # Compute the effective session key before dispatching
                # This ensures /stop command can find tasks correctly when unified session is enabled
                task = asyncio.create_task(self._dispatch(msg))
-                self._active_tasks.setdefault(effective_key, []).append(task)
-                task.add_done_callback(
-                    lambda t, k=effective_key: self._active_tasks.get(k, [])
-                    and self._active_tasks[k].remove(t)
-                    if t in self._active_tasks.get(k, [])
-                    else None
-                )
+                active_tasks = self._active_tasks.setdefault(effective_key, set())
+                active_tasks.add(task)
+                task.add_done_callback(active_tasks.discard)
        finally:
            # MCP stdio transports use AnyIO cancel scopes; close them from the task that opened them.
            await self.close_mcp()
@@ -1332,8 +1312,8 @@ class AgentLoop:
    def _schedule_background(self, coro) -> None:
        """Schedule a coroutine as a tracked background task (drained on shutdown)."""
        task = asyncio.create_task(coro)
-        self._background_tasks.append(task)
-        task.add_done_callback(self._background_tasks.remove)
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)

    def stop(self) -> None:
        """Stop the agent loop."""
@@ -1356,6 +1336,7 @@ class AgentLoop:
        runtime: LLMRuntime | None = None,
        delivery: TurnDelivery | None = None,
        on_runtime_admitted: Callable[[LLMRuntime], Awaitable[None]] | None = None,
+        attributes: Mapping[str, Any] | None = None,
    ) -> OutboundMessage | None:
        """Process a single inbound message and return the response."""
        kind = TurnKind.SYSTEM if msg.channel == "system" else TurnKind.USER
@@ -1379,7 +1360,6 @@ class AgentLoop:
            msg=msg,
            session=None,
            session_key=key,
-            state=TurnState.RESTORE,
            turn_id=f"{key}:{time.time_ns()}",
            runtime=runtime,
            kind=kind,
@@ -1404,6 +1384,7 @@ class AgentLoop:
            hooks=list(hooks or []),
            hook_factories=list(hook_factories or []),
            tools=tools,
+            attributes=dict(attributes or {}),
        )
        # A streaming callback may be present even when the final text comes from a
        # non-streaming recovery. Only the last completed segment can suppress the
@@ -1449,65 +1430,47 @@ class AgentLoop:
            ctx.on_stream = _tracked_stream
            ctx.on_stream_end = _tracked_stream_end

-        while ctx.state is not TurnState.DONE:
-            handler_name = f"_state_{ctx.state.name.lower()}"
-            handler = getattr(self, handler_name, None)
-            if handler is None:
-                raise RuntimeError(f"Missing state handler for {ctx.state}")
-
-            t0 = time.perf_counter()
-            try:
-                event = await handler(ctx)
-            except Exception:
-                duration = (time.perf_counter() - t0) * 1000
-                ctx.trace.append(
-                    StateTraceEntry(
-                        state=ctx.state,
-                        started_at=t0,
-                        duration_ms=duration,
-                        event="",
-                        error="exception",
-                    )
-                )
-                raise
-
-            duration = (time.perf_counter() - t0) * 1000
-            ctx.trace.append(
-                StateTraceEntry(
-                    state=ctx.state,
-                    started_at=t0,
-                    duration_ms=duration,
-                    event=event,
-                )
-            )
-            logger.debug(
-                "[turn {}] State {} took {:.1f}ms -> event {}",
-                ctx.turn_id,
-                ctx.state.name,
-                duration,
-                event,
-            )
-
-            next_state = self._TRANSITIONS.get((ctx.state, event))
-            if next_state is None:
-                raise RuntimeError(
-                    f"[turn {ctx.turn_id}] No transition from {ctx.state} "
-                    f"on event {event!r}"
-                )
-            ctx.state = next_state
-
-        logger.debug(
-            "[turn {}] Turn completed after {} states",
-            ctx.turn_id,
-            len(ctx.trace),
-        )
+        await self._run_turn_stage(ctx, "restore", self._restore_turn)
+        await self._run_turn_stage(ctx, "compact", self._compact_session)
+        if await self._run_turn_stage(ctx, "command", self._dispatch_command):
+            return ctx.outbound
+        await self._run_turn_stage(ctx, "build", self._build_turn)
+        await self._run_turn_stage(ctx, "run", self._run_turn)
+        await self._run_turn_stage(ctx, "save", self._persist_turn)
+        await self._run_turn_stage(ctx, "respond", self._prepare_outbound)
        return ctx.outbound

+    async def _run_turn_stage(
+        self,
+        ctx: TurnContext,
+        name: str,
+        handler: Callable[[TurnContext], Awaitable[_T]],
+    ) -> _T:
+        started_at = time.perf_counter()
+        try:
+            result = await handler(ctx)
+        except Exception:
+            duration_ms = (time.perf_counter() - started_at) * 1000
+            logger.debug(
+                "[turn {}] Stage {} failed after {:.1f}ms",
+                ctx.turn_id,
+                name,
+                duration_ms,
+            )
+            raise
+        duration_ms = (time.perf_counter() - started_at) * 1000
+        logger.debug(
+            "[turn {}] Stage {} completed in {:.1f}ms",
+            ctx.turn_id,
+            name,
+            duration_ms,
+        )
+        return result
+
    def _assemble_outbound(
        self,
        msg: InboundMessage,
        final_content: str,
-        all_msgs: list[dict[str, Any]],
        stop_reason: str,
        had_injections: bool,
        streamed_content: bool,
@@ -1538,13 +1501,16 @@ class AgentLoop:
            metadata=meta,
        )

-    async def _state_restore(self, ctx: TurnContext) -> TurnState:
-        """Restore checkpoint / pending user turn; extract documents."""
+    async def _restore_turn(self, ctx: TurnContext) -> None:
+        """Restore checkpoint / pending user turn; reference non-image attachments."""
        msg = ctx.msg

        if ctx.kind is TurnKind.USER and msg.media:
-            new_content, image_only = self._prepare_message_media(msg.content, msg.media)
-            ctx.msg = dataclasses.replace(msg, content=new_content, media=image_only)
+            new_content, image_paths = reference_non_image_attachments(
+                msg.content,
+                msg.media,
+            )
+            ctx.msg = dataclasses.replace(msg, content=new_content, media=image_paths)
            msg = ctx.msg

        preview = msg.content[:80] + "..." if len(msg.content) > 80 else msg.content
@@ -1571,26 +1537,13 @@ class AgentLoop:
        if self._restore_pending_user_turn(ctx.session):
            self.sessions.save(ctx.session)

-        return "ok"
-
-    def _prepare_message_media(self, content: str, media: list[str]) -> tuple[str, list[str]]:
-        if self._should_extract_document_text():
-            return extract_documents(content, media)
-        return reference_non_image_attachments(content, media)
-
-    def _should_extract_document_text(self) -> bool:
-        if self.channels_config is None:
-            return True
-        return self.channels_config.extract_document_text
-
-    async def _state_compact(self, ctx: TurnContext) -> str:
+    async def _compact_session(self, ctx: TurnContext) -> None:
        ctx.session, pending = self.auto_compact.prepare_session(ctx.session, ctx.session_key)
        ctx.pending_summary = pending
-        return "ok"

-    async def _state_command(self, ctx: TurnContext) -> str:
+    async def _dispatch_command(self, ctx: TurnContext) -> bool:
        if ctx.kind is TurnKind.SYSTEM:
-            return "dispatch"
+            return False
        raw = ctx.msg.content.strip()
        _, automation_metadata = automation_history_overrides(ctx.msg.metadata)
        is_user_turn = (
@@ -1624,16 +1577,29 @@ class AgentLoop:
                ctx.session.add_message(
                    "assistant", result.content, _command=True
                )
-                self.sessions.save(ctx.session)
                self._clear_pending_user_turn(ctx.session)
-            return "shortcut"
-        return "dispatch"
+                self.sessions.save(ctx.session)
+                if not ctx.ephemeral:
+                    await self.runtime_event_publisher.session_turn_persisted(
+                        ctx.msg,
+                        ctx.session_key,
+                        turn_id=ctx.turn_id,
+                        attributes=ctx.attributes,
+                    )
+            return True
+        return False

-    async def _state_build(self, ctx: TurnContext) -> str:
+    async def _build_turn(self, ctx: TurnContext) -> None:
        runtime = ctx.runtime
        if runtime is None:
            runtime = self.runtime_for_session(ctx.session)
            ctx.runtime = runtime
+        if ctx.session_key.startswith("dream:"):
+            logger.info(
+                "Dream run using model={} (preset={})",
+                runtime.model,
+                runtime.model_preset or "default",
+            )
        if ctx.on_runtime_admitted is not None:
            await ctx.on_runtime_admitted(runtime)
        replay_max_messages = replay_max_messages_for_context(
@@ -1655,6 +1621,7 @@ class AgentLoop:
            "max_messages": replay_max_messages,
            "max_tokens": self._replay_token_budget(runtime),
            "extend_to_user": is_subagent,
+            "include_media": True,
        }
        ctx.history = ctx.session.get_history(**_hist_kwargs)
        if is_subagent:
@@ -1685,9 +1652,7 @@ class AgentLoop:
        if ctx.on_retry_wait is None:
            ctx.on_retry_wait = ctx.delivery.retry_wait_callback()

-        return "ok"
-
-    async def _state_run(self, ctx: TurnContext) -> str:
+    async def _run_turn(self, ctx: TurnContext) -> None:
        if ctx.visible_run_started_at is None:
            ctx.visible_run_started_at = time.time()
        await ctx.delivery.running(started_at=ctx.visible_run_started_at)
@@ -1714,17 +1679,15 @@ class AgentLoop:
            tools=ctx.tools,
            request_context=ctx.request_context,
        )
-        final_content, tools_used, all_msgs, stop_reason, had_injections = result
+        final_content, _, all_msgs, stop_reason, had_injections = result
        ctx.final_content = final_content
-        ctx.tools_used = tools_used
        ctx.all_messages = all_msgs
        ctx.stop_reason = stop_reason
        ctx.had_injections = had_injections
        if ctx.kind is TurnKind.USER:
            await turn_continuation.maybe_continue_turn(ctx)
-        return "ok"

-    async def _state_save(self, ctx: TurnContext) -> str:
+    async def _persist_turn(self, ctx: TurnContext) -> None:
        turn_continuation.prepare_save_boundary(ctx)

        if (
@@ -1765,12 +1728,18 @@ class AgentLoop:
        self._clear_pending_user_turn(ctx.session)
        self._clear_runtime_checkpoint(ctx.session)
        self.sessions.save(ctx.session)
-        return "ok"
+        if not ctx.ephemeral:
+            await self.runtime_event_publisher.session_turn_persisted(
+                ctx.msg,
+                ctx.session_key,
+                turn_id=ctx.turn_id,
+                attributes=ctx.attributes,
+            )

-    async def _state_respond(self, ctx: TurnContext) -> str:
+    async def _prepare_outbound(self, ctx: TurnContext) -> None:
        if ctx.suppress_response:
            ctx.outbound = None
-            return "ok"
+            return
        if ctx.kind is TurnKind.SYSTEM:
            ctx.outbound = ctx.delivery.background_response(
                ctx.final_content,
@@ -1778,11 +1747,10 @@ class AgentLoop:
                streamed=ctx.streamed_content,
                latency_ms=ctx.turn_latency_ms,
            )
-            return "ok"
+            return
        ctx.outbound = self._assemble_outbound(
            ctx.msg,
            ctx.final_content,
-            ctx.all_messages,
            ctx.stop_reason,
            ctx.had_injections,
            ctx.streamed_content,
@@ -1790,7 +1758,6 @@ class AgentLoop:
        )
        if ctx.ephemeral and ctx.outbound is not None:
            ctx.outbound.metadata["_stop_reason"] = ctx.stop_reason
-        return "ok"

    def _sanitize_persisted_blocks(
        self,
@@ -2049,6 +2016,7 @@ class AgentLoop:
        persist_user_message: bool = True,
        runtime: LLMRuntime | None = None,
        on_runtime_admitted: Callable[[LLMRuntime], Awaitable[None]] | None = None,
+        attributes: Mapping[str, Any] | None = None,
    ) -> OutboundMessage | None:
        """Process an external message directly and return the outbound payload."""
        if channel == "system":
@@ -2084,10 +2052,12 @@ class AgentLoop:
                    kwargs["runtime"] = runtime
                if on_runtime_admitted is not None:
                    kwargs["on_runtime_admitted"] = on_runtime_admitted
+                if attributes is not None:
+                    kwargs["attributes"] = dict(attributes)
                return await self._process_message(
                    msg,
                    **kwargs,
                )
        finally:
-            await self._runtime_events().run_status_changed(msg, session_key, "idle")
-            self._runtime_events().clear_turn(session_key)
+            await self.runtime_event_publisher.run_status_changed(msg, session_key, "idle")
+            self.runtime_event_publisher.clear_turn(session_key)
@@ -19,10 +19,12 @@ from nanobot.runtime_context import public_history_messages
 from nanobot.session.manager import Session, SessionManager
 from nanobot.utils.gitstore import GitStore
 from nanobot.utils.helpers import (
+    content_with_media_breadcrumbs,
    ensure_dir,
    estimate_message_tokens,
    estimate_prompt_tokens_chain,
    find_legal_message_start,
+    image_placeholder_text,
    recent_message_start_index,
    strip_think,
    truncate_text,
@@ -433,13 +435,33 @@ class MemoryStore:
        ]

    def compact_history(self) -> None:
-        """Drop oldest entries if the file exceeds *max_history_entries*."""
+        """Drop oldest processed entries without discarding pending Dream input."""
        if self.max_history_entries <= 0:
            return
        entries = self._read_entries()
        if len(entries) <= self.max_history_entries:
            return
-        kept = entries[-self.max_history_entries:]
+        last_dream_cursor = self.get_last_dream_cursor()
+        first_unprocessed = next(
+            (
+                index
+                for index, entry in enumerate(entries)
+                if (
+                    (cursor := self._valid_cursor(entry.get("cursor"))) is not None
+                    and cursor > last_dream_cursor
+                )
+            ),
+            len(entries),
+        )
+        keep_from = min(len(entries) - self.max_history_entries, first_unprocessed)
+        kept = entries[keep_from:]
+        if len(kept) > self.max_history_entries:
+            logger.warning(
+                "History compaction retained {} unprocessed entries beyond the configured "
+                "limit of {}",
+                len(kept),
+                self.max_history_entries,
+            )
        self._write_entries(kept)

    # -- JSONL helpers -------------------------------------------------------
@@ -569,7 +591,7 @@ class MemoryStore:

        batch = entries[:max_entries]
        history_text = "\n".join(
-            f"[{e['timestamp']}] {truncate_text(e['content'], 500)}"
+            f"[{e['timestamp']}] {truncate_text(e['content'], 1000)}"
            for e in batch
        )
        template = self._dream_template()
@@ -650,6 +672,7 @@ class MemoryStore:
        tools.register(WriteFileTool(
            workspace=workspace,
            allowed_dir=skills_dir,
+            extra_write_allowed_files=editable_files,
            file_states=file_states,
        ))
        return tools
@@ -674,14 +697,58 @@ class MemoryStore:
    def _format_messages(messages: list[dict]) -> str:
        lines = []
        for message in messages:
-            if not message.get("content"):
+            content = message.get("content") or ""
+            media = message.get("media")
+            media_paths = (
+                [
+                    path.replace("\r", " ").replace("\n", " ")
+                    for path in media[:16]
+                    if isinstance(path, str) and path
+                ]
+                if isinstance(media, list)
+                else []
+            )
+            content = content_with_media_breadcrumbs(
+                message.get("role"),
+                content,
+                media_paths,
+            )
+            if not content:
                continue
            tools = f" [tools: {', '.join(message['tools_used'])}]" if message.get("tools_used") else ""
            lines.append(
-                f"[{message.get('timestamp', '?')[:16]}] {message['role'].upper()}{tools}: {message['content']}"
+                f"[{message.get('timestamp', '?')[:16]}] "
+                f"{message['role'].upper()}{tools}: {content}"
            )
        return "\n".join(lines)

+    @staticmethod
+    def _media_manifest(messages: list[dict]) -> str:
+        paths: list[str] = []
+        seen: set[str] = set()
+        for message in messages:
+            media = message.get("media")
+            if not isinstance(media, list):
+                continue
+            for raw_path in media:
+                if not isinstance(raw_path, str) or not raw_path:
+                    continue
+                path = raw_path.replace("\r", " ").replace("\n", " ")
+                if path in seen:
+                    continue
+                seen.add(path)
+                paths.append(path)
+                if len(paths) >= 64:
+                    break
+            if len(paths) >= 64:
+                break
+        if not paths:
+            return ""
+        return "Archived attachments:\n" + "\n".join(
+            f"- {image_placeholder_text(path)}"
+            for path in paths
+        )
+
    def raw_archive(
        self,
        messages: list[dict],
@@ -691,10 +758,11 @@ class MemoryStore:
    ) -> None:
        """Fallback: dump raw messages to history.jsonl without LLM summarization."""
        limit = max_chars if max_chars is not None else _RAW_ARCHIVE_MAX_CHARS
-        formatted = truncate_text(
-            self._format_messages(public_history_messages(messages)),
-            limit,
-        )
+        formatted = self._format_messages(public_history_messages(messages))
+        manifest = self._media_manifest(messages)
+        if manifest:
+            formatted = f"{manifest}\n\n{formatted}"
+        formatted = truncate_text(formatted, limit)
        self.append_history(
            f"[RAW] {len(messages)} messages\n"
            f"{formatted}",
@@ -912,7 +980,7 @@ class Consolidator:
    ) -> tuple[int, str]:
        """Estimate prompt size from the full unconsolidated session tail."""
        history = self._full_unconsolidated_history(session)
-        channel, chat_id = (session.key.split(":", 1) if ":" in session.key else (None, None))
+        channel = session.key.split(":", 1)[0] if ":" in session.key else None
        # Include archived summary in estimation so the budget accounts for it.
        meta = session.metadata.get("_last_summary")
        summary = meta.get("text") if isinstance(meta, dict) else (meta if isinstance(meta, str) else None)
@@ -920,10 +988,7 @@ class Consolidator:
            history=history,
            current_message="[token-probe]",
            channel=channel,
-            chat_id=chat_id,
-            sender_id=None,
            session_summary=summary,
-            session_metadata=session.metadata,
            session_key=session.key,
            unified_session=self.unified_session,
        )
@@ -1002,6 +1067,11 @@ class Consolidator:
            self.store.raw_archive(messages, session_key=session_key)
            return None
        summary = response.content or "[no summary]"
+        manifest = MemoryStore._media_manifest(messages)
+        if manifest:
+            # Keep the deterministic manifest before generated prose so normal
+            # archive truncation preserves attachment references first.
+            summary = f"{manifest}\n\n{summary}"
        self.store.append_history(
            summary,
            max_chars=_ARCHIVE_SUMMARY_MAX_CHARS,
@@ -23,7 +23,7 @@ def default_selection_signature(


 def configured_model_presets(config: Any) -> dict[str, ModelPresetConfig]:
-    return {**config.model_presets, "default": config.resolve_default_preset()}
+    return dict(config.model_presets)


 def load_model_preset_catalog(
@@ -33,7 +33,10 @@ def load_model_preset_catalog(
    from nanobot.config.loader import load_config, resolve_config_env_vars

    return configured_model_presets(
-        resolve_config_env_vars(load_config(config_path)),
+        resolve_config_env_vars(
+            load_config(config_path),
+            config_path=config_path,
+        ),
    )


@@ -58,6 +61,7 @@ def build_static_preset_snapshot(
        signature=("model_preset", name, preset.model_dump_json()),
        generation=preset.to_generation_settings(),
        model_preset=name,
+        supports_image_input=preset.supports_image_input,
    )


@@ -788,6 +788,7 @@ class AgentRunner:
        kwargs["temperature"] = generation.temperature
        kwargs["max_tokens"] = generation.max_tokens
        kwargs["reasoning_effort"] = generation.reasoning_effort
+        kwargs["supports_image_input"] = spec.runtime.supports_image_input
        return kwargs

    async def _request_model(
@@ -1327,7 +1328,7 @@ class AgentRunner:
                return payload, event, exc
            return payload, event, None

-        if is_tool_error_result(tool_call.name, result):
+        if is_tool_error_result(result):
            await hook.on_execute_tool_error(context, tool_call, tool, params, result)
            event = {
                "name": tool_call.name,
@@ -26,7 +26,7 @@ from nanobot.agent.tools.loader import ToolLoader
 from nanobot.agent.tools.registry import ToolRegistry
 from nanobot.bus.events import InboundMessage
 from nanobot.bus.queue import MessageBus
-from nanobot.config.schema import AgentDefaults, ToolsConfig
+from nanobot.config.schema import AgentDefaults, ModelPresetConfig, ToolsConfig
 from nanobot.providers.base import LLMProvider
 from nanobot.security.workspace_access import (
    WorkspaceScope,
@@ -121,7 +121,9 @@ class SubagentManager:
            self._compat_runtime = LLMRuntime.capture(
                provider,
                model or provider.get_default_model(),
-                context_window_tokens=defaults.context_window_tokens,
+                context_window_tokens=ModelPresetConfig(
+                    model=model or provider.get_default_model()
+                ).context_window_tokens,
            )
        self.workspace = workspace
        self.bus = bus
@@ -161,7 +163,7 @@ class SubagentManager:
        context_window_tokens = (
            self._compat_runtime.context_window_tokens
            if self._compat_runtime is not None
-            else AgentDefaults().context_window_tokens
+            else ModelPresetConfig(model=model).context_window_tokens
        )
        self._compat_runtime = LLMRuntime.capture(
            provider,
@@ -39,12 +39,6 @@ def _validate_patch_path(path: str) -> str:
    return normalized


-def _lines_to_text(lines: list[str]) -> str:
-    if not lines:
-        return ""
-    return "\n".join(lines) + "\n"
-
-
 def _text_line_count(text: str) -> int:
    if not text:
        return 0
@@ -29,6 +29,7 @@ class RequestContext:
    sender_id: str | None = None
    turn_id: str | None = None
    workspace: Path | None = None
+    attributes: dict[str, Any] = field(default_factory=dict)


@runtime_checkable
@@ -28,7 +28,7 @@ _CRON_PARAMETERS = tool_parameters_schema(
        "(e.g., 'Send a reminder to WeChat: xxx' or 'Check system status and report'). "
        "Not used for action='list' or action='remove'."
    ),
-    every_seconds=IntegerSchema(0, description="Interval in seconds (for recurring tasks)"),
+    every_seconds=IntegerSchema(description="Interval in seconds (for recurring tasks)"),
    cron_expr=StringSchema("Cron expression like '0 9 * * *' (for scheduled tasks)"),
    tz=StringSchema(
        "Optional IANA timezone for cron expressions (e.g. 'America/Vancouver'). "
@@ -138,8 +138,6 @@ class CronTool(Tool):
        tz: str | None = None,
        at: str | None = None,
        job_id: str | None = None,
-        deliver: bool = True,
-        **kwargs: Any,
    ) -> str:
        if action == "add":
            if self._in_cron_context.get():
@@ -447,7 +447,6 @@ def format_session_poll(session_id: str, poll: _SessionPoll) -> str:
            default=False,
        ),
        yield_time_ms=IntegerSchema(
-            DEFAULT_YIELD_MS,
            description="Milliseconds to wait before returning recent output (default 1000, max 30000).",
            minimum=0,
            maximum=MAX_YIELD_MS,
@@ -458,20 +457,17 @@ def format_session_poll(session_id: str, poll: _SessionPoll) -> str:
            nullable=True,
        ),
        wait_timeout_ms=IntegerSchema(
-            DEFAULT_WAIT_FOR_MS,
            description="Maximum milliseconds to wait for wait_for text (default 10000, max 120000).",
            minimum=0,
            maximum=MAX_WAIT_FOR_MS,
            nullable=True,
        ),
        max_output_chars=IntegerSchema(
-            DEFAULT_MAX_OUTPUT_CHARS,
            description="Maximum output characters to return from this poll (default 10000, max 50000).",
            minimum=1000,
            maximum=MAX_OUTPUT_CHARS,
        ),
        max_output_tokens=IntegerSchema(
-            DEFAULT_MAX_OUTPUT_CHARS,
            description="Compatibility alias for max_output_chars. The current runtime uses a character budget.",
            minimum=1000,
            maximum=MAX_OUTPUT_CHARS,
@@ -226,12 +226,10 @@ def _builtin_skill_read_path(path: str) -> Path | None:
    tool_parameters_schema(
        path=StringSchema("The file path to read"),
        offset=IntegerSchema(
-            1,
            description="Line number to start reading from (1-indexed, default 1)",
            minimum=1,
        ),
        limit=IntegerSchema(
-            2000,
            description="Maximum number of lines to read (default 2000)",
            minimum=1,
        ),
@@ -263,6 +261,8 @@ class ReadFileTool(_FsTool):
            "Text output format: LINE_NUM|CONTENT. "
            "Images return visual content for analysis. "
            "Supports PDF, DOCX, XLSX, PPTX documents. "
+            "Uploaded non-image attachments are referenced by path; read them "
+            "with this tool only when their contents are needed. "
            "Use find_files/list_dir first when the path is uncertain. "
            "Read the relevant range before editing so replacements or patches "
            "are based on current content. "
@@ -368,11 +368,25 @@ class ReadFileTool(_FsTool):
            try:
                text_content = raw.decode("utf-8")
            except UnicodeDecodeError:
-                # Binary file - return error message
-                mime = detect_image_mime(raw) or mimetypes.guess_type(path)[0]
-                if mime and mime.startswith("image/"):
-                    return build_image_content_blocks(raw, mime, str(fp), f"(Image file: {path})")
-                return ToolResult.error(f"Error: Cannot read binary file {path} (MIME: {mime or 'unknown'}). Only UTF-8 text and images are supported.")
+                # Match the former eager extractor for known text formats while
+                # keeping arbitrary binary files on the guarded error path.
+                from nanobot.utils.document import _is_text_extension
+
+                if _is_text_extension(fp.suffix.lower()):
+                    text_content = raw.decode("latin-1")
+                else:
+                    mime = detect_image_mime(raw) or mimetypes.guess_type(path)[0]
+                    if mime and mime.startswith("image/"):
+                        return build_image_content_blocks(
+                            raw,
+                            mime,
+                            str(fp),
+                            f"(Image file: {path})",
+                        )
+                    return ToolResult.error(
+                        f"Error: Cannot read binary file {path} (MIME: {mime or 'unknown'}). "
+                        "Only supported text files and images can be read."
+                    )

            # Normalize CRLF -> LF before line-splitting. Primarily a Windows
            # concern (git checkouts with autocrlf, editors saving CRLF) but
@@ -790,13 +804,11 @@ def _find_match(content: str, old_text: str) -> tuple[str | None, int]:
        new_text=StringSchema("The text to replace with"),
        replace_all=BooleanSchema(description="Replace all occurrences (default false)"),
        occurrence=IntegerSchema(
-            1,
            description="Optional 1-based occurrence to replace when old_text appears multiple times.",
            minimum=1,
            nullable=True,
        ),
        line_hint=IntegerSchema(
-            1,
            description=(
                "Optional exact 1-based target line copied from read_file. "
                "The selected old_text match must cover this line."
@@ -805,7 +817,6 @@ def _find_match(content: str, old_text: str) -> tuple[str | None, int]:
            nullable=True,
        ),
        expected_replacements=IntegerSchema(
-            1,
            description="Optional guard for the number of replacements that must be made.",
            minimum=1,
            nullable=True,
@@ -1036,7 +1047,6 @@ class EditFileTool(_FsTool):
        path=StringSchema("The directory path to list"),
        recursive=BooleanSchema(description="Recursively list all files (default false)"),
        max_entries=IntegerSchema(
-            200,
            description="Maximum entries to return (default 200)",
            minimum=1,
        ),
@@ -1273,7 +1273,7 @@ async def reload_servers(state: Any, registry: ToolRegistry) -> dict[str, Any]:

        tools_removed = 0
        for name in [*removed, *changed]:
-            tools_removed += _unregister_server_tools(state, registry, name)
+            tools_removed += _unregister_server_tools(registry, name)
            await _close_server(state, name)

        state._mcp_servers = next_servers
@@ -1447,7 +1447,7 @@ async def _refresh_terminated_server(
            return current_tool

        logger.warning("MCP server '{}' session terminated; refreshing connection", server_name)
-        _unregister_server_tools(state, registry, server_name)
+        _unregister_server_tools(registry, server_name)
        await _close_server(state, server_name)

        connected = await connect_mcp_servers({server_name: cfg}, registry)
@@ -1479,7 +1479,7 @@ def _tool_belongs_to_server(tool: Tool | None, tool_name: str, server_name: str)
    return tool_name.startswith(_tool_prefix(server_name))


-def _unregister_server_tools(state: Any, registry: ToolRegistry, server_name: str) -> int:
+def _unregister_server_tools(registry: ToolRegistry, server_name: str) -> int:
    removed = 0
    for tool_name in list(registry.tool_names):
        tool = registry.get(tool_name)
@@ -67,14 +67,6 @@ class MessageTool(Tool):
        self._fallback_message_id = default_message_id
        self._fallback_metadata: dict[str, Any] = {}
        self._sent_in_turn_var: ContextVar[bool] = ContextVar("message_sent_in_turn", default=False)
-        self._turn_delivered_media_var: ContextVar[tuple[str, ...]] = ContextVar(
-            "message_turn_delivered_media",
-            default=(),
-        )
-        self._record_channel_delivery_var: ContextVar[bool] = ContextVar(
-            "message_record_channel_delivery",
-            default=False,
-        )
        self._suppress_delivery_var: ContextVar[bool] = ContextVar(
            "message_suppress_delivery",
            default=False,
@@ -96,19 +88,6 @@ class MessageTool(Tool):
    def start_turn(self) -> None:
        """Reset per-turn send tracking."""
        self._sent_in_turn = False
-        self._turn_delivered_media_var.set(())
-
-    def turn_delivered_media_paths(self) -> list[str]:
-        """Absolute paths attached via this tool to the active chat in the current turn."""
-        return list(self._turn_delivered_media_var.get())
-
-    def set_record_channel_delivery(self, active: bool):
-        """Mark tool-sent messages as proactive channel deliveries."""
-        return self._record_channel_delivery_var.set(active)
-
-    def reset_record_channel_delivery(self, token) -> None:
-        """Restore previous proactive delivery recording state."""
-        self._record_channel_delivery_var.reset(token)

    def set_suppress_delivery(self, active: bool):
        """Acknowledge but don't deliver tool sends (heartbeat internal check)."""
@@ -241,7 +220,7 @@ class MessageTool(Tool):
        metadata = dict(default_metadata) if same_target else {}
        if message_id:
            metadata["message_id"] = message_id
-        if self._record_channel_delivery_var.get() or media:
+        if media:
            metadata["_record_channel_delivery"] = True

        msg = OutboundMessage(
@@ -261,9 +240,6 @@ class MessageTool(Tool):
            await self._send_callback(msg)
            if channel == default_channel and chat_id == default_chat_id:
                self._sent_in_turn = True
-                if media:
-                    prev = self._turn_delivered_media_var.get()
-                    self._turn_delivered_media_var.set(prev + tuple(str(p) for p in media))
            media_info = f" with {len(media)} attachments" if media else ""
            button_info = f" with {sum(len(row) for row in buttons)} button(s)" if buttons else ""
            return f"Message sent to {channel}:{chat_id}{media_info}{button_info}"
@@ -12,7 +12,7 @@ if TYPE_CHECKING:
    from nanobot.runtime_context import RuntimeContextProvider


-def is_tool_error_result(name: str, result: Any) -> bool:
+def is_tool_error_result(result: Any) -> bool:
    return isinstance(result, ToolResult) and result.is_error


@@ -193,7 +193,7 @@ class ToolRegistry:
        try:
            assert tool is not None  # guarded by prepare_call()
            result = await tool.execute(**params)
-            if is_tool_error_result(name, result):
+            if is_tool_error_result(result):
                return ToolResult.error(str(result) + hint)
            return result
        except Exception as e:
@@ -52,11 +52,10 @@ class StringSchema(Schema):


 class IntegerSchema(Schema):
-    """Integer parameter: optional placeholder int (legacy ctor signature), description, and bounds."""
+    """Integer parameter with a description and optional bounds."""

    def __init__(
        self,
-        value: int = 0,
        *,
        description: str = "",
        minimum: int | None = None,
@@ -64,7 +63,6 @@ class IntegerSchema(Schema):
        enum: tuple[int, ...] | list[int] | None = None,
        nullable: bool = False,
    ) -> None:
-        self._value = value
        self._description = description
        self._minimum = minimum
        self._maximum = maximum
@@ -92,7 +90,6 @@ class NumberSchema(Schema):

    def __init__(
        self,
-        value: float = 0.0,
        *,
        description: str = "",
        minimum: float | None = None,
@@ -100,7 +97,6 @@ class NumberSchema(Schema):
        enum: tuple[float, ...] | list[float] | None = None,
        nullable: bool = False,
    ) -> None:
-        self._value = value
        self._description = description
        self._minimum = minimum
        self._maximum = maximum
@@ -108,7 +108,6 @@ class _PreparedCommand:
        working_dir=StringSchema("Optional working directory for the command"),
        workdir=StringSchema("Compatibility alias for working_dir"),
        timeout=IntegerSchema(
-            60,
            description=(
                "Timeout in seconds. Increase for long-running commands "
                "like compilation or installation (default 60, max 600)."
@@ -271,13 +271,12 @@ def _normalize_volcengine_auth_level(value: Any) -> int | None:
@tool_parameters(
    tool_parameters_schema(
        query=StringSchema("Search query"),
-        count=IntegerSchema(1, description="Results (1-10)", minimum=1, maximum=10),
+        count=IntegerSchema(description="Results (1-10)", minimum=1, maximum=10),
        timeRange=StringSchema(
            "Optional time filter for providers that support it: "
            "OneDay, OneWeek, OneMonth, OneYear, or YYYY-MM-DD..YYYY-MM-DD",
        ),
        authLevel=IntegerSchema(
-            0,
            description="Optional authority filter for providers that support it: 0=all, 1=authoritative",
            minimum=0,
            maximum=1,
@@ -939,7 +938,7 @@ class WebSearchTool(Tool):
            "enum": ["markdown", "text"],
            "default": "markdown",
        },
-        maxChars=IntegerSchema(0, minimum=100),
+        maxChars=IntegerSchema(minimum=100),
        required=["url"],
    )
 )
@@ -39,6 +39,7 @@ class AgentTurnHookSpec:
    turn_hooks: list[AgentHook] = field(default_factory=list)
    ephemeral: bool = False
    run_extra_hooks_for_ephemeral: bool = False
+    attributes: dict[str, Any] | None = None


 def build_agent_turn_hook(spec: AgentTurnHookSpec) -> AgentHook:
@@ -62,6 +63,7 @@ def build_agent_turn_hook(spec: AgentTurnHookSpec) -> AgentHook:
        message_id=spec.message_id,
        session_key=spec.session_key,
        metadata=dict(spec.metadata or {}),
+        attributes=dict(spec.attributes or {}),
        ephemeral=spec.ephemeral,
    )
    hook_chain: list[AgentHook] = [progress_hook]
@@ -27,6 +27,7 @@ class RuntimeEventContext:
    chat_id: str
    session_key: str
    metadata: dict[str, Any] = field(default_factory=dict)
+    attributes: dict[str, Any] = field(default_factory=dict)


@dataclass(frozen=True)
@@ -54,6 +55,15 @@ class TurnCompleted:
    runtime: Any | None = None


+@dataclass(frozen=True)
+class SessionTurnPersisted:
+    """A completed turn has been written to local session storage."""
+
+    context: RuntimeEventContext
+    turn_id: str
+    sender_id: str
+
+
@dataclass(frozen=True)
 class GoalStateChanged:
    """A session's sustained-goal state changed."""
@@ -72,6 +82,7 @@ class RuntimeModelChanged:

 RuntimeEvent = (
    SessionTurnStarted
+    | SessionTurnPersisted
    | TurnRunStatusChanged
    | TurnCompleted
    | GoalStateChanged
@@ -79,6 +90,7 @@ RuntimeEvent = (
 )
 RuntimeEventType = (
    type[SessionTurnStarted]
+    | type[SessionTurnPersisted]
    | type[TurnRunStatusChanged]
    | type[TurnCompleted]
    | type[GoalStateChanged]
@@ -152,12 +164,14 @@ class RuntimeEventPublisher:
        chat_id: str,
        session_key: str,
        metadata: dict[str, Any] | None,
+        attributes: dict[str, Any] | None = None,
    ) -> RuntimeEventContext:
        return RuntimeEventContext(
            channel=channel,
            chat_id=chat_id,
            session_key=session_key,
            metadata=dict(metadata or {}),
+            attributes=dict(attributes or {}),
        )

    def record_turn_runtime(self, session_key: str, runtime: Any) -> None:
@@ -208,6 +222,28 @@ class RuntimeEventPublisher:
            )
        )

+    async def session_turn_persisted(
+        self,
+        msg: InboundMessage,
+        session_key: str,
+        *,
+        turn_id: str,
+        attributes: dict[str, Any] | None = None,
+    ) -> None:
+        await self.bus.publish(
+            SessionTurnPersisted(
+                context=self._context(
+                    channel=msg.channel,
+                    chat_id=msg.chat_id,
+                    session_key=session_key,
+                    metadata=msg.metadata,
+                    attributes=attributes,
+                ),
+                turn_id=turn_id,
+                sender_id=msg.sender_id,
+            )
+        )
+
    async def turn_completed(
        self,
        *,
@@ -233,19 +269,3 @@ class RuntimeEventPublisher:
        self.bus.publish_nowait(
            RuntimeModelChanged(model=model, model_preset=model_preset)
        )
-
-
-def ensure_runtime_event_publisher(owner: Any) -> RuntimeEventPublisher:
-    """Return an owner's runtime publisher, creating missing state lazily."""
-    publisher = getattr(owner, "runtime_event_publisher", None)
-    if isinstance(publisher, RuntimeEventPublisher):
-        return publisher
-
-    bus = getattr(owner, "runtime_events", None)
-    if not isinstance(bus, RuntimeEventBus):
-        bus = RuntimeEventBus()
-        owner.runtime_events = bus
-
-    publisher = RuntimeEventPublisher(bus)
-    owner.runtime_event_publisher = publisher
-    return publisher
@@ -3,8 +3,6 @@
 from __future__ import annotations

 import pkgutil
-from functools import cache
-from importlib.metadata import entry_points
 from typing import TYPE_CHECKING

 from loguru import logger
@@ -19,22 +17,6 @@ if TYPE_CHECKING:
    from nanobot.channels.base import BaseChannel


-@cache
-def _warn_legacy_channel_entry_points() -> None:
-    # TODO(v0.3.1): Remove this detection and warning. v0.3.0 is the final
-    # migration window for installed legacy channel entry points.
-    names = sorted({entry_point.name for entry_point in entry_points(group="nanobot.channels")})
-    if not names:
-        return
-    logger.warning(
-        "Legacy channel entry points were detected but will not be loaded: {}. "
-        "The '{}' entry-point group is no longer supported; use a built-in channel or "
-        "migrate it into nanobot/channels/<channel>/.",
-        ", ".join(names),
-        "nanobot.channels",
-    )
-
-
 def _channel_package_names() -> list[str]:
    import nanobot.channels as package

@@ -49,7 +31,6 @@ def discover_plugins(
    enabled_names: set[str] | None = None,
 ) -> dict[str, ChannelPlugin]:
    """Load dependency-free descriptors from self-contained channel packages."""
-    _warn_legacy_channel_entry_points()
    plugins: dict[str, ChannelPlugin] = {}
    for name in _channel_package_names():
        if enabled_names is not None and name not in enabled_names:
@@ -32,6 +32,7 @@ from nanobot.bus.outbound_events import (
 )
 from nanobot.bus.queue import MessageBus
 from nanobot.channels.base import BaseChannel
+from nanobot.command.builtin import builtin_command_starts_agent_turn
 from nanobot.config.schema import Base
 from nanobot.runtime_context import (
    RUNTIME_CONTEXT_INPUT_META,
@@ -43,7 +44,14 @@ from nanobot.security.workspace_access import (
    WorkspaceScopeError,
 )
 from nanobot.session.goal_state import goal_state_ws_blob
-from nanobot.session.webui_turns import websocket_turn_wall_started_at
+from nanobot.session.webui_turns import (
+    clear_websocket_turn_if_current,
+    mark_websocket_turn_transcript_persistence_failed,
+    register_queued_websocket_turn_if_idle,
+    websocket_turn_id,
+    websocket_turn_transcript_persistence_failed,
+    websocket_turn_wall_started_at,
+)
 from nanobot.webui.cli_apps_api import normalize_cli_app_mentions
 from nanobot.webui.forking import handle_webui_fork_chat
 from nanobot.webui.gateway_services import GatewayServices
@@ -57,6 +65,11 @@ from nanobot.webui.http_utils import (
    query_first as _query_first,
 )
 from nanobot.webui.mcp_presets_api import normalize_mcp_preset_mentions
+from nanobot.webui.metadata import (
+    WEBSOCKET_TURN_OWNER_METADATA_KEY,
+    WEBUI_TURN_METADATA_KEY,
+)
+from nanobot.webui.transcript import WEBUI_TRANSCRIPT_INCOMPLETE_KEY
 from nanobot.webui.transcription_ws import webui_transcription_event
 from nanobot.webui.websocket_logging import websockets_server_logger

@@ -317,7 +330,12 @@ class WebSocketChannel(BaseChannel):
        t0 = websocket_turn_wall_started_at(chat_id)
        if t0 is None:
            return
-        await self.send_goal_status(chat_id, "running", started_at=t0)
+        await self.send_goal_status(
+            chat_id,
+            "running",
+            started_at=t0,
+            turn_id=websocket_turn_id(chat_id),
+        )

    async def _hydrate_after_subscribe(self, chat_id: str) -> None:
        """Replay persisted or actively running per-chat state after subscribe."""
@@ -633,17 +651,40 @@ class WebSocketChannel(BaseChannel):
            if not _is_valid_chat_id(cid):
                await self._send_event(connection, "error", detail="invalid chat_id")
                return
+            raw_turn_id = envelope.get("turn_id")
+            turn_id = raw_turn_id if isinstance(raw_turn_id, str) and raw_turn_id else None
+            rejection_fields = {
+                "chat_id": cid,
+                **({"turn_id": turn_id} if turn_id else {}),
+            }
+            # The allowlist can change while an authenticated websocket stays
+            # open. Reject the exact application turn before hydration,
+            # transcript persistence, or an acceptance ACK; BaseChannel's
+            # silent authorization return must not look like successful ingress.
+            if not self.is_allowed(client_id):
+                await self._send_event(
+                    connection,
+                    "error",
+                    detail="access_denied",
+                    **rejection_fields,
+                )
+                return
            if not isinstance(content, str):
-                await self._send_event(connection, "error", detail="missing content")
+                await self._send_event(
+                    connection,
+                    "error",
+                    detail="missing content",
+                    **rejection_fields,
+                )
                return
            message_rejection = self._ingress.validate_text(content)
            if message_rejection is not None:
                await self._send_event(
                    connection,
                    "error",
-                    chat_id=cid,
                    detail="message_rejected",
                    reason=message_rejection,
+                    **rejection_fields,
                )
                return

@@ -656,6 +697,7 @@ class WebSocketChannel(BaseChannel):
                        "error",
                        detail="attachment_rejected",
                        reason="malformed",
+                        **rejection_fields,
                    )
                    return
                media_paths, reason = self._media.store_inbound_attachments(raw_media)
@@ -665,12 +707,18 @@ class WebSocketChannel(BaseChannel):
                        "error",
                        detail="attachment_rejected",
                        reason=reason,
+                        **rejection_fields,
                    )
                    return

            # Allow media-only turns (content may be empty when attachments are present).
            if not content.strip() and not media_paths:
-                await self._send_event(connection, "error", detail="missing content")
+                await self._send_event(
+                    connection,
+                    "error",
+                    detail="missing content",
+                    **rejection_fields,
+                )
                return
            # Auto-attach on first use so clients can one-shot without a separate attach.
            self._attach(connection, cid)
@@ -686,10 +734,23 @@ class WebSocketChannel(BaseChannel):
                    controls_available=self._workspace_controls_available(connection),
                ),
                chat_id=cid,
+                turn_id=turn_id,
            )
            if scope is None:
                return

+            # Hydration and scope resolution can yield. Re-check immediately
+            # before transcript/bus mutation so a mid-flight revocation cannot
+            # fall through BaseChannel's silent deny and still receive an ACK.
+            if not self.is_allowed(client_id):
+                await self._send_event(
+                    connection,
+                    "error",
+                    detail="access_denied",
+                    **rejection_fields,
+                )
+                return
+
            metadata: dict[str, Any] = {"remote": getattr(connection, "remote_address", None)}
            if envelope.get("webui") is True:
                metadata["webui"] = True
@@ -702,29 +763,48 @@ class WebSocketChannel(BaseChannel):
                metadata["mcp_presets"] = mcp_presets
            metadata[WORKSPACE_SCOPE_METADATA_KEY] = scope.metadata()
            self._workspaces.persist_scope(cid, scope)
-            if metadata.get("webui") is True and self.is_allowed(client_id):
-                self._transcripts.append_user_message(
-                    cid,
-                    content,
+            is_webui = metadata.get("webui") is True
+            queued_owner = None
+            if is_webui and builtin_command_starts_agent_turn(content):
+                queued_owner = register_queued_websocket_turn_if_idle(cid, turn_id)
+                if queued_owner is not None:
+                    metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] = queued_owner
+            accepted = False
+            try:
+                if is_webui:
+                    self._transcripts.append_user_message(
+                        cid,
+                        content,
+                        metadata=metadata,
+                        media_paths=media_paths or None,
+                        cli_apps=cli_apps or None,
+                        mcp_presets=mcp_presets or None,
+                    )
+                if is_webui and connection in self._webui_connections:
+                    quote = webui_quote_runtime_context({
+                        WEBUI_QUOTE_METADATA: envelope.get("quoted_context"),
+                    })
+                    if quote is not None:
+                        metadata[RUNTIME_CONTEXT_INPUT_META] = [quote]
+                await self._handle_message(
+                    sender_id=client_id,
+                    chat_id=cid,
+                    content=content,
+                    media=media_paths or None,
                    metadata=metadata,
-                    media_paths=media_paths or None,
-                    cli_apps=cli_apps or None,
-                    mcp_presets=mcp_presets or None,
+                    is_dm=False,
+                )
+                accepted = True
+            finally:
+                if not accepted and queued_owner is not None:
+                    clear_websocket_turn_if_current(cid, queued_owner)
+            if is_webui and turn_id:
+                await self._send_event(
+                    connection,
+                    "message_accepted",
+                    chat_id=cid,
+                    turn_id=turn_id,
                )
-            if metadata.get("webui") is True and connection in self._webui_connections:
-                quote = webui_quote_runtime_context({
-                    WEBUI_QUOTE_METADATA: envelope.get("quoted_context"),
-                })
-                if quote is not None:
-                    metadata[RUNTIME_CONTEXT_INPUT_META] = [quote]
-            await self._handle_message(
-                sender_id=client_id,
-                chat_id=cid,
-                content=content,
-                media=media_paths or None,
-                metadata=metadata,
-                is_dm=False,
-            )
            return
        await self._send_event(connection, "error", detail=f"unknown type: {t!r}")

@@ -734,6 +814,7 @@ class WebSocketChannel(BaseChannel):
        resolver: Callable[[], Any],
        *,
        chat_id: str | None = None,
+        turn_id: str | None = None,
    ) -> Any | None:
        try:
            return resolver()
@@ -744,6 +825,7 @@ class WebSocketChannel(BaseChannel):
                detail="workspace_scope_rejected",
                reason=exc.message,
                **({"chat_id": chat_id} if chat_id else {}),
+                **({"turn_id": turn_id} if turn_id else {}),
            )
            return None

@@ -782,6 +864,37 @@ class WebSocketChannel(BaseChannel):
            self.logger.exception("send failed{}", label)
            raise

+    def _persist_turn_transcript_event(
+        self,
+        chat_id: str,
+        event: dict[str, Any],
+        *,
+        metadata: dict[str, Any] | None,
+        phase: str,
+        include_source: bool = False,
+        transcript_overrides: dict[str, Any] | None = None,
+    ) -> bool:
+        """Persist one canonical turn event and retain unsafe owners on failure."""
+        persisted = self._transcripts.prepare_and_append(
+            chat_id,
+            event,
+            metadata=metadata,
+            phase=phase,
+            include_source=include_source,
+            transcript_overrides=transcript_overrides,
+        )
+        if (
+            not persisted
+            and phase in {"answer", "complete"}
+            and (metadata or {}).get("webui") is True
+        ):
+            owner = (metadata or {}).get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
+            mark_websocket_turn_transcript_persistence_failed(
+                chat_id,
+                owner if isinstance(owner, str) else None,
+            )
+        return persisted
+
    async def send(self, msg: OutboundMessage) -> None:
        event = outbound_event_from_message(msg)
        progress_event = event if isinstance(event, ProgressEvent) else None
@@ -818,21 +931,38 @@ class WebSocketChannel(BaseChannel):
                await self.send_goal_state(msg.chat_id, event.goal_state or {"active": False})
            return
        if isinstance(event, GoalStatusEvent):
-            if conns:
-                if event.status in ("running", "idle"):
+            turn_id = (msg.metadata or {}).get(WEBUI_TURN_METADATA_KEY)
+            current_turn_id = turn_id if isinstance(turn_id, str) else None
+            turn_owner = (msg.metadata or {}).get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
+            current_turn_owner = turn_owner if isinstance(turn_owner, str) else None
+            try:
+                if conns and event.status in ("running", "idle"):
                    await self.send_goal_status(
                        msg.chat_id,
                        event.status,
                        started_at=event.started_at,
+                        turn_id=current_turn_id,
+                    )
+            finally:
+                if event.status == "idle":
+                    # Cancellation/direct runs may have no turn_end, so idle is
+                    # still terminal. A failed canonical completion write is
+                    # the one case that must remain pending for safe resume.
+                    clear_websocket_turn_if_current(
+                        msg.chat_id,
+                        current_turn_owner,
+                        preserve_persistence_failure=True,
                    )
            return
        # Signal that the agent has fully finished processing the current turn.
        if isinstance(event, TurnEndEvent):
+            turn_owner = (msg.metadata or {}).get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
            await self.send_turn_end(
                msg.chat_id,
                latency_ms=event.latency_ms,
                goal_state=event.goal_state,
                metadata=msg.metadata,
+                turn_owner=turn_owner if isinstance(turn_owner, str) else None,
            )
            await self.send_session_updated(msg.chat_id, scope="thread")
            return
@@ -884,7 +1014,7 @@ class WebSocketChannel(BaseChannel):
        elif progress_event:
            payload["kind"] = "progress"
        phase = "activity" if payload.get("kind") in ("tool_hint", "progress") else "answer"
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
            msg.chat_id,
            payload,
            metadata=msg.metadata,
@@ -922,7 +1052,7 @@ class WebSocketChannel(BaseChannel):
        }
        if stream_id is not None:
            body["stream_id"] = stream_id
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
            chat_id,
            body,
            metadata=meta,
@@ -950,7 +1080,7 @@ class WebSocketChannel(BaseChannel):
        }
        if stream_id is not None:
            body["stream_id"] = stream_id
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
            chat_id,
            body,
            metadata=meta,
@@ -974,7 +1104,7 @@ class WebSocketChannel(BaseChannel):
            "chat_id": chat_id,
            "edits": edits,
        }
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
            chat_id,
            payload,
            metadata=metadata,
@@ -1026,7 +1156,7 @@ class WebSocketChannel(BaseChannel):
            body["resuming"] = True
        if stream_end and merge_next:
            body["merge_next"] = True
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
            chat_id,
            body,
            metadata=meta,
@@ -1045,6 +1175,7 @@ class WebSocketChannel(BaseChannel):
        *,
        goal_state: dict[str, Any] | None = None,
        metadata: dict[str, Any] | None = None,
+        turn_owner: str | None = None,
    ) -> None:
        """Signal that the agent has fully finished processing the current turn."""
        conns = list(self._subs.get(chat_id, ()))
@@ -1053,12 +1184,27 @@ class WebSocketChannel(BaseChannel):
            body["latency_ms"] = int(latency_ms)
        if goal_state is not None:
            body["goal_state"] = goal_state
-        self._transcripts.prepare_and_append(
+        canonical_webui_turn = (metadata or {}).get("webui") is True
+        prior_persistence_failure = (
+            canonical_webui_turn
+            and websocket_turn_transcript_persistence_failed(chat_id, turn_owner)
+        )
+        persisted = self._persist_turn_transcript_event(
            chat_id,
            body,
            metadata=metadata,
            phase="complete",
+            transcript_overrides=(
+                {WEBUI_TRANSCRIPT_INCOMPLETE_KEY: True}
+                if prior_persistence_failure
+                else None
+            ),
        )
+        if persisted:
+            # A successful completion either has a complete transcript or now
+            # carries a durable incomplete marker. The HTTP replay path can
+            # recover the latter from session history after a gateway restart.
+            clear_websocket_turn_if_current(chat_id, turn_owner)
        raw = json.dumps(body, ensure_ascii=False)
        if not conns:
            return
@@ -1081,6 +1227,7 @@ class WebSocketChannel(BaseChannel):
        status: str,
        *,
        started_at: float | None = None,
+        turn_id: str | None = None,
    ) -> None:
        """Notify subscribed clients that a turn started or finished (wall-clock hint)."""
        conns = list(self._subs.get(chat_id, ()))
@@ -1093,6 +1240,8 @@ class WebSocketChannel(BaseChannel):
        }
        if status == "running" and started_at is not None:
            body["started_at"] = started_at
+        if turn_id:
+            body["turn_id"] = turn_id
        raw = json.dumps(body, ensure_ascii=False)
        for connection in conns:
            await self._safe_send_to(connection, raw, label=" goal_status ")
@@ -49,8 +49,13 @@ from nanobot.webui.http_utils import (
 from nanobot.webui.http_utils import (
    parse_request_path as _parse_request_path,
 )
+from nanobot.webui.metadata import WEBSOCKET_TURN_OWNER_METADATA_KEY
 from nanobot.webui.settings_api import settings_payload, update_provider_settings
-from nanobot.webui.transcript import append_transcript_object, read_transcript_lines
+from nanobot.webui.transcript import (
+    append_transcript_object,
+    build_webui_thread_response,
+    read_transcript_lines,
+)

 from .ws_test_client import http_get as _http_get

@@ -164,11 +169,20 @@ async def test_start_extends_http_open_timeout_for_slow_settings_routes(

@pytest.fixture(autouse=True)
 def isolate_webui_workspace_state(tmp_path, monkeypatch) -> None:
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
    monkeypatch.setattr(
        "nanobot.webui.workspaces.get_webui_dir",
        lambda: tmp_path / "webui",
    )
+    yield
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()


@pytest.mark.asyncio
@@ -743,6 +757,7 @@ async def test_webui_scope_rejects_running_scope_change(bus: MagicMock, tmp_path
                "chat_id": "chat-running",
                "content": "hello",
                "webui": True,
+                "turn_id": "turn-scope-rejected",
                "workspace_scope": {
                    "project_path": str(other),
                    "access_mode": "full",
@@ -757,6 +772,7 @@ async def test_webui_scope_rejects_running_scope_change(bus: MagicMock, tmp_path
    assert payload["detail"] == "workspace_scope_rejected"
    assert payload["reason"] == "chat_running"
    assert payload["chat_id"] == "chat-running"
+    assert payload["turn_id"] == "turn-scope-rejected"
    bus.publish_inbound.assert_not_awaited()


@@ -1582,49 +1598,6 @@ async def test_stream_transcript_persists_without_subscribers() -> None:
    assert body["messages"][-1]["latencyMs"] == 42


-@pytest.mark.asyncio
-async def test_cron_reply_persists_for_replay_without_subscribers() -> None:
-    from nanobot.cron.webui_metadata import cron_proactive_delivery_metadata
-    from nanobot.webui.transcript import build_webui_thread_response
-
-    bus = MagicMock()
-    channel = WebSocketChannel(
-        {"enabled": True, "allowFrom": ["*"]},
-        bus,
-        gateway=_basic_handler(bus),
-    )
-    metadata = cron_proactive_delivery_metadata(
-        "websocket",
-        None,
-        turn_seed="cron:daily-digest",
-        source_label="Daily digest",
-    )
-
-    await channel.send(OutboundMessage(
-        channel="websocket",
-        chat_id="cron-offline",
-        content="The scheduled digest is ready.",
-        metadata=metadata,
-    ))
-    await channel.send(OutboundMessage(
-        channel="websocket",
-        chat_id="cron-offline",
-        content="",
-        event=TurnEndEvent(),
-        metadata=metadata,
-    ))
-
-    assert channel._subs == {}
-    body = build_webui_thread_response("websocket:cron-offline")
-    assert body is not None
-    assert body["messages"][-1]["role"] == "assistant"
-    assert body["messages"][-1]["content"] == "The scheduled digest is ready."
-    assert body["messages"][-1]["source"] == {
-        "kind": "cron",
-        "label": "Daily digest",
-    }
-
-
@pytest.mark.asyncio
 async def test_send_turn_end_emits_turn_end_event() -> None:
    bus = MagicMock()
@@ -1645,6 +1618,434 @@ async def test_send_turn_end_emits_turn_end_event() -> None:
    ]


+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("active_owner", "event_owner", "expected_cleared"),
+    [
+        ("owner-current", "owner-current", True),
+        ("owner-new", "owner-old", False),
+    ],
+)
+async def test_turn_end_persists_and_conditionally_clears_when_fanout_fails(
+    active_owner: str,
+    event_owner: str,
+    expected_cleared: bool,
+) -> None:
+    bus = MagicMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    mock_ws = AsyncMock()
+    mock_ws.send.side_effect = RuntimeError("fanout failed")
+    chat_id = f"turn-end-failure-{expected_cleared}"
+    channel._attach(mock_ws, chat_id)
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT[chat_id] = 1234.5
+    wth._WEBSOCKET_TURN_OWNERS[chat_id] = active_owner
+
+    try:
+        with pytest.raises(RuntimeError, match="fanout failed"):
+            await channel.send(OutboundMessage(
+                channel="websocket",
+                chat_id=chat_id,
+                content="",
+                metadata={WEBSOCKET_TURN_OWNER_METADATA_KEY: event_owner},
+                event=TurnEndEvent(),
+            ))
+
+        assert read_transcript_lines(f"websocket:{chat_id}")[-1]["event"] == "turn_end"
+        assert (wth.websocket_turn_wall_started_at(chat_id) is None) is expected_cleared
+        if not expected_cleared:
+            assert wth._WEBSOCKET_TURN_OWNERS[chat_id] == active_owner
+    finally:
+        wth._WEBSOCKET_TURN_WALL_STARTED_AT.pop(chat_id, None)
+        wth._WEBSOCKET_TURN_IDS.pop(chat_id, None)
+        wth._WEBSOCKET_TURN_OWNERS.pop(chat_id, None)
+
+
+@pytest.mark.asyncio
+async def test_turn_end_keeps_registry_when_transcript_persistence_fails(
+    monkeypatch,
+) -> None:
+    from nanobot.bus.events import InboundMessage
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    chat_id = "turn-end-persistence-failure"
+    owner = "owner-persist"
+    turn_id = "turn-persist"
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="hi",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": turn_id,
+            "webui": True,
+        },
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+    append = MagicMock(side_effect=OSError("disk full"))
+    monkeypatch.setattr("nanobot.webui.transcript.append_transcript_object", append)
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": turn_id,
+            "webui": True,
+        },
+        event=TurnEndEvent(),
+    ))
+
+    append.assert_called_once()
+    assert wth.websocket_turn_wall_started_at(chat_id) == 1234.5
+    assert wth.websocket_turn_id(chat_id) == turn_id
+    assert wth._WEBSOCKET_TURN_OWNERS[chat_id] == owner
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=GoalStatusEvent(status="idle"),
+    ))
+
+    # The normal WebUI idle event follows turn_end. It must not convert a
+    # failed canonical completion write into an apparently settled HTTP
+    # snapshot.
+    assert wth.websocket_turn_wall_started_at(chat_id) == 1234.5
+    assert wth.websocket_turn_id(chat_id) == turn_id
+    assert wth._WEBSOCKET_TURN_OWNERS[chat_id] == owner
+
+
+@pytest.mark.asyncio
+async def test_durable_incomplete_marker_stays_pending_without_safe_session_recovery(
+    monkeypatch,
+) -> None:
+    from nanobot.bus.events import InboundMessage
+    from nanobot.webui.transcript import build_webui_thread_response
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    chat_id = "answer-persistence-failure"
+    key = f"websocket:{chat_id}"
+    owner = "owner-answer"
+    turn_id = "turn-answer"
+    append_transcript_object(
+        key,
+        {"event": "user", "chat_id": chat_id, "text": "question", "turn_id": turn_id},
+    )
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="question",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": turn_id,
+            "webui": True,
+        },
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+
+    original_append = append_transcript_object
+
+    def fail_answer(session_key: str, event: dict[str, Any]) -> None:
+        if event.get("event") == "message":
+            raise OSError("transient disk failure")
+        original_append(session_key, event)
+
+    monkeypatch.setattr("nanobot.webui.transcript.append_transcript_object", fail_answer)
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="answer",
+        metadata=dict(inbound.metadata),
+    ))
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=TurnEndEvent(),
+    ))
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=GoalStatusEvent(status="idle"),
+    ))
+
+    # Simulate a gateway restart: no process-local owner survives, so the
+    # persisted marker must be sufficient to reject canonical completion.
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
+    body = build_webui_thread_response(
+        key,
+        active_turn_started_at=wth.websocket_turn_wall_started_at(chat_id),
+        active_turn_id=wth.websocket_turn_id(chat_id),
+        active_turn_transcript_persistence_failed=(
+            wth.websocket_turn_transcript_persistence_failed(chat_id)
+        ),
+    )
+    assert body is not None
+    assert read_transcript_lines(key)[-1]["transcript_incomplete"] is True
+    assert body["completed_turn_ids"] == []
+    assert [(message["role"], message["content"]) for message in body["messages"]] == [
+        ("user", "question"),
+    ]
+    assert body["has_pending_tool_calls"] is True
+    assert chat_id not in wth._WEBSOCKET_TURN_OWNERS
+
+
+@pytest.mark.asyncio
+async def test_http_replay_recovers_marked_answer_from_session_after_gateway_restart(
+    tmp_path,
+    monkeypatch,
+) -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.bus.events import InboundMessage
+
+    chat_id = "answer-recovery-after-restart"
+    key = f"websocket:{chat_id}"
+    owner = "owner-answer-recovery"
+    turn_id = "turn-answer-recovery"
+    sessions_path = tmp_path / "sessions"
+    sessions = SessionManager(sessions_path)
+    session = sessions.get_or_create(key)
+    session.add_message("user", "question")
+    session.add_message("assistant", "durable answer")
+    sessions.save(session)
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": chat_id,
+            "text": "question",
+            "turn_id": turn_id,
+        },
+    )
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus, session_manager=sessions),
+    )
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="question",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": turn_id,
+            "webui": True,
+        },
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+
+    original_append = append_transcript_object
+
+    def fail_answer(session_key: str, event: dict[str, Any]) -> None:
+        if event.get("event") == "message":
+            raise OSError("transient disk failure")
+        original_append(session_key, event)
+
+    monkeypatch.setattr("nanobot.webui.transcript.append_transcript_object", fail_answer)
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="durable answer",
+        metadata=dict(inbound.metadata),
+    ))
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=TurnEndEvent(),
+    ))
+
+    persisted_lines = read_transcript_lines(key)
+    assert persisted_lines[-1]["event"] == "turn_end"
+    assert persisted_lines[-1]["transcript_incomplete"] is True
+
+    # Drop all process-local state and construct a fresh HTTP/session layer.
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
+    restarted_channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(
+            bus,
+            session_manager=SessionManager(sessions_path),
+        ),
+    )
+    restarted_channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    encoded_key = quote(key, safe="")
+    request = Request(
+        f"/api/sessions/{encoded_key}/webui-thread",
+        Headers([("Authorization", "Bearer tok")]),
+    )
+
+    response = restarted_channel.gateway.http._handle_webui_thread_get(
+        request,
+        encoded_key,
+    )
+
+    assert response.status_code == 200
+    body = json.loads(response.body.decode())
+    assert [(message["role"], message["content"]) for message in body["messages"]] == [
+        ("user", "question"),
+        ("assistant", "durable answer"),
+    ]
+    assert body["completed_turn_ids"] == [turn_id]
+    assert body["has_pending_tool_calls"] is False
+    assert body["active_turn_id"] is None
+
+
+@pytest.mark.asyncio
+async def test_webui_idle_clears_owner_when_no_completion_write_failed() -> None:
+    from nanobot.bus.events import InboundMessage
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    chat_id = "cancelled-webui-turn"
+    owner = "owner-cancelled"
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="hi",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": "turn-cancelled",
+            "webui": True,
+        },
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=GoalStatusEvent(status="idle"),
+    ))
+
+    assert wth.websocket_turn_wall_started_at(chat_id) is None
+    assert wth.websocket_turn_id(chat_id) is None
+    assert chat_id not in wth._WEBSOCKET_ACTIVE_TURNS
+
+
+@pytest.mark.asyncio
+async def test_non_webui_transcript_failure_does_not_block_idle_cleanup(
+    monkeypatch,
+) -> None:
+    from nanobot.bus.events import InboundMessage
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    chat_id = "direct-non-webui-failure"
+    owner = "owner-direct"
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="runtime",
+        chat_id=chat_id,
+        content="direct",
+        metadata={WEBSOCKET_TURN_OWNER_METADATA_KEY: owner},
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+    monkeypatch.setattr(
+        "nanobot.webui.transcript.append_transcript_object",
+        MagicMock(side_effect=OSError("disk full")),
+    )
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="direct answer",
+        metadata=dict(inbound.metadata),
+    ))
+
+    assert wth.websocket_turn_transcript_persistence_failed(chat_id, owner) is False
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=GoalStatusEvent(status="idle"),
+    ))
+    assert wth.websocket_turn_wall_started_at(chat_id) is None
+    assert chat_id not in wth._WEBSOCKET_ACTIVE_TURNS
+
+
+@pytest.mark.asyncio
+async def test_idle_clears_matching_owner_when_fanout_fails() -> None:
+    bus = MagicMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    mock_ws = AsyncMock()
+    mock_ws.send.side_effect = RuntimeError("fanout failed")
+    chat_id = "idle-failure"
+    owner = "owner-idle"
+    channel._attach(mock_ws, chat_id)
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT[chat_id] = 1234.5
+    wth._WEBSOCKET_TURN_OWNERS[chat_id] = owner
+
+    with pytest.raises(RuntimeError, match="fanout failed"):
+        await channel.send(OutboundMessage(
+            channel="websocket",
+            chat_id=chat_id,
+            content="",
+            metadata={WEBSOCKET_TURN_OWNER_METADATA_KEY: owner},
+            event=GoalStatusEvent(status="idle"),
+        ))
+
+    assert wth.websocket_turn_wall_started_at(chat_id) is None
+    assert chat_id not in wth._WEBSOCKET_TURN_OWNERS
+
+
@pytest.mark.asyncio
 async def test_send_turn_end_includes_latency_ms_when_present() -> None:
    bus = MagicMock()
@@ -1697,6 +2098,7 @@ async def test_send_goal_status_running_emits_event_with_started_at() -> None:
        channel="websocket",
        chat_id="chat-1",
        content="",
+        metadata={"webui_turn_id": "turn-running"},
        event=GoalStatusEvent(status="running", started_at=1_700_000_000.5),
    ))

@@ -1707,6 +2109,7 @@ async def test_send_goal_status_running_emits_event_with_started_at() -> None:
        "chat_id": "chat-1",
        "status": "running",
        "started_at": 1_700_000_000.5,
+        "turn_id": "turn-running",
    }


@@ -1721,12 +2124,18 @@ async def test_send_goal_status_idle_omits_started_at() -> None:
        channel="websocket",
        chat_id="chat-1",
        content="",
+        metadata={"webui_turn_id": "turn-idle"},
        event=GoalStatusEvent(status="idle", started_at=99.0),
    ))

    mock_ws.send.assert_awaited_once()
    body = json.loads(mock_ws.send.await_args.args[0])
-    assert body == {"event": "goal_status", "chat_id": "chat-1", "status": "idle"}
+    assert body == {
+        "event": "goal_status",
+        "chat_id": "chat-1",
+        "status": "idle",
+        "turn_id": "turn-idle",
+    }


@pytest.mark.asyncio
@@ -2053,7 +2462,7 @@ async def test_settings_api_returns_safe_subset_and_updates_whitelist(
    port = 29891
    config_path = tmp_path / "config.json"
    config = Config()
-    config.agents.defaults.model = "openai/gpt-4o"
+    config.resolve_default_preset().model = "openai/gpt-4o"
    config.providers.openai.api_key = "secret-key"
    config.model_presets["deep"] = ModelPresetConfig(
        model="anthropic/claude-opus-4-5",
@@ -2386,8 +2795,8 @@ async def test_settings_api_returns_safe_subset_and_updates_whitelist(
        assert bad_image.status_code == 400

        saved = load_config(config_path)
-        assert saved.agents.defaults.model == "atomic_chat/test"
-        assert saved.agents.defaults.provider == "atomic_chat"
+        assert saved.resolve_default_preset().model == "atomic_chat/test"
+        assert saved.resolve_default_preset().provider == "atomic_chat"
        assert saved.agents.defaults.model_preset == "fast-writing"
        assert saved.agents.defaults.fallback_models == ["deep"]
        assert saved.model_presets["fast-writing"].label == "Codex"
@@ -2592,7 +3001,7 @@ def test_settings_payload_normalizes_camel_case_provider(
 ) -> None:
    config_path = tmp_path / "config.json"
    config = Config()
-    config.agents.defaults.provider = "minimaxAnthropic"
+    config.resolve_default_preset().provider = "minimaxAnthropic"
    save_config(config, config_path)
    monkeypatch.setattr("nanobot.config.loader._current_config_path", config_path)

@@ -2768,6 +3177,147 @@ async def test_allow_from_rejects_unauthorized_client_id(bus: MagicMock) -> None
        await server_task


+@pytest.mark.asyncio
+async def test_open_connection_rejects_revoked_webui_turn_without_acceptance_ack(
+    bus: MagicMock,
+) -> None:
+    channel = _ch(bus, allowFrom=["alice"])
+    conn = AsyncMock()
+    conn.remote_address = ("127.0.0.1", 50123)
+
+    await channel._dispatch_envelope(
+        conn,
+        "revoked-client",
+        {
+            "type": "message",
+            "chat_id": "chat-revoked",
+            "content": "must not enter the bus",
+            "webui": True,
+            "turn_id": "turn-revoked",
+        },
+    )
+
+    payloads = [json.loads(call.args[0]) for call in conn.send.await_args_list]
+    assert payloads == [
+        {
+            "event": "error",
+            "detail": "access_denied",
+            "chat_id": "chat-revoked",
+            "turn_id": "turn-revoked",
+        }
+    ]
+    bus.publish_inbound.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_midflight_allowlist_revocation_rejects_turn_without_ack(
+    bus: MagicMock,
+) -> None:
+    channel = _ch(bus)
+    channel.is_allowed = MagicMock(side_effect=[True, False])
+    conn = AsyncMock()
+    conn.remote_address = ("127.0.0.1", 50123)
+
+    await channel._dispatch_envelope(
+        conn,
+        "webui-client",
+        {
+            "type": "message",
+            "chat_id": "chat-midflight-revoked",
+            "content": "must not be acknowledged",
+            "webui": True,
+            "turn_id": "turn-midflight-revoked",
+        },
+    )
+
+    payloads = [json.loads(call.args[0]) for call in conn.send.await_args_list]
+    assert payloads[-1] == {
+        "event": "error",
+        "detail": "access_denied",
+        "chat_id": "chat-midflight-revoked",
+        "turn_id": "turn-midflight-revoked",
+    }
+    assert all(payload["event"] != "message_accepted" for payload in payloads)
+    bus.publish_inbound.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_authorized_webui_turn_is_acked_after_bus_acceptance(
+    bus: MagicMock,
+) -> None:
+    channel = _ch(bus)
+    conn = AsyncMock()
+    conn.remote_address = ("127.0.0.1", 50123)
+
+    await channel._dispatch_envelope(
+        conn,
+        "webui-client",
+        {
+            "type": "message",
+            "chat_id": "chat-accepted",
+            "content": "accepted",
+            "webui": True,
+            "turn_id": "turn-accepted",
+        },
+    )
+
+    bus.publish_inbound.assert_awaited_once()
+    inbound = bus.publish_inbound.await_args.args[0]
+    owner = inbound.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+    assert wth.websocket_turn_id("chat-accepted") == "turn-accepted"
+    assert wth.websocket_turn_wall_started_at("chat-accepted") is not None
+    assert wth.websocket_turn_owner_is_registered(
+        "chat-accepted",
+        owner,
+        "turn-accepted",
+    )
+    thread = build_webui_thread_response(
+        "websocket:chat-accepted",
+        active_turn_started_at=wth.websocket_turn_wall_started_at("chat-accepted"),
+        active_turn_id=wth.websocket_turn_id("chat-accepted"),
+    )
+    assert thread is not None
+    assert thread["active_turn_id"] == "turn-accepted"
+    assert thread["has_pending_tool_calls"] is True
+    payloads = [json.loads(call.args[0]) for call in conn.send.await_args_list]
+    assert payloads[-1] == {
+        "event": "message_accepted",
+        "chat_id": "chat-accepted",
+        "turn_id": "turn-accepted",
+    }
+
+
+@pytest.mark.asyncio
+async def test_side_channel_command_does_not_register_queued_turn(
+    bus: MagicMock,
+) -> None:
+    channel = _ch(bus)
+    conn = AsyncMock()
+    conn.remote_address = ("127.0.0.1", 50123)
+
+    await channel._dispatch_envelope(
+        conn,
+        "webui-client",
+        {
+            "type": "message",
+            "chat_id": "chat-status",
+            "content": "/status",
+            "webui": True,
+            "turn_id": "turn-status",
+        },
+    )
+
+    inbound = bus.publish_inbound.await_args.args[0]
+    assert WEBSOCKET_TURN_OWNER_METADATA_KEY not in inbound.metadata
+    assert wth.websocket_turn_wall_started_at("chat-status") is None
+    payloads = [json.loads(call.args[0]) for call in conn.send.await_args_list]
+    assert payloads[-1] == {
+        "event": "message_accepted",
+        "chat_id": "chat-status",
+        "turn_id": "turn-status",
+    }
+
+
@pytest.mark.asyncio
 async def test_client_id_truncation(bus: MagicMock) -> None:
    port = 29883
@@ -3281,6 +3831,255 @@ def test_handle_webui_thread_get_returns_json(tmp_path, monkeypatch) -> None:
    assert len(body["messages"]) == 1
    assert body["messages"][0]["role"] == "user"
    assert body["messages"][0]["content"] == "hi"
+    assert body["has_pending_tool_calls"] is False
+
+
+def test_handle_webui_thread_get_reports_registered_turn_as_pending(
+    tmp_path,
+    monkeypatch,
+) -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.webui.transcript import append_transcript_object
+
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    monkeypatch.setattr(
+        "nanobot.session.webui_turns.websocket_turn_wall_started_at",
+        lambda chat_id: 1_700_000_000.0 if chat_id == "running" else None,
+    )
+    monkeypatch.setattr(
+        "nanobot.session.webui_turns.websocket_turn_id",
+        lambda chat_id: "turn-running" if chat_id == "running" else None,
+    )
+    key = "websocket:running"
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": "running",
+            "text": "hi",
+            "turn_id": "turn-running",
+        },
+    )
+    bus = MagicMock()
+    channel = _ch(bus)
+    channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    enc = quote(key, safe="")
+    req = Request(f"/api/sessions/{enc}/webui-thread", Headers([("Authorization", "Bearer tok")]))
+
+    resp = channel.gateway.http._handle_webui_thread_get(req, enc)
+
+    assert resp.status_code == 200
+    body = json.loads(resp.body.decode())
+    assert body["messages"][0]["content"] == "hi"
+    assert body["has_pending_tool_calls"] is True
+
+
+@pytest.mark.asyncio
+async def test_idle_registry_stays_pending_until_turn_end_is_persisted(
+    tmp_path,
+    monkeypatch,
+) -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.bus.events import InboundMessage
+    from nanobot.session import webui_turns as wth
+    from nanobot.webui.transcript import append_transcript_object
+
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    key = "websocket:idle-order"
+    turn_id = "turn-idle-order"
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": "idle-order",
+            "text": "hi",
+            "turn_id": turn_id,
+        },
+    )
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id="idle-order",
+        content="hi",
+        metadata={"webui_turn_id": turn_id},
+    )
+    channel = _ch(bus)
+    channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    enc = quote(key, safe="")
+    request = Request(
+        f"/api/sessions/{enc}/webui-thread",
+        Headers([("Authorization", "Bearer tok")]),
+    )
+
+    try:
+        await wth.publish_turn_run_status(bus, inbound, "running")
+        await wth.publish_turn_run_status(bus, inbound, "idle")
+
+        before_delivery = channel.gateway.http._handle_webui_thread_get(request, enc)
+        assert json.loads(before_delivery.body.decode())["has_pending_tool_calls"] is True
+
+        await channel.send(OutboundMessage(
+            channel="websocket",
+            chat_id="idle-order",
+            content="",
+            metadata=dict(inbound.metadata),
+            event=TurnEndEvent(),
+        ))
+
+        after_delivery = channel.gateway.http._handle_webui_thread_get(request, enc)
+        assert json.loads(after_delivery.body.decode())["has_pending_tool_calls"] is False
+        assert wth.websocket_turn_wall_started_at("idle-order") is None
+        assert wth.websocket_turn_id("idle-order") is None
+    finally:
+        wth._WEBSOCKET_TURN_WALL_STARTED_AT.pop("idle-order", None)
+        wth._WEBSOCKET_TURN_IDS.pop("idle-order", None)
+        wth._WEBSOCKET_TURN_OWNERS.pop("idle-order", None)
+
+
+@pytest.mark.asyncio
+async def test_webui_thread_api_restores_older_owner_after_latest_completes() -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.bus.events import InboundMessage
+
+    chat_id = "concurrent-projection"
+    key = f"websocket:{chat_id}"
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": chat_id,
+            "text": "first",
+            "turn_id": "turn-first",
+        },
+    )
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    first = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="first",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: "owner-first",
+            "webui_turn_id": "turn-first",
+        },
+        session_key_override="websocket:session-first",
+    )
+    second = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="second",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: "owner-second",
+            "webui_turn_id": "turn-second",
+        },
+        session_key_override="websocket:session-second",
+    )
+    await wth.publish_turn_run_status(bus, first, "running", started_at=100.0)
+    await wth.publish_turn_run_status(bus, second, "running", started_at=200.0)
+    assert wth.clear_websocket_turn_if_current(chat_id, "owner-second") is True
+
+    channel = _ch(bus)
+    channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    enc = quote(key, safe="")
+    request = Request(
+        f"/api/sessions/{enc}/webui-thread",
+        Headers([("Authorization", "Bearer tok")]),
+    )
+    response = channel.gateway.http._handle_webui_thread_get(request, enc)
+
+    assert response.status_code == 200
+    payload = json.loads(response.body.decode())
+    assert payload["has_pending_tool_calls"] is True
+    assert wth.websocket_turn_wall_started_at(chat_id) == 100.0
+    assert wth.websocket_turn_id(chat_id) == "turn-first"
+    assert wth._WEBSOCKET_TURN_OWNERS[chat_id] == "owner-first"
+
+
+@pytest.mark.parametrize(
+    ("active_turn_id", "expected_pending"),
+    [
+        ("turn-complete", False),
+        ("turn-next", True),
+    ],
+)
+def test_handle_webui_thread_get_reconciles_registered_turn_with_turn_end(
+    tmp_path,
+    monkeypatch,
+    active_turn_id: str,
+    expected_pending: bool,
+) -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.webui.transcript import append_transcript_object
+
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    monkeypatch.setattr(
+        "nanobot.session.webui_turns.websocket_turn_wall_started_at",
+        lambda chat_id: 1_700_000_000.0 if chat_id == "running" else None,
+    )
+    monkeypatch.setattr(
+        "nanobot.session.webui_turns.websocket_turn_id",
+        lambda chat_id: active_turn_id if chat_id == "running" else None,
+    )
+    key = "websocket:running"
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": "running",
+            "text": "hi",
+            "turn_id": "turn-complete",
+        },
+    )
+    append_transcript_object(
+        key,
+        {
+            "event": "message",
+            "chat_id": "running",
+            "text": "done",
+            "turn_id": "turn-complete",
+        },
+    )
+    append_transcript_object(
+        key,
+        {
+            "event": "turn_end",
+            "chat_id": "running",
+            "turn_id": "turn-complete",
+        },
+    )
+    bus = MagicMock()
+    channel = _ch(bus)
+    channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    enc = quote(key, safe="")
+    req = Request(f"/api/sessions/{enc}/webui-thread", Headers([("Authorization", "Bearer tok")]))
+
+    resp = channel.gateway.http._handle_webui_thread_get(req, enc)
+
+    assert resp.status_code == 200
+    body = json.loads(resp.body.decode())
+    assert body["messages"][-1]["content"] == "done"
+    assert body["has_pending_tool_calls"] is expected_pending
+    assert body["active_turn_id"] == active_turn_id


 def test_handle_webui_thread_get_accepts_pagination_query(tmp_path, monkeypatch) -> None:
@@ -19,6 +19,7 @@ from nanobot.channels.websocket.runtime import (
    WebSocketChannel,
    WebSocketConfig,
 )
+from nanobot.session import webui_turns as wth
 from nanobot.webui.gateway_services import build_gateway_services


@@ -59,6 +60,19 @@ def _make_channel() -> WebSocketChannel:
    return channel


+@pytest.fixture(autouse=True)
+def isolate_websocket_turn_state() -> None:
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
+    yield
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
+
+
 # -- max_message_bytes bump ----------------------------------------------------


@@ -94,6 +108,28 @@ async def test_message_without_media_backward_compatible() -> None:
    assert call.kwargs["media"] is None


+@pytest.mark.asyncio
+async def test_webui_message_acceptance_echoes_turn_id() -> None:
+    channel = _make_channel()
+    mock_conn = AsyncMock()
+    envelope = {
+        "type": "message",
+        "chat_id": "abc123",
+        "content": "hello",
+        "webui": True,
+        "turn_id": "turn-accepted",
+    }
+
+    await channel._dispatch_envelope(mock_conn, "client-1", envelope)
+
+    channel._handle_message.assert_awaited_once()
+    assert json.loads(mock_conn.send.await_args.args[0]) == {
+        "event": "message_accepted",
+        "chat_id": "abc123",
+        "turn_id": "turn-accepted",
+    }
+
+
@pytest.mark.asyncio
 async def test_message_text_policy_is_independent_from_transport_limit() -> None:
    channel = _make_channel()
@@ -102,6 +138,7 @@ async def test_message_text_policy_is_independent_from_transport_limit() -> None
        "type": "message",
        "chat_id": "abc123",
        "content": "你" * 22_000,
+        "turn_id": "turn-text-policy",
    }

    await channel._dispatch_envelope(mock_conn, "client-1", envelope)
@@ -113,6 +150,7 @@ async def test_message_text_policy_is_independent_from_transport_limit() -> None
        "chat_id": "abc123",
        "detail": "message_rejected",
        "reason": "text_too_large",
+        "turn_id": "turn-text-policy",
    }


@@ -235,6 +273,7 @@ async def test_message_rejected_when_more_than_four_images(tmp_path) -> None:
        "chat_id": "abc123",
        "content": "hi",
        "media": [{"data_url": _tiny_png_data_url()}] * 5,
+        "turn_id": "turn-attachments",
    }

    with patch(
@@ -246,8 +285,10 @@ async def test_message_rejected_when_more_than_four_images(tmp_path) -> None:
    mock_conn.send.assert_awaited_once()
    err = json.loads(mock_conn.send.call_args[0][0])
    assert err["event"] == "error"
+    assert err["chat_id"] == "abc123"
    assert err["detail"] == "attachment_rejected"
    assert err["reason"] == "too_many_images"
+    assert err["turn_id"] == "turn-attachments"


@pytest.mark.asyncio
@@ -1891,15 +1891,11 @@ async def test_webui_sidebar_state_routes_are_config_dir_scoped(
        assert initial.status_code == 200
        assert initial.json()["schema_version"] == 1
        assert initial.json()["pinned_keys"] == []
-        assert initial.json()["activity_seen_at_by_key"] == {}

        payload = {
            "pinned_keys": ["websocket:sidebar"],
            "archived_keys": ["websocket:old"],
            "title_overrides": {"websocket:sidebar": "Pinned work"},
-            "activity_seen_at_by_key": {
-                "websocket:sidebar": "2026-07-27T08:30:00Z"
-            },
            "view": {"density": "compact", "show_archived": True},
        }
        query = urlencode({"state": json.dumps(payload)})
@@ -1911,9 +1907,6 @@ async def test_webui_sidebar_state_routes_are_config_dir_scoped(
        body = updated.json()
        assert body["pinned_keys"] == ["websocket:sidebar"]
        assert body["title_overrides"] == {"websocket:sidebar": "Pinned work"}
-        assert body["activity_seen_at_by_key"] == {
-            "websocket:sidebar": "2026-07-27T08:30:00Z"
-        }
        assert body["view"]["density"] == "compact"

        state_path = tmp_path / "webui" / "sidebar-state.json"
@@ -1921,9 +1914,6 @@ async def test_webui_sidebar_state_routes_are_config_dir_scoped(
        assert json.loads(state_path.read_text(encoding="utf-8"))["pinned_keys"] == [
            "websocket:sidebar"
        ]
-        assert json.loads(state_path.read_text(encoding="utf-8"))[
-            "activity_seen_at_by_key"
-        ] == {"websocket:sidebar": "2026-07-27T08:30:00Z"}
    finally:
        await channel.stop()
        await server_task
@@ -53,9 +53,19 @@ async def test_hydrate_after_subscribe_pushes_running_when_turn_active():
    channel.send_goal_state = mock_send_goal_state
    channel.send_goal_status = mock_send_goal_status

-    with patch("nanobot.channels.websocket.runtime.websocket_turn_wall_started_at", return_value=1234567890.0):
+    with (
+        patch(
+            "nanobot.channels.websocket.runtime.websocket_turn_wall_started_at",
+            return_value=1234567890.0,
+        ),
+        patch(
+            "nanobot.channels.websocket.runtime.websocket_turn_id",
+            return_value="turn-active",
+        ),
+    ):
        await channel._hydrate_after_subscribe("test-chat")

    running_events = [e for e in sent_events if e[0] == "goal_status" and e[2] == "running"]
    assert len(running_events) == 1
    assert running_events[0][3]["started_at"] == 1234567890.0
+    assert running_events[0][3]["turn_id"] == "turn-active"
@@ -54,6 +54,7 @@ from prompt_toolkit.history import FileHistory  # noqa: E402
 from prompt_toolkit.key_binding import KeyBindings  # noqa: E402
 from prompt_toolkit.keys import Keys  # noqa: E402
 from prompt_toolkit.patch_stdout import patch_stdout  # noqa: E402
+from pydantic import ValidationError  # noqa: E402
 from rich.console import Console  # noqa: E402
 from rich.markdown import Markdown  # noqa: E402
 from rich.markup import escape  # noqa: E402
@@ -793,13 +794,93 @@ def _model_display(config: Config) -> tuple[str, str]:
    """Return (resolved_model_name, preset_tag) for display strings."""
    resolved = config.resolve_preset()
    name = config.agents.defaults.model_preset
-    tag = f" (preset: {name})" if name else ""
+    tag = f" (preset: {name})" if name != "default" else ""
    return resolved.model, tag


+def _print_config_error(error: Exception) -> None:
+    """Render a configuration failure without exposing traceback internals."""
+    from nanobot.config.errors import ConfigLoadError
+
+    console.print(Text(str(error), style="red"))
+    if isinstance(error, ConfigLoadError):
+        command = _status_command(error.path)
+        console.print(f"[dim]Check again after editing: {escape(command)}[/dim]")
+
+
+def _print_runtime_config_validation_error(
+    error: ValidationError,
+    *,
+    config_path: Path,
+    summary: str,
+    path_prefix: tuple[str | int, ...],
+    retry_command: str,
+) -> None:
+    """Render a runtime-owned Pydantic config error without exposing input values."""
+    from nanobot.config.errors import ConfigIssue, ConfigLoadError, validation_issues
+
+    issues = tuple(
+        ConfigIssue(
+            path=(*path_prefix, *issue.path),
+            message=issue.message,
+        )
+        for issue in validation_issues(error)
+    )
+    diagnostic = ConfigLoadError(
+        config_path,
+        kind="invalid_schema",
+        summary=summary,
+        issues=issues,
+    )
+    console.print(Text(str(diagnostic), style="red"))
+    console.print(f"[dim]Fix the listed setting, then retry: {escape(retry_command)}[/dim]")
+
+
+def _status_command(config_path: Path) -> str:
+    return f'nanobot status --config "{config_path}"'
+
+
+def _print_model_setup_steps(config_path: Path) -> None:
+    """Show the shortest setup routes shared by Status and Agent startup."""
+    config_arg = f'--config "{config_path}"'
+    console.print(
+        f"  WebUI: run [cyan]nanobot webui {escape(config_arg)}[/cyan], "
+        "then open Settings → Models"
+    )
+    console.print(f"  CLI:   run [cyan]nanobot onboard --wizard {escape(config_arg)}[/cyan]")
+    console.print(f"  Check: [cyan]{escape(_status_command(config_path))}[/cyan]")
+
+
+def _print_agent_start_error(error: ValueError) -> None:
+    from nanobot.config.loader import get_config_path
+
+    console.print(Text(f"Agent cannot start: {error}", style="red"))
+    console.print("Complete provider/model setup:")
+    _print_model_setup_steps(get_config_path())
+
+
+def _load_config_for_cli(
+    config_path: Path | None = None,
+    *,
+    resolve_env: bool = False,
+) -> Config:
+    """Load CLI configuration and turn expected failures into a clean exit."""
+    from nanobot.config.errors import ConfigLoadError
+    from nanobot.config.loader import load_config, resolve_config_env_vars
+
+    try:
+        loaded = load_config(config_path)
+        if resolve_env:
+            loaded = resolve_config_env_vars(loaded)
+        return loaded
+    except ConfigLoadError as exc:
+        _print_config_error(exc)
+        raise typer.Exit(1) from exc
+
+
 def _load_runtime_config(config: str | None = None, workspace: str | None = None) -> Config:
    """Load config and optionally override the active workspace."""
-    from nanobot.config.loader import load_config, resolve_config_env_vars, set_config_path
+    from nanobot.config.loader import set_config_path

    config_path = None
    if config:
@@ -810,12 +891,7 @@ def _load_runtime_config(config: str | None = None, workspace: str | None = None
        set_config_path(config_path)
        console.print(f"[dim]Using config: {config_path}[/dim]")

-    try:
-        loaded = resolve_config_env_vars(load_config(config_path))
-    except ValueError as e:
-        console.print(f"[red]Error: {e}[/red]")
-        raise typer.Exit(1)
-    _warn_deprecated_config_keys(config_path)
+    loaded = _load_config_for_cli(config_path, resolve_env=True)
    if workspace:
        loaded.agents.defaults.workspace = workspace
    return loaded
@@ -836,29 +912,12 @@ def _read_trigger_cli_message(message: str | None) -> str:
    raise typer.Exit(1)


-def _warn_deprecated_config_keys(config_path: Path | None) -> None:
-    """Hint users to remove obsolete keys from their config file."""
-    import json
-
-    from nanobot.config.loader import get_config_path
-
-    path = config_path or get_config_path()
-    try:
-        raw = json.loads(path.read_text(encoding="utf-8"))
-    except Exception:
-        return
-    if "memoryWindow" in raw.get("agents", {}).get("defaults", {}):
-        console.print(
-            "[dim]Hint: `memoryWindow` in your config is no longer used "
-            "and can be safely removed.[/dim]"
-        )
-
-
 def _load_inspection_config(
    config: str | None = None,
    workspace: str | None = None,
 ) -> tuple[Path, Config]:
    """Load config for diagnostic commands without resolving secret env refs."""
+    from nanobot.config.errors import ConfigLoadError
    from nanobot.config.loader import get_config_path, load_config, set_config_path

    config_path = None
@@ -870,10 +929,12 @@ def _load_inspection_config(
    display_path = config_path or get_config_path()
    try:
        loaded = load_config(config_path)
+    except ConfigLoadError as exc:
+        _print_config_error(exc)
+        raise typer.Exit(1) from exc
    except ValueError as exc:
        console.print(f"[red]Error: {exc}[/red]")
        raise typer.Exit(1) from exc
-    _warn_deprecated_config_keys(display_path)
    if workspace:
        loaded.agents.defaults.workspace = workspace
    return display_path, loaded
@@ -921,21 +982,15 @@ def _resolve_webui_config_path(config: str | None) -> Path:

 def _load_webui_setup_config(config_path: Path) -> Config:
    """Load config for first-run mutation without resolving env-var placeholders."""
-    from nanobot.config.loader import load_config
-
-    try:
-        return load_config(config_path)
-    except ValueError as e:
-        console.print(f"[red]Error: {e}[/red]")
-        raise typer.Exit(1) from e
+    return _load_config_for_cli(config_path)


 def _provider_setup_error(config: Config) -> str | None:
-    """Return the provider setup error, or None when the current model can start."""
-    from nanobot.providers.factory import build_provider_snapshot
+    """Return a local provider/model configuration error, or None."""
+    from nanobot.providers.factory import validate_provider_setup

    try:
-        build_provider_snapshot(config)
+        validate_provider_setup(config)
    except ValueError as exc:
        return str(exc)
    return None
@@ -957,6 +1012,60 @@ def _webui_channel_enabled(config: Config) -> bool:
    return bool(WebSocketConfig.model_validate(current).enabled)


+def _validate_gateway_startup(config: Config) -> str | None:
+    """Validate gateway startup and return a provider error recoverable through WebUI."""
+    from nanobot.config.loader import get_config_path
+
+    config_path = get_config_path()
+    try:
+        webui_config = _webui_config_dict(config)
+    except ValidationError as exc:
+        retry_command = f'nanobot gateway --config "{config_path}"'
+        _print_runtime_config_validation_error(
+            exc,
+            config_path=config_path,
+            summary="Gateway configuration is invalid.",
+            path_prefix=("channels", "websocket"),
+            retry_command=retry_command,
+        )
+        raise typer.Exit(1) from exc
+
+    provider_error = _provider_setup_error(config)
+    if not provider_error:
+        return None
+
+    if bool(webui_config["enabled"]):
+        console.print(
+            Text(f"Provider/model setup is incomplete: {provider_error}", style="yellow")
+        )
+        console.print(
+            "Gateway will start so you can configure a provider and model "
+            "in WebUI Settings → Models."
+        )
+        browser_url = _webui_browser_url(config)
+        webui_url = browser_url.split("/#/", 1)[0]
+        console.print(Text(f"WebUI: {webui_url}", style="cyan"))
+        if browser_url != webui_url:
+            secret_key = (
+                "tokenIssueSecret"
+                if str(webui_config.get("tokenIssueSecret") or "").strip()
+                else "token"
+            )
+            console.print(
+                Text(
+                    f"If prompted, enter the configured channels.websocket.{secret_key} "
+                    f"value (see {config_path}).",
+                    style="dim",
+                )
+            )
+        return provider_error
+
+    console.print(Text(f"Gateway cannot start: {provider_error}", style="red"))
+    console.print("Complete provider/model setup:")
+    _print_model_setup_steps(config_path)
+    raise typer.Exit(1)
+
+
 def _prepare_webui_bundle_for_gateway(
    config: Config,
    *,
@@ -1254,14 +1363,20 @@ def _gateway_instance_command(
    return " ".join(shlex.quote(part) for part in parts)


-def _run_quick_start_for_webui(config: Config, *, yes: bool) -> Config:
+def _run_quick_start_for_webui(
+    config: Config,
+    *,
+    yes: bool,
+    config_path: Path,
+) -> Config:
    """Offer the existing Quick Start flow when provider setup is missing."""
    if yes:
        console.print(
            "[red]Error: provider/model setup is incomplete, and --yes cannot answer "
-            "provider credentials. Run `nanobot webui` interactively or "
-            "`nanobot onboard --wizard`.[/red]"
+            "provider credentials.[/red]"
        )
+        console.print("Complete provider/model setup:")
+        _print_model_setup_steps(config_path)
        raise typer.Exit(1)

    console.print()
@@ -1453,9 +1568,12 @@ def webui(
        setup_config.agents.defaults.workspace = workspace

    try:
-        resolved_setup_config = resolve_config_env_vars(setup_config.model_copy(deep=True))
+        resolved_setup_config = resolve_config_env_vars(
+            setup_config.model_copy(deep=True),
+            config_path=config_path,
+        )
    except ValueError as exc:
-        console.print(f"[red]Error: {exc}[/red]")
+        _print_config_error(exc)
        raise typer.Exit(1) from exc

    provider_error = _provider_setup_error(resolved_setup_config)
@@ -1471,7 +1589,11 @@ def webui(
            raise typer.Exit(1)
    elif provider_error:
        console.print(f"[dim]Provider check: {provider_error}[/dim]")
-        setup_config = _run_quick_start_for_webui(setup_config, yes=yes)
+        setup_config = _run_quick_start_for_webui(
+            setup_config,
+            yes=yes,
+            config_path=config_path,
+        )
        if workspace:
            setup_config.agents.defaults.workspace = workspace

@@ -1483,6 +1605,16 @@ def webui(
        )
        _warn_webui_bind_scope(setup_config)
        webui_url = _webui_browser_url(setup_config)
+    except ValidationError as exc:
+        retry_command = f'nanobot webui --config "{config_path}"'
+        _print_runtime_config_validation_error(
+            exc,
+            config_path=config_path,
+            summary="WebUI configuration is invalid.",
+            path_prefix=("channels", "websocket"),
+            retry_command=retry_command,
+        )
+        raise typer.Exit(1) from exc
    except ValueError as exc:
        console.print(f"[red]Error: invalid WebUI channel config: {exc}[/red]")
        raise typer.Exit(1) from exc
@@ -1840,12 +1972,17 @@ def _run_gateway(
                    return None
                prompt, last_cursor = result
                key = dream_session_key()
+                resolve_dream_runtime = getattr(agent, "dream_runtime", None)
+                dream_runtime = (
+                    resolve_dream_runtime() if callable(resolve_dream_runtime) else None
+                )
                resp = await agent.process_direct(
                    prompt,
                    session_key=key,
                    ephemeral=True,
                    tools=store.build_dream_tools(),
                    on_progress=progress,
+                    runtime=dream_runtime,
                )
                # The real file delta grounds the audit record; clean completion
                # decides whether this history batch has finished processing.
@@ -2243,6 +2380,7 @@ app.add_typer(
        log_handler_id=_log_handler_id,
        load_runtime_config=_load_runtime_config,
        run_gateway=_run_gateway,
+        validate_startup_config=_validate_gateway_startup,
        prepare_webui_bundle=lambda config, mode: _prepare_webui_bundle_for_gateway(
            config,
            mode=mode,
@@ -2269,9 +2407,16 @@ def agent(
    """Interact with the agent directly."""
    from nanobot.bus.queue import MessageBus
    from nanobot.cron.service import CronService
+    from nanobot.providers.factory import make_provider
    from nanobot.providers.image_generation import image_gen_provider_configs

    config = _load_runtime_config(config, workspace)
+    try:
+        provider = make_provider(config)
+    except ValueError as exc:
+        _print_agent_start_error(exc)
+        raise typer.Exit(1) from exc
+
    sync_workspace_templates(config.workspace_path)

    bus = MessageBus()
@@ -2289,12 +2434,13 @@ def agent(
    try:
        agent_loop = AgentLoop.from_config(
            config, bus,
+            provider=provider,
            cron_service=cron,
            image_generation_provider_configs=image_gen_provider_configs(config),
            hook_factories=[create_file_edit_activity_hook],
        )
    except ValueError as exc:
-        console.print(f"[red]Error: {exc}[/red]")
+        _print_agent_start_error(exc)
        raise typer.Exit(1) from exc
    restart_notice = consume_restart_notice_from_env()
    if restart_notice and should_show_cli_restart_notice(restart_notice, session_id):
@@ -2698,11 +2844,32 @@ def status(
    )

    if config_path.exists():
+        from nanobot.config.errors import ConfigLoadError
+        from nanobot.config.loader import resolve_config_env_vars, resolve_env_refs
        from nanobot.providers.registry import PROVIDERS

        _model, _preset_tag = _model_display(loaded)
        console.print(f"Model: {_model}{_preset_tag}")

+        provider_ready = False
+        try:
+            resolved = resolve_config_env_vars(
+                loaded.model_copy(deep=True),
+                config_path=config_path,
+            )
+        except ConfigLoadError as exc:
+            console.print("Agent: [red]✗ configuration is not ready[/red]")
+            _print_config_error(exc)
+        else:
+            provider_error = _provider_setup_error(resolved)
+            if provider_error:
+                console.print(Text(f"Agent: ✗ {provider_error}", style="red"))
+                console.print("Complete provider/model setup:")
+                _print_model_setup_steps(config_path)
+            else:
+                provider_ready = True
+                console.print("Agent: [green]✓ provider/model configuration is ready[/green]")
+
        # Check API keys from registry
        for spec in PROVIDERS:
            p = getattr(loaded.providers, spec.name, None)
@@ -2712,14 +2879,25 @@ def status(
                console.print(f"{spec.label}: [green]✓ (OAuth)[/green]")
            elif spec.is_local:
                # Local deployments show api_base instead of api_key
-                if p.api_base:
+                if resolve_env_refs(p.api_base or ""):
                    console.print(f"{spec.label}: [green]✓ {p.api_base}[/green]")
                else:
                    console.print(f"{spec.label}: [dim]not set[/dim]")
            else:
-                has_key = bool(p.api_key)
+                has_key = bool(resolve_env_refs(p.api_key or ""))
                console.print(f"{spec.label}: {'[green]✓[/green]' if has_key else '[dim]not set[/dim]'}")

+        if provider_ready:
+            console.print()
+            console.print('Next: [cyan]nanobot agent -m "Hello!"[/cyan]')
+            console.print(
+                "[dim]Status does not call the model or verify network access and credentials.[/dim]"
+            )
+    else:
+        console.print("Agent: [red]✗ configuration file not found[/red]")
+        console.print("Create the provider/model configuration:")
+        _print_model_setup_steps(config_path)
+

 # ============================================================================
 # OAuth Login
@@ -2791,11 +2969,13 @@ def _set_oauth_provider_as_main(

    config = load_config(resolved_config_path)
    selected_model = (model or "").strip() or _OAUTH_PROVIDER_DEFAULT_MODELS[provider_name]
-    config.agents.defaults.model_preset = None
-    config.agents.defaults.provider = provider_name
-    config.agents.defaults.model = selected_model
+    default_preset = config.resolve_default_preset().model_copy(
+        update={"provider": provider_name, "model": selected_model}
+    )
    if provider_name == "xai_grok" and selected_model == "xai-grok/grok-4.5":
-        config.agents.defaults.context_window_tokens = 500_000
+        default_preset.context_window_tokens = 500_000
+    config.model_presets["default"] = default_preset
+    config.agents.defaults.model_preset = "default"
    save_config(config, resolved_config_path)

    saved_path = resolved_config_path or get_config_path()
@@ -29,6 +29,7 @@ from nanobot.webui.build import BuildMode

 RuntimeConfigLoader = Callable[[str | None, str | None], Config]
 GatewayRunner = Callable[..., None]
+GatewayConfigValidator = Callable[[Config], str | None]
 GatewayRuntimeFactory = Callable[..., Any]
 GatewayServiceFactory = Callable[[], Any]
 WebUIBundlePreparer = Callable[[Config, BuildMode], None]
@@ -40,6 +41,7 @@ def create_gateway_app(
    log_handler_id: int,
    load_runtime_config: RuntimeConfigLoader,
    run_gateway: GatewayRunner,
+    validate_startup_config: GatewayConfigValidator | None = None,
    runtime_factory: GatewayRuntimeFactory | None = None,
    service_factory: GatewayServiceFactory | None = None,
    prepare_webui_bundle: WebUIBundlePreparer | None = None,
@@ -149,6 +151,8 @@ def create_gateway_app(
            raise typer.Exit(1)
        if background:
            cfg = load_runtime_config(config, workspace)
+            if validate_startup_config is not None:
+                validate_startup_config(cfg)
            if prepare_webui_bundle is not None:
                prepare_webui_bundle(cfg, interactive_build_mode())
            runtime = runtime_for_instance(workspace=workspace, config=config)
@@ -171,7 +175,18 @@ def create_gateway_app(

        configure_logging(verbose)
        cfg = load_runtime_config(config, workspace)
-        run_gateway(cfg, port=port, webui_bundle_mode=interactive_build_mode())
+        unconfigured_provider_error = None
+        if validate_startup_config is not None:
+            unconfigured_provider_error = validate_startup_config(cfg)
+        if unconfigured_provider_error is None:
+            run_gateway(cfg, port=port, webui_bundle_mode=interactive_build_mode())
+        else:
+            run_gateway(
+                cfg,
+                port=port,
+                webui_bundle_mode=interactive_build_mode(),
+                unconfigured_provider_error=unconfigured_provider_error,
+            )

    @gateway_app.command("status")
    def gateway_status(
@@ -225,6 +240,8 @@ def create_gateway_app(
    ) -> None:
        """Restart the background gateway."""
        cfg = load_runtime_config(config, workspace)
+        if validate_startup_config is not None:
+            validate_startup_config(cfg)
        if prepare_webui_bundle is not None:
            prepare_webui_bundle(cfg, interactive_build_mode())
        runtime = runtime_for_instance(workspace=workspace, config=config)
@@ -755,15 +755,13 @@ def _handle_model_preset_field(
    working_model: BaseModel, field_name: str, field_display: str, current_value: Any
 ) -> None:
    """Handle the 'model_preset' field with a list of existing presets."""
-    preset_names = sorted(_MODEL_PRESET_CACHE)
-    choices = [_CLEAR_CHOICE] + preset_names
-    default_choice = str(current_value) if current_value else _CLEAR_CHOICE
+    preset_names = sorted(_MODEL_PRESET_CACHE) or ["default"]
+    choices = preset_names
+    default_choice = str(current_value) if current_value else "default"
    new_value = _select_with_back(field_display, choices, default=default_choice)
    if new_value is _BACK_PRESSED:
        return
-    if new_value == _CLEAR_CHOICE:
-        setattr(working_model, field_name, None)
-    elif new_value is not None:
+    if new_value is not None:
        setattr(working_model, field_name, new_value)


@@ -792,8 +790,6 @@ def _handle_fallback_models_field(
    working_model: BaseModel, field_name: str, field_display: str, current_value: Any
 ) -> None:
    """Handle the 'fallback_models' field with preset-aware list management."""
-    from nanobot.config.schema import InlineFallbackConfig
-
    items: list[Any] = list(current_value) if isinstance(current_value, list) else []
    preset_names = sorted(_MODEL_PRESET_CACHE)

@@ -802,10 +798,7 @@ def _handle_fallback_models_field(
        console.print(f"[bold]{field_display}[/bold]")
        if items:
            for idx, item in enumerate(items, 1):
-                if isinstance(item, InlineFallbackConfig):
-                    console.print(f"  {idx}. {item.model} - {item.provider} inline")
-                else:
-                    console.print(f"  {idx}. {item}")
+                console.print(f"  {idx}. {item}")
        else:
            console.print("  [dim]empty[/dim]")
        console.print()
@@ -14,7 +14,7 @@ from typing import Literal
 from nanobot import __version__
 from nanobot.agent.goal_permission import goal_mutation_permission
 from nanobot.bus.events import OutboundMessage
-from nanobot.command.router import CommandContext, CommandRouter
+from nanobot.command.router import CommandContext, CommandRouter, normalize_command_text
 from nanobot.utils.helpers import build_status_content
 from nanobot.utils.restart import set_restart_notice_to_env
 from nanobot.utils.workspace_prompts import initialize_workspace_prompt
@@ -180,6 +180,21 @@ def builtin_command_palette() -> list[dict[str, str | bool]]:
    return [spec.as_dict() for spec in BUILTIN_COMMAND_SPECS]


+def builtin_command_starts_agent_turn(text: str) -> bool:
+    """Return whether WebUI ingress should expect a normal agent lifecycle."""
+    normalized = normalize_command_text(text)
+    command, separator, args = normalized.partition(" ")
+    spec = next(
+        (item for item in BUILTIN_COMMAND_SPECS if item.command == command.lower()),
+        None,
+    )
+    if spec is None or (separator and not spec.accepts_args):
+        return True
+    if spec.lifecycle == "agent_turn":
+        return True
+    return spec.lifecycle == "agent_turn_with_args" and bool(args.strip())
+
+
 async def cmd_stop(ctx: CommandContext) -> OutboundMessage:
    """Cancel all active tasks and subagents for the session."""
    loop = ctx.loop
@@ -427,12 +442,15 @@ async def cmd_dream(ctx: CommandContext) -> OutboundMessage:
                return
            prompt, last_cursor = result
            key = dream_session_key()
+            resolve_dream_runtime = getattr(loop, "dream_runtime", None)
+            dream_runtime = resolve_dream_runtime() if callable(resolve_dream_runtime) else None
            resp = await loop.process_direct(
                prompt,
                session_key=key,
                ephemeral=True,
                tools=store.build_dream_tools(),
                on_progress=progress,
+                runtime=dream_runtime,
            )
            elapsed = time.monotonic() - t0
            # The real file delta grounds the audit record; clean completion
@@ -1,5 +1,6 @@
 """Configuration module for nanobot."""

+from nanobot.config.errors import ConfigIssue, ConfigLoadError
 from nanobot.config.loader import get_config_path, load_config
 from nanobot.config.paths import (
    get_cli_history_path,
@@ -17,6 +18,8 @@ from nanobot.config.schema import Config

 __all__ = [
    "Config",
+    "ConfigIssue",
+    "ConfigLoadError",
    "load_config",
    "get_config_path",
    "get_data_dir",
@@ -0,0 +1,112 @@
+"""User-safe configuration diagnostics."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from pydantic import ValidationError
+
+ConfigErrorKind = Literal[
+    "invalid_json",
+    "invalid_root",
+    "invalid_schema",
+    "missing_env",
+    "io_error",
+]
+ConfigPathPart = str | int
+_SAFE_LOCATION_PART = re.compile(r"[A-Za-z_][A-Za-z0-9_-]{0,63}")
+
+
+def _display_location_part(part: ConfigPathPart) -> str:
+    if isinstance(part, int):
+        return str(part)
+    return part if _SAFE_LOCATION_PART.fullmatch(part) else "<redacted>"
+
+
+@dataclass(frozen=True)
+class ConfigIssue:
+    """One actionable configuration problem."""
+
+    path: tuple[ConfigPathPart, ...]
+    message: str
+
+    @property
+    def location(self) -> str:
+        # Pydantic locations can contain user-controlled mapping keys. Only
+        # render conventional config identifiers so credential-bearing URLs
+        # and other free-form values cannot leak through a redacted error.
+        if not self.path:
+            return "<root>"
+        return ".".join(_display_location_part(part) for part in self.path)
+
+
+class ConfigLoadError(ValueError):
+    """A structured, user-safe configuration loading failure."""
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        kind: ConfigErrorKind,
+        summary: str,
+        issues: tuple[ConfigIssue, ...] = (),
+    ) -> None:
+        self.path = path
+        self.kind = kind
+        self.summary = summary
+        self.issues = issues
+        super().__init__(summary)
+
+    def __str__(self) -> str:
+        lines = [f"Invalid configuration: {self.path}", "", self.summary]
+        for issue in self.issues[:10]:
+            lines.extend(("", f"  {issue.location}", f"    {issue.message}"))
+        remaining = len(self.issues) - 10
+        if remaining > 0:
+            lines.extend(("", f"  … and {remaining} more issue(s)"))
+        return "\n".join(lines)
+
+
+def validation_issues(
+    error: ValidationError,
+) -> tuple[ConfigIssue, ...]:
+    """Convert Pydantic details to actionable messages without exposing input values."""
+    issues: list[ConfigIssue] = []
+    for detail in error.errors(
+        include_url=False,
+        include_context=False,
+        include_input=False,
+    ):
+        location = tuple(detail.get("loc", ()))
+        code = str(detail.get("type") or "")
+        message = _friendly_validation_message(
+            str(detail.get("msg") or "Invalid value"),
+            code,
+        )
+        issues.append(ConfigIssue(path=location, message=message))
+    return tuple(issues)
+
+
+def _friendly_validation_message(message: str, code: str) -> str:
+    if code == "extra_forbidden":
+        return "Unknown setting."
+    if code == "missing":
+        return "This setting is required."
+    if code in {"assertion_error", "value_error"}:
+        # Custom validators control these messages and may interpolate the
+        # rejected value. Keep the field location, but never render that text.
+        return "Value does not satisfy this setting's requirements."
+    if message.startswith("Value error, "):
+        message = message.removeprefix("Value error, ")
+    elif message.startswith("Input should be "):
+        message = "Must be " + message.removeprefix("Input should be ")
+    elif message.startswith("Input should have "):
+        message = "Must have " + message.removeprefix("Input should have ")
+    if message:
+        message = message[:1].upper() + message[1:]
+    if message and message[-1] not in ".!?":
+        message += "."
+    return message or "Invalid value."
@@ -6,16 +6,18 @@ import re
 from pathlib import Path
 from typing import Any

-import pydantic
 from loguru import logger
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
+from pydantic_settings import SettingsError

+from nanobot.config.errors import ConfigIssue, ConfigLoadError, validation_issues
 from nanobot.config.schema import Config, _resolve_tool_config_refs
 from nanobot.utils.helpers import _write_text_atomic

 # Global variable to store current config path (for multi-instance support)
 _current_config_path: Path | None = None
 _schema_refs_ready = False
+_warned_legacy_model_env = False


 def set_config_path(path: Path) -> None:
@@ -48,16 +50,99 @@ def load_config(config_path: Path | None = None) -> Config:

    path = config_path or get_config_path()

-    config = Config()
-    if path.exists():
+    if not path.exists():
        try:
-            with open(path, encoding="utf-8") as f:
-                data = json.load(f)
-            data = _migrate_config(data)
-            config = Config.model_validate(data)
-        except (json.JSONDecodeError, ValueError, pydantic.ValidationError) as e:
-            raise ValueError(f"Failed to load config from {path}: {e}") from e
+            config = Config()
+        except SettingsError as exc:
+            raise ConfigLoadError(
+                path,
+                kind="invalid_schema",
+                summary=(
+                    "Environment-based configuration could not be parsed. "
+                    "Check that complex NANOBOT_* values use valid JSON."
+                ),
+            ) from exc
+        except ValidationError as exc:
+            raise ConfigLoadError(
+                path,
+                kind="invalid_schema",
+                summary="Environment-based configuration is invalid.",
+                issues=validation_issues(exc),
+            ) from exc
+        _warn_unsupported_legacy_model_env(path)
+        _apply_ssrf_whitelist(config)
+        return config

+    try:
+        with path.open(encoding="utf-8") as handle:
+            data = json.load(handle)
+    except json.JSONDecodeError as exc:
+        raise ConfigLoadError(
+            path,
+            kind="invalid_json",
+            summary=(
+                f"JSON syntax error at line {exc.lineno}, column {exc.colno}: "
+                f"{_sentence(exc.msg)}"
+            ),
+        ) from exc
+    except UnicodeDecodeError as exc:
+        raise ConfigLoadError(
+            path,
+            kind="io_error",
+            summary="The file is not valid UTF-8.",
+        ) from exc
+    except OSError as exc:
+        detail = exc.strerror or type(exc).__name__
+        raise ConfigLoadError(
+            path,
+            kind="io_error",
+            summary=f"Unable to read the file: {_sentence(detail)}",
+        ) from exc
+
+    if not isinstance(data, dict):
+        root_type = type(data).__name__
+        raise ConfigLoadError(
+            path,
+            kind="invalid_root",
+            summary="The top level of config.json must be a JSON object.",
+            issues=(
+                ConfigIssue(
+                    path=(),
+                    message=f"Expected an object, but found {root_type}.",
+                ),
+            ),
+        )
+
+    legacy_model_migration = _legacy_model_migration_kind(data)
+    data, migrated = _migrate_config(data)
+    try:
+        config = Config.model_validate(data)
+    except ValidationError as exc:
+        issues = validation_issues(exc)
+        raise ConfigLoadError(
+            path,
+            kind="invalid_schema",
+            summary=f"Found {len(issues)} invalid setting(s).",
+            issues=issues,
+        ) from exc
+
+    if migrated:
+        _write_text_atomic(path, json.dumps(data, indent=2, ensure_ascii=False))
+        if legacy_model_migration:
+            detail = (
+                "Existing modelPresets.default took precedence; conflicting "
+                "legacy agents.defaults fields were removed."
+                if legacy_model_migration == "conflict"
+                else "Legacy settings were converted to named model presets."
+            )
+            logger.warning(
+                "Migrated legacy model configuration in {}. {} "
+                "Review the rewritten file before downgrading nanobot.",
+                path,
+                detail,
+            )
+
+    _warn_unsupported_legacy_model_env(path)
    _apply_ssrf_whitelist(config)
    return config

@@ -117,13 +202,25 @@ def merge_missing_defaults(existing: Any, defaults: Any) -> Any:
 _ENV_REF_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")


-def resolve_config_env_vars(config: Config) -> Config:
+def resolve_config_env_vars(
+    config: Config,
+    *,
+    config_path: Path | None = None,
+) -> Config:
    """Return *config* with ``${VAR}`` env-var references resolved.

    Walks in place so fields declared with ``exclude=True`` survive;
    returns the same instance when no references are present.
-    Raises ``ValueError`` if a referenced variable is not set.
+    Raises ``ConfigLoadError`` if a referenced variable is not set.
    """
+    missing = tuple(_missing_env_issues(config))
+    if missing:
+        raise ConfigLoadError(
+            config_path or get_config_path(),
+            kind="missing_env",
+            summary=f"Found {len(missing)} missing environment variable reference(s).",
+            issues=missing,
+        )
    return _resolve_in_place(config)


@@ -177,6 +274,42 @@ def _resolve_in_place(obj: Any) -> Any:
    return obj


+def _missing_env_issues(
+    obj: Any,
+    path: tuple[str | int, ...] = (),
+) -> list[ConfigIssue]:
+    if isinstance(obj, str):
+        return [
+            ConfigIssue(
+                path=path,
+                message=f"Environment variable '{name}' is not set.",
+            )
+            for name in dict.fromkeys(_ENV_REF_PATTERN.findall(obj))
+            if name not in os.environ
+        ]
+    if isinstance(obj, BaseModel):
+        issues: list[ConfigIssue] = []
+        for name, field in type(obj).model_fields.items():
+            alias = field.serialization_alias or field.alias or name
+            part = alias if isinstance(alias, str) else name
+            issues.extend(_missing_env_issues(getattr(obj, name), (*path, part)))
+        for name, value in (obj.__pydantic_extra__ or {}).items():
+            issues.extend(_missing_env_issues(value, (*path, name)))
+        return issues
+    if isinstance(obj, dict):
+        issues = []
+        for name, value in obj.items():
+            part = name if isinstance(name, (str, int)) else str(name)
+            issues.extend(_missing_env_issues(value, (*path, part)))
+        return issues
+    if isinstance(obj, list):
+        issues = []
+        for index, value in enumerate(obj):
+            issues.extend(_missing_env_issues(value, (*path, index)))
+        return issues
+    return []
+
+
 def _resolve_env_vars(obj: object) -> object:
    """Recursively resolve ``${VAR}`` patterns in plain strings/dicts/lists."""
    if isinstance(obj, str):
@@ -198,43 +331,290 @@ def _env_replace(match: re.Match[str]) -> str:
    return value


-def _migrate_config(data: dict) -> dict:
-    """Migrate old config formats to current."""
-    agents = data.get("agents", {})
-    defaults = agents.get("defaults", {}) if isinstance(agents, dict) else {}
-    if isinstance(defaults, dict):
-        had_legacy_max_messages = (
-            "maxMessages" in defaults or "max_messages" in defaults
-        )
-        defaults.pop("maxMessages", None)
-        defaults.pop("max_messages", None)
-        if had_legacy_max_messages:
-            # TODO(v0.3.1): Remove this legacy cleanup branch. v0.3.0 is the
-            # final release that warns before the schema silently ignores the field.
-            logger.warning(
-                "agents.defaults.maxMessages/max_messages is legacy and ignored; "
-                "replay max messages is now an internal safety cap. Remove it from "
-                "config. This compatibility warning will be removed in the next version."
-            )
+_LEGACY_DEFAULT_PRESET = {
+    "label": "Default",
+    "model": "anthropic/claude-opus-4-5",
+    "provider": "auto",
+    "maxTokens": 8192,
+    "contextWindowTokens": 200_000,
+    "temperature": 0.1,
+    "reasoningEffort": None,
+}
+_LEGACY_MODEL_FIELD_ALIASES = {
+    "model": ("model",),
+    "provider": ("provider",),
+    "maxTokens": ("maxTokens", "max_tokens"),
+    "contextWindowTokens": ("contextWindowTokens", "context_window_tokens"),
+    "temperature": ("temperature",),
+    "reasoningEffort": ("reasoningEffort", "reasoning_effort"),
+}

+
+def _legacy_model_migration_kind(data: dict[str, Any]) -> str | None:
+    """Classify a pending model migration without exposing configured values."""
+    if not _needs_legacy_model_migration(data):
+        return None
+
+    agents = data.get("agents")
+    defaults = agents.get("defaults") if isinstance(agents, dict) else None
+    presets = data.get("modelPresets", data.get("model_presets"))
+    has_legacy_fields = isinstance(defaults, dict) and any(
+        alias in defaults
+        for aliases in _LEGACY_MODEL_FIELD_ALIASES.values()
+        for alias in aliases
+    )
+    if has_legacy_fields and isinstance(presets, dict) and "default" in presets:
+        return "conflict"
+    return "migrated"
+
+
+def _has_unsupported_legacy_model_env() -> bool:
+    for env_name in ("NANOBOT_AGENTS", "NANOBOT_AGENTS__DEFAULTS"):
+        raw = os.environ.get(env_name)
+        if not raw:
+            continue
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        data = (
+            {"agents": parsed}
+            if env_name == "NANOBOT_AGENTS"
+            else {"agents": {"defaults": parsed}}
+        )
+        if isinstance(parsed, dict) and _needs_legacy_model_migration(data):
+            return True
+
+    legacy_suffixes = {
+        alias.upper()
+        for aliases in _LEGACY_MODEL_FIELD_ALIASES.values()
+        for alias in aliases
+    }
+    prefix = "NANOBOT_AGENTS__DEFAULTS__"
+    for env_name in os.environ:
+        upper_name = env_name.upper()
+        if not upper_name.startswith(prefix):
+            continue
+        suffix = upper_name[len(prefix):]
+        if suffix in legacy_suffixes:
+            return True
+    return False
+
+
+def _warn_unsupported_legacy_model_env(config_path: Path) -> None:
+    global _warned_legacy_model_env
+    if _warned_legacy_model_env or not _has_unsupported_legacy_model_env():
+        return
+    logger.warning(
+        "Ignoring unsupported legacy model settings from NANOBOT_AGENTS. "
+        "Move them to modelPresets in {}.",
+        config_path,
+    )
+    _warned_legacy_model_env = True
+
+
+def _pop_alias(mapping: dict[str, Any], aliases: tuple[str, ...]) -> tuple[bool, Any]:
+    found = False
+    value: Any = None
+    for alias in aliases:
+        if alias in mapping:
+            if not found:
+                value = mapping[alias]
+                found = True
+            mapping.pop(alias, None)
+    return found, value
+
+
+def _preset_value(preset: dict[str, Any], camel: str, snake: str) -> Any:
+    return preset.get(camel, preset.get(snake))
+
+
+def _first_not_none(*values: Any) -> Any:
+    return next((value for value in values if value is not None), None)
+
+
+def _unique_legacy_fallback_name(presets: dict[str, Any], model: Any) -> str:
+    tail = str(model or "fallback").rsplit("/", 1)[-1].strip().lower()
+    base = re.sub(r"[^a-z0-9]+", "-", tail).strip("-") or "fallback"
+    name = base
+    suffix = 2
+    while name in presets:
+        name = f"{base}-{suffix}"
+        suffix += 1
+    return name
+
+
+def _needs_legacy_model_migration(data: dict[str, Any]) -> bool:
+    agents = data.get("agents")
+    defaults = agents.get("defaults") if isinstance(agents, dict) else None
+    if isinstance(defaults, dict):
+        if any(
+            alias in defaults
+            for aliases in _LEGACY_MODEL_FIELD_ALIASES.values()
+            for alias in aliases
+        ):
+            return True
+        if "model_preset" in defaults:
+            return True
+        active = defaults.get("modelPreset")
+        if "modelPreset" in defaults and (
+            not isinstance(active, str) or not active.strip()
+        ):
+            return True
+        fallbacks = defaults.get(
+            "fallbackModels",
+            defaults.get("fallback_models"),
+        )
+        if isinstance(fallbacks, list) and any(
+            isinstance(fallback, dict) for fallback in fallbacks
+        ):
+            return True
+
+    presets = data.get("modelPresets", data.get("model_presets"))
+    return isinstance(presets, dict) and "default" not in presets
+
+
+def _migrate_legacy_model_config(data: dict[str, Any]) -> bool:
+    """Move concrete model settings into named presets before schema validation."""
+    if not _needs_legacy_model_migration(data):
+        return False
+
+    changed = False
+    agents = data.setdefault("agents", {})
+    if not isinstance(agents, dict):
+        return False
+    defaults = agents.setdefault("defaults", {})
+    if not isinstance(defaults, dict):
+        return False
+
+    presets_key = "modelPresets" if "modelPresets" in data else "model_presets"
+    if presets_key not in data:
+        presets_key = "modelPresets"
+        data[presets_key] = {}
+        changed = True
+    presets = data[presets_key]
+    if not isinstance(presets, dict):
+        return changed
+
+    migrated_default = dict(_LEGACY_DEFAULT_PRESET)
+    legacy_values_found = False
+    for destination, aliases in _LEGACY_MODEL_FIELD_ALIASES.items():
+        found, value = _pop_alias(defaults, aliases)
+        if found:
+            migrated_default[destination] = value
+            legacy_values_found = True
+            changed = True
+
+    if "default" not in presets:
+        presets["default"] = migrated_default
+        changed = True
+
+    had_canonical_active = "modelPreset" in defaults
+    active_found, active = _pop_alias(defaults, ("modelPreset", "model_preset"))
+    normalized_active = active.strip() if isinstance(active, str) else ""
+    normalized_active = normalized_active or "default"
+    if not active_found or active != normalized_active or not had_canonical_active:
+        changed = True
+    defaults["modelPreset"] = normalized_active
+
+    fallback_key = (
+        "fallbackModels"
+        if "fallbackModels" in defaults
+        else "fallback_models"
+        if "fallback_models" in defaults
+        else None
+    )
+    if fallback_key is not None and isinstance(defaults[fallback_key], list):
+        primary = presets.get(normalized_active)
+        if not isinstance(primary, dict):
+            primary = presets["default"]
+        migrated_fallbacks: list[Any] = []
+        for fallback in defaults[fallback_key]:
+            if isinstance(fallback, str):
+                migrated_fallbacks.append(fallback)
+                continue
+            if not isinstance(fallback, dict):
+                migrated_fallbacks.append(fallback)
+                continue
+            name = _unique_legacy_fallback_name(presets, fallback.get("model"))
+            presets[name] = {
+                "label": str(fallback.get("model") or name),
+                "model": fallback.get("model"),
+                "provider": fallback.get("provider"),
+                "maxTokens": _first_not_none(
+                    _preset_value(fallback, "maxTokens", "max_tokens"),
+                    _preset_value(primary, "maxTokens", "max_tokens"),
+                    _LEGACY_DEFAULT_PRESET["maxTokens"],
+                ),
+                "contextWindowTokens": _first_not_none(
+                    _preset_value(fallback, "contextWindowTokens", "context_window_tokens"),
+                    _preset_value(primary, "contextWindowTokens", "context_window_tokens"),
+                    _LEGACY_DEFAULT_PRESET["contextWindowTokens"],
+                ),
+                "temperature": (
+                    fallback["temperature"]
+                    if fallback.get("temperature") is not None
+                    else primary.get("temperature", _LEGACY_DEFAULT_PRESET["temperature"])
+                ),
+                "reasoningEffort": _preset_value(
+                    fallback,
+                    "reasoningEffort",
+                    "reasoning_effort",
+                ),
+            }
+            migrated_fallbacks.append(name)
+            changed = True
+        if fallback_key != "fallbackModels":
+            defaults.pop(fallback_key, None)
+            changed = True
+        defaults["fallbackModels"] = migrated_fallbacks
+
+    return changed or legacy_values_found
+
+
+def _migrate_config(data: dict) -> tuple[dict, bool]:
+    """Migrate old config formats to current."""
+    changed = _migrate_legacy_model_config(data)
    # Move tools.exec.restrictToWorkspace → tools.restrictToWorkspace
    tools = data.get("tools", {})
+    if not isinstance(tools, dict):
+        return data, changed
    exec_cfg = tools.get("exec", {})
-    if "restrictToWorkspace" in exec_cfg and "restrictToWorkspace" not in tools:
+    if (
+        isinstance(exec_cfg, dict)
+        and "restrictToWorkspace" in exec_cfg
+        and "restrictToWorkspace" not in tools
+    ):
        tools["restrictToWorkspace"] = exec_cfg.pop("restrictToWorkspace")
+        changed = True

    # Move tools.myEnabled / tools.mySet → tools.my.{enable, allowSet}.
    # The old flat keys shipped in the initial MyTool landing; wrapping them in a
    # sub-config keeps `web` / `exec` / `my` symmetric and gives room to grow.
    if "myEnabled" in tools or "mySet" in tools:
-        my_cfg = tools.setdefault("my", {})
+        my_cfg = tools.get("my")
+        if my_cfg is None:
+            my_cfg = {}
+            tools["my"] = my_cfg
+            changed = True
+        if not isinstance(my_cfg, dict):
+            return data, changed
        if "myEnabled" in tools and "enable" not in my_cfg:
            my_cfg["enable"] = tools.pop("myEnabled")
+            changed = True
        else:
-            tools.pop("myEnabled", None)
+            changed = tools.pop("myEnabled", None) is not None or changed
        if "mySet" in tools and "allowSet" not in my_cfg:
            my_cfg["allowSet"] = tools.pop("mySet")
+            changed = True
        else:
-            tools.pop("mySet", None)
+            changed = tools.pop("mySet", None) is not None or changed

-    return data
+    return data, changed
+
+
+def _sentence(message: str) -> str:
+    message = message.strip()
+    if message and message[-1] not in ".!?":
+        message += "."
+    return message
@@ -32,7 +32,7 @@ class ChannelsConfig(Base):
    send_progress: bool = True  # stream agent's text progress to the channel
    send_tool_hints: bool = True  # stream tool-call hints (e.g. read_file("…"))
    show_reasoning: bool = True  # surface model reasoning when channel implements it
-    extract_document_text: bool = True  # extract text from document attachments before sending to the model
+    extract_document_text: bool = True  # Deprecated and ignored; documents are read on demand
    send_max_retries: int = Field(default=3, ge=0, le=10)  # Max delivery attempts (initial send included)
    transcription_provider: str = "groq"  # Deprecated: use top-level transcription.provider
    transcription_language: str | None = Field(default=None, pattern=r"^[a-z]{2,3}$")  # Deprecated: use top-level transcription.language
@@ -63,10 +63,7 @@ class DreamConfig(Base):
    model_override: str | None = Field(
        default=None,
        validation_alias=AliasChoices("modelOverride", "model", "model_override"),
-    )  # Override model for Dream sessions (pending implementation)
-    max_batch_size: int = Field(default=20, ge=1)  # Deprecated: no longer used
-    max_iterations: int = Field(default=15, ge=1)  # Deprecated: no longer used
-    annotate_line_ages: bool = True  # Deprecated: no longer used
+    )  # Model preset name for Dream sessions

    def build_schedule(self, timezone: str) -> CronSchedule:
        """Build the runtime schedule, preferring the legacy cron override if present."""
@@ -82,20 +79,6 @@ class DreamConfig(Base):
        return f"every {hours}h"


-class InlineFallbackConfig(Base):
-    """One inline fallback model configuration."""
-
-    model: str
-    provider: str
-    max_tokens: int | None = None
-    context_window_tokens: int | None = None
-    temperature: float | None = None
-    reasoning_effort: str | None = None
-
-
-FallbackCandidate = str | InlineFallbackConfig
-
-
 class ModelPresetConfig(Base):
    """A named set of model + generation parameters for quick switching."""

@@ -106,6 +89,7 @@ class ModelPresetConfig(Base):
    context_window_tokens: int = 200_000
    temperature: float = 0.1
    reasoning_effort: str | None = None
+    supports_image_input: bool | None = None

    def to_generation_settings(self) -> Any:
        from nanobot.providers.base import GenerationSettings
@@ -120,16 +104,9 @@ class AgentDefaults(Base):
    """Default agent configuration."""

    workspace: str = "~/.nanobot/workspace"
-    model_preset: str | None = None  # Active preset name — takes precedence over fields below
-    model: str = "anthropic/claude-opus-4-5"
-    provider: str = (
-        "auto"  # Provider name (e.g. "anthropic", "openrouter") or "auto" for auto-detection
-    )
-    max_tokens: int = 8192
-    context_window_tokens: int = 200_000
+    model_preset: str = "default"
    context_block_limit: int | None = None
-    temperature: float = 0.1
-    fallback_models: list[FallbackCandidate] = Field(default_factory=list)
+    fallback_models: list[str] = Field(default_factory=list)
    max_tool_iterations: int = 200
    max_concurrent_subagents: int = Field(default=1, ge=1)
    fail_on_tool_error: bool = True
@@ -142,7 +119,6 @@ class AgentDefaults(Base):
        validation_alias=AliasChoices("toolHintMaxLength"),
        serialization_alias="toolHintMaxLength",
    )  # Max characters for tool hint display (e.g. "$ cd …/project && npm test")
-    reasoning_effort: str | None = None  # low / medium / high / adaptive / none — LLM thinking effort; None preserves the provider default
    timezone: str = "UTC"  # IANA timezone, e.g. "Asia/Shanghai", "America/New_York"
    bot_name: str = "nanobot"  # Display name shown in CLI prompts (e.g. "{name} is thinking...")
    bot_icon: str = "🐈"  # Short icon (emoji or text) shown next to the bot name in CLI; "" to omit
@@ -422,7 +398,12 @@ class Config(BaseSettings):
    gateway: GatewayConfig = Field(default_factory=GatewayConfig)
    tools: ToolsConfig = Field(default_factory=ToolsConfig)
    model_presets: dict[str, ModelPresetConfig] = Field(
-        default_factory=dict,
+        default_factory=lambda: {
+            "default": ModelPresetConfig(
+                label="Default",
+                model="anthropic/claude-opus-4-5",
+            )
+        },
        validation_alias=AliasChoices("modelPresets", "model_presets"),
        serialization_alias="modelPresets",
    )
@@ -434,30 +415,26 @@ class Config(BaseSettings):

    @model_validator(mode="after")
    def _validate_model_preset(self) -> "Config":
-        if "default" in self.model_presets:
-            raise ValueError("model_preset name 'default' is reserved for agents.defaults")
+        if "default" not in self.model_presets:
+            raise ValueError("model_presets must define a 'default' preset")
        name = self.agents.defaults.model_preset
-        if name and name != "default" and name not in self.model_presets:
+        if name not in self.model_presets:
            raise ValueError(f"model_preset {name!r} not found in model_presets")
+        dream_name = self.agents.defaults.dream.model_override
+        if dream_name and dream_name not in self.model_presets:
+            raise ValueError(f"Dream model preset {dream_name!r} not found in model_presets")
        for fallback in self.agents.defaults.fallback_models:
-            if isinstance(fallback, str) and fallback not in self.model_presets:
+            if fallback not in self.model_presets:
                raise ValueError(f"fallback_models entry {fallback!r} not found in model_presets")
        return self

    def resolve_default_preset(self) -> ModelPresetConfig:
-        """Return the implicit `default` preset from agents.defaults fields."""
-        d = self.agents.defaults
-        return ModelPresetConfig(
-            model=d.model, provider=d.provider, max_tokens=d.max_tokens,
-            context_window_tokens=d.context_window_tokens,
-            temperature=d.temperature, reasoning_effort=d.reasoning_effort,
-        )
+        """Return the concrete ``default`` model preset."""
+        return self.model_presets["default"]

    def resolve_preset(self, name: str | None = None) -> ModelPresetConfig:
-        """Return effective model params from a named preset or the implicit default."""
-        name = self.agents.defaults.model_preset if name is None else name
-        if not name or name == "default":
-            return self.resolve_default_preset()
+        """Return effective model params from a named preset."""
+        name = self.agents.defaults.model_preset if name is None else (name or "default")
        if name not in self.model_presets:
            raise KeyError(f"model_preset {name!r} not found in model_presets")
        return self.model_presets[name]
@@ -3,7 +3,7 @@
 from __future__ import annotations

 import asyncio
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
 from pathlib import Path
 from typing import Any

@@ -13,10 +13,7 @@ from nanobot.agent.loop import AgentLoop
 from nanobot.config.schema import Config
 from nanobot.providers.image_generation import image_gen_provider_configs
 from nanobot.sdk.clients import MemoryClient, RuntimeClient, SessionClient
-from nanobot.sdk.runtime import (
-    build_process_direct_kwargs,
-    ensure_single_model_selector,
-)
+from nanobot.sdk.runtime import build_process_direct_kwargs
 from nanobot.sdk.streaming import RunStream, SDKStreamEmitter, SDKStreamingHook
 from nanobot.sdk.types import (
    STREAM_EVENT_REASONING_COMPLETED,
@@ -84,7 +81,6 @@ class Nanobot:
        config_path: str | Path | None = None,
        *,
        workspace: str | Path | None = None,
-        model: str | None = None,
        model_preset: str | None = None,
    ) -> Nanobot:
        """Create a Nanobot instance from a config file.
@@ -93,28 +89,25 @@ class Nanobot:
            config_path: Path to ``config.json``.  Defaults to
                ``~/.nanobot/config.json``.
            workspace: Override the workspace directory from config.
-            model: Override the instance default model.
            model_preset: Override the instance default model preset.
        """
        from nanobot.config.loader import load_config, resolve_config_env_vars

-        ensure_single_model_selector(model=model, model_preset=model_preset)
        resolved: Path | None = None
        if config_path is not None:
            resolved = Path(config_path).expanduser().resolve()
            if not resolved.exists():
                raise FileNotFoundError(f"Config not found: {resolved}")

-        config: Config = resolve_config_env_vars(load_config(resolved))
+        config: Config = resolve_config_env_vars(
+            load_config(resolved),
+            config_path=resolved,
+        )
        if workspace is not None:
            config.agents.defaults.workspace = str(
                Path(workspace).expanduser().resolve()
            )
-        if model is not None:
-            config.agents.defaults.model_preset = None
-            config.agents.defaults.model = model
-            config.agents.defaults.provider = "auto"
-        elif model_preset is not None:
+        if model_preset is not None:
            config.agents.defaults.model_preset = model_preset

        loop = AgentLoop.from_config(
@@ -134,8 +127,8 @@ class Nanobot:
        sender_id: str = "user",
        media: list[str] | None = None,
        ephemeral: bool = False,
+        attributes: Mapping[str, Any] | None = None,
        hooks: list[AgentHook] | None = None,
-        model: str | None = None,
        model_preset: str | None = None,
    ) -> RunResult:
        """Run the agent once and return the result.
@@ -149,14 +142,16 @@ class Nanobot:
            sender_id: Logical sender identifier for runtime context.
            media: Optional local media paths attached to the message.
            ephemeral: If true, do not persist the turn or compact session history.
+            attributes: Optional caller-owned request data exposed to context
+                providers and turn-hook factories. Attributes are kept separate
+                from nanobot's trusted internal message metadata.
            hooks: Optional lifecycle hooks for this run.
-            model: Override the model for this run only.
            model_preset: Override the model preset for this run only.
        """
        capture = SDKCaptureHook()
        per_run_hooks = [capture, *(hooks or [])]
        runtime = self._loop.runtime_resolver.resolve_override(
-            model=model,
+            model=None,
            model_preset=model_preset,
            config=self._config,
        )
@@ -167,6 +162,7 @@ class Nanobot:
            sender_id=sender_id,
            media=media,
            ephemeral=ephemeral,
+            attributes=attributes,
        )
        if runtime is not None:
            kwargs["runtime"] = runtime
@@ -188,13 +184,13 @@ class Nanobot:
        sender_id: str = "user",
        media: list[str] | None = None,
        ephemeral: bool = False,
+        attributes: Mapping[str, Any] | None = None,
        hooks: list[AgentHook] | None = None,
-        model: str | None = None,
        model_preset: str | None = None,
    ) -> RunStream:
        """Start a streamed run and return a handle for events and final result."""
        override_runtime = self._loop.runtime_resolver.resolve_override(
-            model=model,
+            model=None,
            model_preset=model_preset,
            config=self._config,
        )
@@ -242,6 +238,7 @@ class Nanobot:
                sender_id=sender_id,
                media=media,
                ephemeral=ephemeral,
+                attributes=attributes,
                on_stream=_on_stream,
                on_stream_end=_on_stream_end,
            )
@@ -289,8 +286,8 @@ class Nanobot:
        sender_id: str = "user",
        media: list[str] | None = None,
        ephemeral: bool = False,
+        attributes: Mapping[str, Any] | None = None,
        hooks: list[AgentHook] | None = None,
-        model: str | None = None,
        model_preset: str | None = None,
    ) -> AsyncIterator[StreamEvent]:
        """Stream events for one agent turn."""
@@ -302,8 +299,8 @@ class Nanobot:
            sender_id=sender_id,
            media=media,
            ephemeral=ephemeral,
+            attributes=attributes,
            hooks=hooks,
-            model=model,
            model_preset=model_preset,
        )
        try:
@@ -218,6 +218,16 @@ class LLMProvider(ABC):
        "速率限制",
        "访问量过大",
    )
+    _IMAGE_UNSUPPORTED_MARKERS = (
+        "does not support image",
+        "doesn't support image",
+        "images are not supported",
+        "image input is not supported",
+        "image input not supported",
+        "image_url is not supported",
+        "unsupported image input",
+        "vision is not supported",
+    )
    _RETRYABLE_STATUS_CODES = frozenset({408, 409, 429})
    _TRANSIENT_ERROR_KINDS = frozenset({"timeout", "connection"})
    _NON_RETRYABLE_429_ERROR_TOKENS = frozenset({
@@ -272,6 +282,7 @@ class LLMProvider(ABC):
        self.api_key = api_key
        self.api_base = api_base
        self.generation: GenerationSettings = GenerationSettings()
+        self.supports_image_input: bool | None = None

    @staticmethod
    def _sanitize_empty_content(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
@@ -602,6 +613,51 @@ class LLMProvider(ABC):
                result.append(msg)
        return result if found else None

+    def _messages_for_image_capability(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        supports_image_input: bool | None | object = _SENTINEL,
+    ) -> list[dict[str, Any]]:
+        """Apply an explicit text-only preset before making a provider request."""
+        capability = (
+            self.supports_image_input
+            if supports_image_input is self._SENTINEL
+            else supports_image_input
+        )
+        if capability is not False:
+            return messages
+        return self._strip_image_content(messages) or messages
+
+    def _outer_image_capability(
+        self,
+        supports_image_input: bool | None,
+    ) -> bool | None:
+        """Return the image policy applied by this provider's retry wrapper."""
+        return supports_image_input
+
+    def _image_policy_request_kwargs(
+        self,
+        supports_image_input: bool | None,
+    ) -> dict[str, Any]:
+        """Return provider-internal kwargs needed for candidate image policy."""
+        return {}
+
+    @classmethod
+    def _is_image_unsupported_response(cls, response: LLMResponse) -> bool:
+        if response.finish_reason != "error":
+            return False
+        text = " ".join(
+            str(value or "")
+            for value in (
+                response.content,
+                response.error_kind,
+                response.error_type,
+                response.error_code,
+            )
+        ).lower()
+        return any(marker in text for marker in cls._IMAGE_UNSUPPORTED_MARKERS)
+
    @staticmethod
    def _strip_image_content_inplace(messages: list[dict[str, Any]]) -> bool:
        """Replace image_url blocks with text placeholder *in-place*.
@@ -692,6 +748,7 @@ class LLMProvider(ABC):
        on_stream_recover: Callable[[], Awaitable[None]] | None = None,
        retry_mode: str = "standard",
        on_retry_wait: Callable[[str], Awaitable[None]] | None = None,
+        supports_image_input: bool | None | object = _SENTINEL,
    ) -> LLMResponse:
        """Call chat_stream() with retry on transient provider failures."""
        if max_tokens is self._SENTINEL or max_tokens is None:
@@ -700,6 +757,14 @@ class LLMProvider(ABC):
            temperature = self.generation.temperature
        if reasoning_effort is self._SENTINEL:
            reasoning_effort = self.generation.reasoning_effort
+        candidate_image_capability = (
+            self.supports_image_input
+            if supports_image_input is self._SENTINEL
+            else supports_image_input
+        )
+        outer_image_capability = self._outer_image_capability(
+            candidate_image_capability
+        )

        has_streamed_content = False

@@ -717,13 +782,19 @@ class LLMProvider(ABC):
            has_streamed_content = False

        kw: dict[str, Any] = dict(
-            messages=messages, tools=tools, model=model,
+            messages=self._messages_for_image_capability(
+                messages,
+                supports_image_input=outer_image_capability,
+            ),
+            tools=tools,
+            model=model,
            max_tokens=max_tokens, temperature=temperature,
            reasoning_effort=reasoning_effort, tool_choice=tool_choice,
            on_content_delta=_tracking_delta if on_content_delta is not None else None,
            on_thinking_delta=on_thinking_delta,
            on_tool_call_delta=on_tool_call_delta,
        )
+        kw.update(self._image_policy_request_kwargs(candidate_image_capability))
        if on_stream_recover and getattr(self, "supports_stream_recover_callback", False):
            kw["on_stream_recover"] = _recover_stream
        return await self._run_with_retry(
@@ -734,6 +805,7 @@ class LLMProvider(ABC):
            on_retry_wait=on_retry_wait,
            should_retry_guard=lambda: not has_streamed_content,
            on_stream_recover=_recover_stream if on_stream_recover else None,
+            supports_image_input=outer_image_capability,
        )

    async def chat_with_retry(
@@ -747,6 +819,7 @@ class LLMProvider(ABC):
        tool_choice: str | dict[str, Any] | None = None,
        retry_mode: str = "standard",
        on_retry_wait: Callable[[str], Awaitable[None]] | None = None,
+        supports_image_input: bool | None | object = _SENTINEL,
    ) -> LLMResponse:
        """Call chat() with retry on transient provider failures.

@@ -763,18 +836,33 @@ class LLMProvider(ABC):
            temperature = self.generation.temperature
        if reasoning_effort is self._SENTINEL:
            reasoning_effort = self.generation.reasoning_effort
+        candidate_image_capability = (
+            self.supports_image_input
+            if supports_image_input is self._SENTINEL
+            else supports_image_input
+        )
+        outer_image_capability = self._outer_image_capability(
+            candidate_image_capability
+        )

        kw: dict[str, Any] = dict(
-            messages=messages, tools=tools, model=model,
+            messages=self._messages_for_image_capability(
+                messages,
+                supports_image_input=outer_image_capability,
+            ),
+            tools=tools,
+            model=model,
            max_tokens=max_tokens, temperature=temperature,
            reasoning_effort=reasoning_effort, tool_choice=tool_choice,
        )
+        kw.update(self._image_policy_request_kwargs(candidate_image_capability))
        return await self._run_with_retry(
            self._safe_chat,
            kw,
            messages,
            retry_mode=retry_mode,
            on_retry_wait=on_retry_wait,
+            supports_image_input=outer_image_capability,
        )

    @classmethod
@@ -882,6 +970,7 @@ class LLMProvider(ABC):
        on_retry_wait: Callable[[str], Awaitable[None]] | None,
        should_retry_guard: Callable[[], bool] | None = None,
        on_stream_recover: Callable[[], Awaitable[None]] | None = None,
+        supports_image_input: bool | None | object = _SENTINEL,
    ) -> LLMResponse:
        attempt = 0
        delays = list(self._CHAT_RETRY_DELAYS)
@@ -928,9 +1017,19 @@ class LLMProvider(ABC):

            if not self._is_transient_response(response):
                stripped = self._strip_image_content(original_messages)
-                if stripped is not None and stripped != kw["messages"]:
+                if (
+                    (
+                        self.supports_image_input
+                        if supports_image_input is self._SENTINEL
+                        else supports_image_input
+                    )
+                    is None
+                    and self._is_image_unsupported_response(response)
+                    and stripped is not None
+                    and stripped != kw["messages"]
+                ):
                    logger.warning(
-                        "Non-transient LLM error with image content, retrying without images"
+                        "Model rejected image input, retrying without images"
                    )
                    retry_kw = dict(kw)
                    retry_kw["messages"] = stripped
@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path

-from nanobot.config.schema import Config, InlineFallbackConfig, ModelPresetConfig, ProviderConfig
+from nanobot.config.schema import Config, ModelPresetConfig, ProviderConfig
 from nanobot.providers.base import GenerationSettings, LLMProvider
 from nanobot.providers.fallback_provider import FallbackProvider
 from nanobot.providers.registry import ProviderSpec, create_dynamic_spec, find_by_name
@@ -19,6 +19,16 @@ class ProviderSnapshot:
    signature: tuple[object, ...]
    generation: GenerationSettings | None = None
    model_preset: str | None = None
+    supports_image_input: bool | None = None
+
+
+@dataclass(frozen=True)
+class _ProviderSetup:
+    model: str
+    provider_name: str
+    provider_config: ProviderConfig | None
+    spec: ProviderSpec | None
+    backend: str


 def _resolve_model_preset(
@@ -40,20 +50,20 @@ def _provider_extra_headers(
    return headers or None


-def _make_provider_core(
+def _resolve_provider_setup(
    config: Config,
    *,
-    preset_name: str | None = None,
-    preset: ModelPresetConfig | None = None,
+    preset: ModelPresetConfig,
    model: str | None = None,
-) -> LLMProvider:
-    """Create a plain LLM provider without failover wrapping."""
-    resolved = _resolve_model_preset(config, preset_name=preset_name, preset=preset)
-    model = model or resolved.model
-    provider_name = config.get_provider_name(model, preset=resolved)
-    p = config.get_provider(model, preset=resolved)
-    spec = find_by_name(provider_name) if provider_name else None
-    if provider_name and not spec and p:
+) -> _ProviderSetup:
+    """Resolve and validate provider configuration without constructing a client."""
+    model = model or preset.model
+    provider_name = config.get_provider_name(model, preset=preset)
+    p = config.get_provider(model, preset=preset)
+    if not provider_name:
+        raise ValueError(f"No provider is configured for model '{model}'.")
+    spec = find_by_name(provider_name)
+    if not spec and p:
        if not p.api_base:
            raise ValueError(f"Provider '{provider_name}' requires api_base in config.")
        spec = create_dynamic_spec(
@@ -81,12 +91,57 @@ def _make_provider_core(
        and not (p and p.api_base)
    ):
        raise ValueError(f"Provider '{provider_name}' requires api_base in config.")
-    elif backend == "openai_compat" and not model.startswith("bedrock/"):
+    elif backend in {"anthropic", "openai_compat"} and not (
+        backend == "openai_compat" and model.startswith("bedrock/")
+    ):
        needs_key = not (p and p.api_key)
        exempt = spec and (spec.is_oauth or spec.is_local or spec.is_direct)
        if needs_key and not exempt:
            raise ValueError(f"No API key configured for provider '{provider_name}'.")

+    return _ProviderSetup(
+        model=model,
+        provider_name=provider_name,
+        provider_config=p,
+        spec=spec,
+        backend=backend,
+    )
+
+
+def validate_provider_setup(
+    config: Config,
+    *,
+    preset_name: str | None = None,
+    preset: ModelPresetConfig | None = None,
+    model: str | None = None,
+) -> None:
+    """Validate local provider/model settings without loading a provider client."""
+    resolved = _resolve_model_preset(config, preset_name=preset_name, preset=preset)
+    _resolve_provider_setup(
+        config,
+        preset=resolved,
+        model=model,
+    )
+
+
+def _make_provider_core(
+    config: Config,
+    *,
+    preset: ModelPresetConfig,
+    model: str | None = None,
+) -> LLMProvider:
+    """Create a plain LLM provider without failover wrapping."""
+    setup = _resolve_provider_setup(
+        config,
+        preset=preset,
+        model=model,
+    )
+    model = setup.model
+    provider_name = setup.provider_name
+    p = setup.provider_config
+    spec = setup.spec
+    backend = setup.backend
+
    if backend == "openai_codex":
        from nanobot.providers.openai_codex_provider import OpenAICodexProvider

@@ -120,7 +175,7 @@ def _make_provider_core(

        provider = AnthropicProvider(
            api_key=p.api_key if p else None,
-            api_base=config.get_api_base(model, preset=resolved),
+            api_base=config.get_api_base(model, preset=preset),
            default_model=model,
            extra_headers=_provider_extra_headers(spec, p),
        )
@@ -140,7 +195,7 @@ def _make_provider_core(

        provider = OpenAICompatProvider(
            api_key=p.api_key if p else None,
-            api_base=config.get_api_base(model, preset=resolved),
+            api_base=config.get_api_base(model, preset=preset),
            default_model=model,
            extra_headers=_provider_extra_headers(spec, p),
            spec=spec,
@@ -150,38 +205,16 @@ def _make_provider_core(
            proxy=p.proxy if p else None,
        )

-    provider.generation = resolved.to_generation_settings()
+    provider.generation = preset.to_generation_settings()
+    provider.supports_image_input = preset.supports_image_input
    return provider


-def _inline_fallback_preset(
-    primary: ModelPresetConfig,
-    fallback: InlineFallbackConfig,
-) -> ModelPresetConfig:
-    return ModelPresetConfig(
-        model=fallback.model,
-        provider=fallback.provider,
-        max_tokens=fallback.max_tokens if fallback.max_tokens is not None else primary.max_tokens,
-        context_window_tokens=(
-            fallback.context_window_tokens
-            if fallback.context_window_tokens is not None
-            else primary.context_window_tokens
-        ),
-        temperature=(
-            fallback.temperature if fallback.temperature is not None else primary.temperature
-        ),
-        reasoning_effort=fallback.reasoning_effort,
-    )
-
-
-def _resolve_fallback_presets(config: Config, primary: ModelPresetConfig) -> list[ModelPresetConfig]:
-    presets: list[ModelPresetConfig] = []
-    for fallback in config.agents.defaults.fallback_models:
-        if isinstance(fallback, str):
-            presets.append(config.model_presets[fallback])
-        else:
-            presets.append(_inline_fallback_preset(primary, fallback))
-    return presets
+def _resolve_fallback_presets(config: Config, _primary: ModelPresetConfig) -> list[ModelPresetConfig]:
+    return [
+        config.model_presets[name]
+        for name in config.agents.defaults.fallback_models
+    ]


 def make_provider(
@@ -197,16 +230,14 @@ def make_provider(
    the failover path to create providers for fallback models.
    """
    resolved = _resolve_model_preset(config, preset_name=preset_name, preset=preset)
-    provider = _make_provider_core(config, preset_name=preset_name, preset=preset, model=model)
+    provider = _make_provider_core(config, preset=resolved, model=model)
    fallback_presets = _resolve_fallback_presets(config, resolved)

    if fallback_presets:
        provider = FallbackProvider(
            primary=provider,
            fallback_presets=fallback_presets,
-            provider_factory=lambda fb: _make_provider_core(
-                config, preset_name=preset_name, preset=fb
-            ),
+            provider_factory=lambda fb: _make_provider_core(config, preset=fb),
        )

    return provider
@@ -225,6 +256,7 @@ def build_unconfigured_provider_snapshot(config: Config, setup_error: str) -> Pr
        context_window_tokens=preset.context_window_tokens,
        signature=("unconfigured", setup_error, preset.model),
        generation=provider.generation,
+        supports_image_input=preset.supports_image_input,
    )


@@ -258,6 +290,7 @@ def provider_signature(
            fallback.temperature,
            fallback.reasoning_effort,
            fallback.context_window_tokens,
+            fallback.supports_image_input,
            getattr(fp, "proxy", None) if fp else None,
            fp.thinking_style if fp else None,
        )
@@ -279,6 +312,7 @@ def provider_signature(
        resolved.temperature,
        resolved.reasoning_effort,
        resolved.context_window_tokens,
+        resolved.supports_image_input,
        getattr(p, "proxy", None) if p else None,
        p.thinking_style if p else None,
        tuple(_fallback_signature(fallback) for fallback in fallback_presets),
@@ -308,6 +342,7 @@ def build_provider_snapshot(
        signature=provider_signature(config, preset=resolved),
        generation=resolved.to_generation_settings(),
        model_preset=selected_preset,
+        supports_image_input=resolved.supports_image_input,
    )


@@ -319,6 +354,9 @@ def load_provider_snapshot(
    from nanobot.config.loader import load_config, resolve_config_env_vars

    return build_provider_snapshot(
-        resolve_config_env_vars(load_config(config_path)),
+        resolve_config_env_vars(
+            load_config(config_path),
+            config_path=config_path,
+        ),
        preset_name=preset_name,
    )
@@ -13,7 +13,6 @@ from nanobot.providers.base import LLMProvider, LLMResponse
 # Circuit breaker tuned to match OpenAICompatProvider's Responses API breaker.
 _PRIMARY_FAILURE_THRESHOLD = 3
 _PRIMARY_COOLDOWN_S = 60
-_MISSING = object()
 _FALLBACK_ERROR_KINDS = frozenset({
    "timeout",
    "connection",
@@ -118,6 +117,9 @@ class FallbackProvider(LLMProvider):
        self._provider_factory = provider_factory
        self._fallback_model_observer = fallback_model_observer
        self._has_fallbacks = bool(fallback_presets)
+        # Candidate-specific image policy is applied inside _try_with_fallback;
+        # the outer retry wrapper preserves canonical images for the chain.
+        self.supports_image_input = getattr(primary, "supports_image_input", None)
        self._primary_failures = 0
        self._primary_tripped_at: float | None = None

@@ -140,6 +142,19 @@ class FallbackProvider(LLMProvider):
    def supports_progress_deltas(self) -> bool:
        return bool(getattr(self._primary, "supports_progress_deltas", False))

+    def _outer_image_capability(
+        self,
+        supports_image_input: bool | None,
+    ) -> bool | None:
+        """Keep canonical images intact until each candidate applies its policy."""
+        return True
+
+    def _image_policy_request_kwargs(
+        self,
+        supports_image_input: bool | None,
+    ) -> dict[str, Any]:
+        return {"_primary_supports_image_input": supports_image_input}
+
    def _primary_available(self) -> bool:
        """Return True if the primary provider is not currently tripped."""
        if self._primary_tripped_at is None:
@@ -150,16 +165,39 @@ class FallbackProvider(LLMProvider):
        return False

    async def chat(self, **kwargs: Any) -> LLMResponse:
+        primary_supports_image_input = kwargs.pop(
+            "_primary_supports_image_input",
+            getattr(self._primary, "supports_image_input", None),
+        )
        if not self._has_fallbacks:
-            return await self._primary.chat(**kwargs)
+            return await self._call_with_image_policy(
+                lambda p, kw: p.chat(**kw),
+                self._primary,
+                kwargs,
+                has_streamed=None,
+                supports_image_input=primary_supports_image_input,
+            )
        return await self._try_with_fallback(
-            lambda p, kw: p.chat(**kw), kwargs, has_streamed=None
+            lambda p, kw: p.chat(**kw),
+            kwargs,
+            has_streamed=None,
+            primary_supports_image_input=primary_supports_image_input,
        )

    async def chat_stream(self, **kwargs: Any) -> LLMResponse:
        on_stream_recover = kwargs.pop("on_stream_recover", None)
+        primary_supports_image_input = kwargs.pop(
+            "_primary_supports_image_input",
+            getattr(self._primary, "supports_image_input", None),
+        )
        if not self._has_fallbacks:
-            return await self._primary.chat_stream(**kwargs)
+            return await self._call_with_image_policy(
+                lambda p, kw: p.chat_stream(**kw),
+                self._primary,
+                kwargs,
+                has_streamed=None,
+                supports_image_input=primary_supports_image_input,
+            )

        has_streamed: list[bool] = [False]
        original_delta = kwargs.get("on_content_delta")
@@ -176,6 +214,7 @@ class FallbackProvider(LLMProvider):
            kwargs,
            has_streamed=has_streamed,
            on_stream_recover=on_stream_recover,
+            primary_supports_image_input=primary_supports_image_input,
        )

    async def _try_with_fallback(
@@ -184,6 +223,7 @@ class FallbackProvider(LLMProvider):
        kwargs: dict[str, Any],
        has_streamed: list[bool] | None,
        on_stream_recover: Callable[[], Awaitable[None]] | None = None,
+        primary_supports_image_input: bool | None | object = LLMProvider._SENTINEL,
    ) -> LLMResponse:
        primary_model = kwargs.get("model") or self._primary.get_default_model()
        primary_was_attempted = False
@@ -191,7 +231,13 @@ class FallbackProvider(LLMProvider):

        if self._primary_available():
            primary_was_attempted = True
-            response = await call(self._primary, kwargs)
+            response = await self._call_with_image_policy(
+                call,
+                self._primary,
+                kwargs,
+                has_streamed=has_streamed,
+                supports_image_input=primary_supports_image_input,
+            )
            if response.finish_reason != "error":
                self._primary_failures = 0
                self._primary_tripped_at = None
@@ -217,7 +263,8 @@ class FallbackProvider(LLMProvider):
                    )
                    return response

-            if not self._should_fallback(response):
+            image_rejected = self._primary._is_image_unsupported_response(response)
+            if not image_rejected and not self._should_fallback(response):
                logger.warning(
                    "Primary model '{}' returned non-fallbackable error: {}",
                    primary_model,
@@ -225,13 +272,14 @@ class FallbackProvider(LLMProvider):
                )
                return response

-            self._primary_failures += 1
-            if self._primary_failures >= _PRIMARY_FAILURE_THRESHOLD:
-                self._primary_tripped_at = time.monotonic()
-                logger.warning(
-                    "Primary model '{}' circuit open after {} consecutive failures",
-                    primary_model, self._primary_failures,
-                )
+            if not image_rejected:
+                self._primary_failures += 1
+                if self._primary_failures >= _PRIMARY_FAILURE_THRESHOLD:
+                    self._primary_tripped_at = time.monotonic()
+                    logger.warning(
+                        "Primary model '{}' circuit open after {} consecutive failures",
+                        primary_model, self._primary_failures,
+                    )
        else:
            logger.debug("Primary model '{}' circuit open; skipping", primary_model)

@@ -271,6 +319,7 @@ class FallbackProvider(LLMProvider):
                )
            try:
                fallback_provider = self._provider_factory(fallback)
+                fallback_provider.supports_image_input = fallback.supports_image_input
            except Exception as exc:
                logger.warning(
                    "Failed to create provider for fallback '{}': {}", fallback_model, exc
@@ -279,25 +328,23 @@ class FallbackProvider(LLMProvider):

            await self._notify_fallback_model(fallback_model)

-            original_values = {
-                name: kwargs.get(name, _MISSING)
-                for name in ("model", "max_tokens", "temperature", "reasoning_effort")
+            fallback_kwargs = {
+                **kwargs,
+                "model": fallback_model,
+                "max_tokens": fallback.max_tokens,
+                "temperature": fallback.temperature,
            }
-            kwargs["model"] = fallback_model
-            kwargs["max_tokens"] = fallback.max_tokens
-            kwargs["temperature"] = fallback.temperature
            if fallback.reasoning_effort is None:
-                kwargs.pop("reasoning_effort", None)
+                fallback_kwargs.pop("reasoning_effort", None)
            else:
-                kwargs["reasoning_effort"] = fallback.reasoning_effort
-            try:
-                fallback_response = await call(fallback_provider, kwargs)
-            finally:
-                for name, value in original_values.items():
-                    if value is _MISSING:
-                        kwargs.pop(name, None)
-                    else:
-                        kwargs[name] = value
+                fallback_kwargs["reasoning_effort"] = fallback.reasoning_effort
+            fallback_response = await self._call_with_image_policy(
+                call,
+                fallback_provider,
+                fallback_kwargs,
+                has_streamed=has_streamed,
+                supports_image_input=fallback.supports_image_input,
+            )

            if fallback_response.finish_reason != "error":
                logger.info(
@@ -326,6 +373,49 @@ class FallbackProvider(LLMProvider):
            finish_reason="error",
        )

+    @staticmethod
+    async def _call_with_image_policy(
+        call: Callable[[LLMProvider, dict[str, Any]], Awaitable[LLMResponse]],
+        provider: LLMProvider,
+        kwargs: dict[str, Any],
+        *,
+        has_streamed: list[bool] | None,
+        supports_image_input: bool | None | object = LLMProvider._SENTINEL,
+    ) -> LLMResponse:
+        original_messages = kwargs.get("messages")
+        if not isinstance(original_messages, list):
+            return await call(provider, kwargs)
+
+        prepared_kwargs = dict(kwargs)
+        prepared_kwargs["messages"] = provider._messages_for_image_capability(
+            original_messages,
+            supports_image_input=supports_image_input,
+        )
+        response = await call(provider, prepared_kwargs)
+        capability = (
+            provider.supports_image_input
+            if supports_image_input is LLMProvider._SENTINEL
+            else supports_image_input
+        )
+        if (
+            capability is None
+            and provider._is_image_unsupported_response(response)
+            and (has_streamed is None or not has_streamed[0])
+        ):
+            stripped = provider._strip_image_content(original_messages)
+            if stripped is not None and stripped != prepared_kwargs["messages"]:
+                logger.warning(
+                    "Fallback candidate '{}' rejected image input, retrying without images",
+                    prepared_kwargs.get("model") or provider.get_default_model(),
+                )
+                retry_kwargs = dict(prepared_kwargs)
+                retry_kwargs["messages"] = stripped
+                retry_response = await call(provider, retry_kwargs)
+                if retry_response.finish_reason != "error":
+                    provider._strip_image_content_inplace(original_messages)
+                return retry_response
+        return response
+
    async def _notify_fallback_model(self, model: str) -> None:
        if self._fallback_model_observer is None:
            return
@@ -23,7 +23,10 @@ MAX_WEBUI_QUOTE_CHARS = 4_000

@dataclass(frozen=True)
 class RuntimeContextBlock:
-    """One provider-owned block appended to the current user content."""
+    """Provider-owned context appended verbatim to the current user content.
+
+    Callers must bound and delimit content obtained from untrusted sources.
+    """

    source: str
    content: str
@@ -2,12 +2,13 @@

 from __future__ import annotations

-from collections.abc import Iterable, Mapping
+from collections.abc import Awaitable, Callable, Iterable, Mapping
 from copy import deepcopy
 from pathlib import Path
 from typing import TYPE_CHECKING, Any

-from nanobot.runtime_context import RUNTIME_CONTEXT_HISTORY_META
+from nanobot.bus.runtime_events import SessionTurnPersisted
+from nanobot.runtime_context import RUNTIME_CONTEXT_HISTORY_META, RuntimeContextProvider
 from nanobot.sdk.types import (
    SessionInfo,
    SessionSnapshot,
@@ -193,6 +194,20 @@ class RuntimeClient:
        """Current runtime workspace."""
        return self._loop.workspace

+    def add_context_provider(
+        self,
+        provider: RuntimeContextProvider,
+    ) -> Callable[[], None]:
+        """Register per-turn model context and return an unsubscribe callback."""
+        return self._loop.register_runtime_context_provider(provider)
+
+    def on_session_turn_persisted(
+        self,
+        handler: Callable[[SessionTurnPersisted], Awaitable[None] | None],
+    ) -> Callable[[], None]:
+        """Register a persisted-turn callback and return an unsubscribe callback."""
+        return self._loop.runtime_events.subscribe(handler, SessionTurnPersisted)
+
    async def compact_session(self, session_key: str) -> SessionSnapshot:
        """Run token/replay-window consolidation for one session."""
        session = self._loop.sessions.get_or_create(session_key)
@@ -2,18 +2,10 @@

 from __future__ import annotations

+from collections.abc import Mapping
 from typing import Any


-def ensure_single_model_selector(
-    *,
-    model: str | None,
-    model_preset: str | None,
-) -> None:
-    if model is not None and model_preset is not None:
-        raise ValueError("model and model_preset are mutually exclusive")
-
-
 def build_process_direct_kwargs(
    *,
    session_key: str,
@@ -22,6 +14,7 @@ def build_process_direct_kwargs(
    sender_id: str,
    media: list[str] | None,
    ephemeral: bool,
+    attributes: Mapping[str, Any] | None = None,
    on_stream: Any | None = None,
    on_stream_end: Any | None = None,
 ) -> dict[str, Any]:
@@ -37,6 +30,8 @@ def build_process_direct_kwargs(
    if ephemeral:
        kwargs["ephemeral"] = True
        kwargs["_run_extra_hooks_for_ephemeral"] = True
+    if attributes is not None:
+        kwargs["attributes"] = dict(attributes)
    if on_stream is not None:
        kwargs["on_stream"] = on_stream
    if on_stream_end is not None:
@@ -5,7 +5,6 @@ import errno
 import json
 import os
 import re
-import shutil
 from collections import OrderedDict
 from contextlib import suppress
 from copy import deepcopy
@@ -23,10 +22,10 @@ from nanobot.runtime_context import (
    public_history_message,
 )
 from nanobot.utils.helpers import (
+    content_with_media_breadcrumbs,
    ensure_dir,
    estimate_message_tokens,
    find_legal_message_start,
-    image_placeholder_text,
    recent_message_start_index,
    safe_filename,
    strip_think,
@@ -166,6 +165,7 @@ class Session:
        max_tokens: int = 0,
        extend_to_user: bool = False,
        include_runtime_context: bool = True,
+        include_media: bool = False,
    ) -> list[dict[str, Any]]:
        """Return unconsolidated messages for LLM input.

@@ -210,17 +210,17 @@ class Session:
            role = message.get("role")
            if role == "assistant" and isinstance(content, str):
                content = _sanitize_assistant_replay_text(content)
-            # Synthesize an ``[image: path]`` breadcrumb from the persisted
-            # ``media`` kwarg so LLM replay still sees *something* where the
-            # image used to be. Without this, an image-only user turn
-            # replays as an empty user message — the assistant's reply then
-            # looks like it's responding to nothing.
            media = message.get("media")
-            if role == "user" and isinstance(media, list) and media and isinstance(content, str):
-                breadcrumbs = "\n".join(
-                    image_placeholder_text(p) for p in media if isinstance(p, str) and p
-                )
-                content = f"{content}\n{breadcrumbs}" if content else breadcrumbs
+            media_paths = (
+                [path for path in media if isinstance(path, str) and path]
+                if role == "user" and isinstance(media, list)
+                else []
+            )
+            # General history consumers retain a compact breadcrumb. The agent
+            # loop asks for internal media refs and deterministically rebuilds
+            # image blocks at the request boundary.
+            if media_paths and not include_media:
+                content = content_with_media_breadcrumbs(role, content, media_paths)
            cli_apps = message.get("cli_apps")
            if (
                include_runtime_context
@@ -249,6 +249,11 @@ class Session:
                if not any(key in message for key in ("tool_calls", "reasoning_content", "thinking_blocks")):
                    continue
            entry: dict[str, Any] = {"role": message["role"], "content": content}
+            if media_paths and include_media:
+                entry["_media_paths"] = media_paths
+                runtime_context = message.get(RUNTIME_CONTEXT_HISTORY_META)
+                if isinstance(runtime_context, dict):
+                    entry[RUNTIME_CONTEXT_HISTORY_META] = deepcopy(runtime_context)
            for key in ("tool_calls", "tool_call_id", "name", "reasoning_content", "thinking_blocks"):
                if key in message:
                    entry[key] = message[key]
@@ -477,6 +482,14 @@ class SessionManager:
        except _SESSION_DATA_ERRORS:
            return None

+    @classmethod
+    def _session_key_from_path(cls, path: Path) -> str | None:
+        """Decode a session key only from a canonical collision-resistant filename."""
+        key = cls._decode_storage_key(path.stem)
+        if key is None or cls._storage_key(key) != path.stem:
+            return None
+        return key
+
    def _get_session_path(self, key: str) -> Path:
        """Get the collision-resistant workspace path for a session."""
        return self.sessions_dir / f"{self._storage_key(key)}.jsonl"
@@ -489,61 +502,6 @@ class SessionManager:
        """Legacy global session path (~/.nanobot/sessions/)."""
        return self.legacy_sessions_dir / f"{self.safe_key(key)}.jsonl"

-    @staticmethod
-    def _stored_key_for_path(path: Path) -> str | None:
-        """Read the stored session key from a JSONL metadata row, if present."""
-        try:
-            with open(path, encoding="utf-8") as f:
-                for line in f:
-                    line = line.strip()
-                    if not line:
-                        continue
-                    data = json.loads(line)
-                    if not isinstance(data, dict):
-                        raise ValueError("session records must be JSON objects")
-                    if data.get("_type") == "metadata":
-                        stored_key = data.get("key")
-                        return stored_key if isinstance(stored_key, str) else None
-                    return None
-        except _SESSION_DATA_ERRORS:
-            return None
-        return None
-
-    def _resolve_session_path(self, key: str, *, migrate: bool = False) -> Path | None:
-        """Resolve a session path, falling back to legacy storage locations."""
-        path = self._get_session_path(key)
-        if path.exists():
-            return path
-
-        # TODO(v0.3.1): Remove both legacy fallbacks. v0.3.0 is the final
-        # compatibility window for reading and lazily migrating legacy session files.
-        fallback_paths = [
-            (self._get_legacy_lossy_path(key), "legacy lossy path"),
-            (self._get_legacy_session_path(key), "legacy path"),
-        ]
-        for fallback_path, description in fallback_paths:
-            if not fallback_path.exists():
-                continue
-            stored_key = self._stored_key_for_path(fallback_path)
-            if stored_key and stored_key != key:
-                logger.info(
-                    "Skipping session {} from {} because it belongs to {}",
-                    key,
-                    description,
-                    stored_key,
-                )
-                continue
-            if not migrate:
-                return fallback_path
-            try:
-                shutil.move(str(fallback_path), str(path))
-                logger.info("Migrated session {} from {}", key, description)
-            except Exception:
-                logger.exception("Failed to migrate session {}", key)
-                return None
-            return path
-        return None
-
    def get_or_create(self, key: str) -> Session:
        """
        Get an existing session or create a new one.
@@ -567,8 +525,8 @@ class SessionManager:

    def _load(self, key: str) -> Session | None:
        """Load a session from disk."""
-        path = self._resolve_session_path(key, migrate=True)
-        if path is None:
+        path = self._get_session_path(key)
+        if not path.exists():
            return None

        try:
@@ -847,8 +805,8 @@ class SessionManager:
        Returns ``{"key", "created_at", "updated_at", "metadata", "messages"}`` or
        ``None`` when the session file does not exist or fails to parse.
        """
-        path = self._resolve_session_path(key)
-        if path is None:
+        path = self._get_session_path(key)
+        if not path.exists():
            return None
        try:
            messages: list[dict[str, Any]] = []
@@ -890,8 +848,8 @@ class SessionManager:
        This is used by WebUI routes that need session-level metadata but not the
        full conversation transcript.
        """
-        path = self._resolve_session_path(key)
-        if path is None:
+        path = self._get_session_path(key)
+        if not path.exists():
            return None
        try:
            with open(path, encoding="utf-8") as f:
@@ -935,8 +893,9 @@ class SessionManager:
        sessions = []

        for path in self.sessions_dir.glob("*.jsonl"):
-            decoded = self._decode_storage_key(path.stem)
-            fallback_key = decoded or path.stem.replace("_", ":", 1)
+            storage_key = self._session_key_from_path(path)
+            if storage_key is None:
+                continue
            try:
                # Read the metadata line and a small preview for session lists.
                with open(path, encoding="utf-8") as f:
@@ -946,7 +905,7 @@ class SessionManager:
                        if not isinstance(data, dict):
                            raise ValueError("session records must be JSON objects")
                        if data.get("_type") == "metadata":
-                            key = data.get("key") or fallback_key
+                            key = data.get("key") or storage_key
                            metadata = data.get("metadata", {})
                            title = _metadata_title(metadata)
                            preview = ""
@@ -991,7 +950,7 @@ class SessionManager:
            except FileNotFoundError:
                continue
            except _SESSION_DATA_ERRORS:
-                repaired = self._repair(fallback_key, path=path)
+                repaired = self._repair(storage_key, path=path)
                if repaired is not None:
                    sessions.append(
                        {
@@ -5,7 +5,7 @@ from __future__ import annotations
 import re
 import time
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass, field, replace
+from dataclasses import dataclass, replace
 from typing import Any
 from uuid import uuid4

@@ -42,7 +42,10 @@ from nanobot.session.history_visibility import is_hidden_history_message
 from nanobot.session.manager import Session, SessionManager
 from nanobot.utils.helpers import strip_think, truncate_text
 from nanobot.utils.llm_runtime import LLMRuntime
-from nanobot.webui.metadata import WEBUI_TURN_METADATA_KEY
+from nanobot.webui.metadata import (
+    WEBSOCKET_TURN_OWNER_METADATA_KEY,
+    WEBUI_TURN_METADATA_KEY,
+)

 WEBUI_SESSION_METADATA_KEY = "webui"
 WEBUI_TITLE_METADATA_KEY = "title"
@@ -51,9 +54,42 @@ TITLE_MAX_CHARS = 60
 TITLE_GENERATION_MAX_TOKENS = 96
 TITLE_GENERATION_REASONING_EFFORT = "none"

-# Wall-clock turn start per ``chat_id`` (websocket only). Survives browser refresh while the
-# gateway process stays up; cleared on idle/stop and implicitly dropped on restart.
+# Latest active turn projection per ``chat_id`` (websocket only). It survives browser refresh
+# while the gateway process stays up and is implicitly dropped on restart.
 _WEBSOCKET_TURN_WALL_STARTED_AT: dict[str, float] = {}
+_WEBSOCKET_TURN_IDS: dict[str, str] = {}
+_WEBSOCKET_TURN_OWNERS: dict[str, str] = {}
+
+
+@dataclass(frozen=True)
+class _WebsocketTurn:
+    started_at: float
+    turn_id: str | None
+    transcript_persistence_failed: bool = False
+
+
+# All in-flight lifecycle owners per chat, in admission order. The three maps
+# above remain the latest-owner projection consumed by the HTTP API.
+_WEBSOCKET_ACTIVE_TURNS: dict[str, dict[str, _WebsocketTurn]] = {}
+
+
+def _sync_websocket_turn_projection(chat_id: str) -> None:
+    turns = _WEBSOCKET_ACTIVE_TURNS.get(chat_id)
+    if not turns:
+        _WEBSOCKET_ACTIVE_TURNS.pop(chat_id, None)
+        _WEBSOCKET_TURN_WALL_STARTED_AT.pop(chat_id, None)
+        _WEBSOCKET_TURN_IDS.pop(chat_id, None)
+        _WEBSOCKET_TURN_OWNERS.pop(chat_id, None)
+        return
+
+    owner = next(reversed(turns))
+    turn = turns[owner]
+    _WEBSOCKET_TURN_WALL_STARTED_AT[chat_id] = turn.started_at
+    _WEBSOCKET_TURN_OWNERS[chat_id] = owner
+    if turn.turn_id is None:
+        _WEBSOCKET_TURN_IDS.pop(chat_id, None)
+    else:
+        _WEBSOCKET_TURN_IDS[chat_id] = turn.turn_id


 def mark_webui_session(session: Session, metadata: dict[str, Any]) -> bool:
@@ -203,6 +239,96 @@ def websocket_turn_wall_started_at(chat_id: str) -> float | None:
    return _WEBSOCKET_TURN_WALL_STARTED_AT.get(chat_id)


+def websocket_turn_id(chat_id: str) -> str | None:
+    """Return the WebUI identity of the active turn, when one was provided."""
+    return _WEBSOCKET_TURN_IDS.get(chat_id)
+
+
+def register_queued_websocket_turn_if_idle(
+    chat_id: str,
+    turn_id: str | None,
+) -> str | None:
+    """Track an accepted WebUI turn while it waits for AgentLoop admission."""
+    if websocket_turn_wall_started_at(chat_id) is not None:
+        return None
+    owner = uuid4().hex
+    _WEBSOCKET_ACTIVE_TURNS.setdefault(chat_id, {})[owner] = _WebsocketTurn(
+        started_at=time.time(),
+        turn_id=turn_id,
+    )
+    _sync_websocket_turn_projection(chat_id)
+    return owner
+
+
+def websocket_turn_owner_is_registered(
+    chat_id: str,
+    owner: str,
+    turn_id: str | None,
+) -> bool:
+    """Return whether websocket ingress registered this owner for the turn."""
+    turn = _WEBSOCKET_ACTIVE_TURNS.get(chat_id, {}).get(owner)
+    return turn is not None and turn.turn_id == turn_id
+
+
+def websocket_turn_transcript_persistence_failed(
+    chat_id: str,
+    owner: str | None = None,
+) -> bool:
+    """Return whether one active owner has an incomplete canonical transcript."""
+    turns = _WEBSOCKET_ACTIVE_TURNS.get(chat_id)
+    if not turns:
+        return False
+    selected_owner = owner or next(reversed(turns))
+    turn = turns.get(selected_owner)
+    return turn.transcript_persistence_failed if turn is not None else False
+
+
+def mark_websocket_turn_transcript_persistence_failed(
+    chat_id: str,
+    owner: str | None,
+) -> bool:
+    """Keep a turn active when any canonical display event could not be written."""
+    if not owner:
+        return False
+    turns = _WEBSOCKET_ACTIVE_TURNS.get(chat_id)
+    if turns is None or owner not in turns:
+        return False
+    turns[owner] = replace(turns[owner], transcript_persistence_failed=True)
+    return True
+
+
+def clear_websocket_turn_if_current(
+    chat_id: str,
+    owner: str | None,
+    *,
+    preserve_persistence_failure: bool = False,
+) -> bool:
+    """Clear one lifecycle owner without disturbing concurrent turns for the chat."""
+    if not owner:
+        return False
+    turns = _WEBSOCKET_ACTIVE_TURNS.get(chat_id)
+    if turns is not None:
+        if owner not in turns:
+            return False
+        if preserve_persistence_failure and turns[owner].transcript_persistence_failed:
+            return False
+        turns.pop(owner)
+        _sync_websocket_turn_projection(chat_id)
+        return True
+
+    # Compatibility for callers/tests that populated the legacy projection
+    # directly before the multi-owner registry existed.
+    if (
+        chat_id in _WEBSOCKET_TURN_WALL_STARTED_AT
+        and _WEBSOCKET_TURN_OWNERS.get(chat_id) == owner
+    ):
+        _WEBSOCKET_TURN_WALL_STARTED_AT.pop(chat_id, None)
+        _WEBSOCKET_TURN_IDS.pop(chat_id, None)
+        _WEBSOCKET_TURN_OWNERS.pop(chat_id, None)
+        return True
+    return False
+
+
 def build_bus_progress_callback(
    bus: MessageBus,
    msg: InboundMessage,
@@ -229,9 +355,17 @@ async def publish_turn_run_status(
        else:
            t0 = time.time()
        started_at_event = t0
-        _WEBSOCKET_TURN_WALL_STARTED_AT[cid] = t0
-    else:
-        _WEBSOCKET_TURN_WALL_STARTED_AT.pop(cid, None)
+        owner = msg.metadata.get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
+        if not isinstance(owner, str) or not owner:
+            owner = uuid4().hex
+            msg.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] = owner
+        turn_id = msg.metadata.get(WEBUI_TURN_METADATA_KEY)
+        current_turn_id = turn_id if isinstance(turn_id, str) and turn_id else None
+        turns = _WEBSOCKET_ACTIVE_TURNS.setdefault(cid, {})
+        # Re-registration makes this owner the latest projection.
+        turns.pop(owner, None)
+        turns[owner] = _WebsocketTurn(started_at=t0, turn_id=current_turn_id)
+        _sync_websocket_turn_projection(cid)
    await bus.publish_outbound(
        outbound_message_for_event(
            channel=msg.channel,
@@ -254,25 +388,50 @@ class WebuiTurnRoutePolicy:
        route: TurnRoute,
    ) -> TurnRoute:
        """Make an independently dispatched late subagent result visible in WebUI."""
+        routed = route
        if (
-            msg.channel != "system"
-            or msg.sender_id != "subagent"
-            or msg.metadata.get("injected_event") != "subagent_result"
-            or route.channel != "websocket"
+            msg.channel == "system"
+            and msg.sender_id == "subagent"
+            and msg.metadata.get("injected_event") == "subagent_result"
+            and route.channel == "websocket"
        ):
-            return route
+            session = self.sessions.get_or_create(session_key)
+            if session.metadata.get(WEBUI_SESSION_METADATA_KEY) is True:
+                metadata = dict(route.metadata)
+                metadata.update({
+                    WEBUI_SESSION_METADATA_KEY: True,
+                    "_wants_stream": True,
+                    WEBUI_TURN_METADATA_KEY: f"subagent:{uuid4().hex}",
+                })
+                routed = replace(route, metadata=metadata, publish_lifecycle=True)

-        session = self.sessions.get_or_create(session_key)
-        if session.metadata.get(WEBUI_SESSION_METADATA_KEY) is not True:
-            return route
+        if routed.channel == "websocket" and routed.publish_lifecycle:
+            metadata = dict(routed.metadata)
+            turn_id = metadata.get(WEBUI_TURN_METADATA_KEY)
+            current_turn_id = turn_id if isinstance(turn_id, str) and turn_id else None
+            queued_owner = metadata.get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
+            owner = (
+                queued_owner
+                if (
+                    msg.channel == "websocket"
+                    and isinstance(queued_owner, str)
+                    and websocket_turn_owner_is_registered(
+                        str(msg.chat_id),
+                        queued_owner,
+                        current_turn_id,
+                    )
+                )
+                else uuid4().hex
+            )
+            metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] = owner
+            routed = replace(routed, metadata=metadata)
+            # Direct websocket turns publish their final idle transition from
+            # the original input message. Carry the same server-owned identity
+            # there, overwriting any untrusted client-supplied value.
+            if msg.channel == "websocket":
+                msg.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] = owner

-        metadata = dict(route.metadata)
-        metadata.update({
-            WEBUI_SESSION_METADATA_KEY: True,
-            "_wants_stream": True,
-            WEBUI_TURN_METADATA_KEY: f"subagent:{uuid4().hex}",
-        })
-        return replace(route, metadata=metadata, publish_lifecycle=True)
+        return routed


 def build_webui_fallback_model_observer(bus: MessageBus) -> FallbackModelObserver:
@@ -304,7 +463,6 @@ class WebuiTurnCoordinator:
    bus: MessageBus
    sessions: SessionManager
    schedule_background: Callable[[Awaitable[None]], None]
-    _title_contexts: dict[str, LLMRuntime] = field(default_factory=dict)

    def subscribe(self, runtime_events: RuntimeEventBus) -> Callable[[], None]:
        """Subscribe this coordinator to runtime events."""
@@ -408,18 +566,6 @@ class WebuiTurnCoordinator:
            )
        )

-    def capture_title_context(
-        self,
-        session_key: str,
-        msg: InboundMessage,
-        llm: LLMRuntime,
-    ) -> None:
-        if msg.channel == "websocket" and msg.metadata.get("webui") is True:
-            self._title_contexts[session_key] = llm
-
-    def discard(self, session_key: str) -> None:
-        self._title_contexts.pop(session_key, None)
-
    async def publish_run_status(
        self,
        msg: InboundMessage,
@@ -451,32 +597,6 @@ class WebuiTurnCoordinator:
                metadata=msg.metadata,
            )
        )
-        self._schedule_title_update(msg, session_key=session_key)
-
-    def _schedule_title_update(self, msg: InboundMessage, *, session_key: str) -> None:
-        title_context = self._title_contexts.pop(session_key, None)
-        if msg.metadata.get("webui") is not True or title_context is None:
-            return
-
-        async def _generate_title_and_notify(
-            title_llm: LLMRuntime = title_context,
-        ) -> None:
-            generated = await maybe_generate_webui_title_after_turn(
-                channel=msg.channel,
-                metadata=msg.metadata,
-                sessions=self.sessions,
-                session_key=session_key,
-                provider=title_llm.provider,
-                model=title_llm.model,
-            )
-            if generated:
-                await self._publish_session_metadata_updated(
-                    channel=msg.channel,
-                    chat_id=msg.chat_id,
-                    metadata=msg.metadata,
-                )
-
-        self.schedule_background(_generate_title_and_notify())

    def _schedule_title_update_from_event(self, event: TurnCompleted) -> None:
        title_context = event.runtime
@@ -431,7 +431,7 @@ def _is_text_extension(ext: str) -> bool:


 # ---------------------------------------------------------------------------
-# High-level helper: split media into images + extracted document text
+# High-level helper: split images from on-demand attachment references
 # ---------------------------------------------------------------------------


@@ -454,17 +454,31 @@ def is_image_file(path: str) -> bool:
    return bool(mime and mime.startswith("image/"))


+def _canonical_local_media_path(path: str) -> str:
+    """Return an existing local media file as an absolute path."""
+    try:
+        candidate = Path(path).expanduser()
+        if candidate.is_file():
+            return str(candidate.resolve(strict=False))
+    except (OSError, RuntimeError, TypeError, ValueError):
+        pass
+    return path
+
+
 def reference_non_image_attachments(
    content: str, media: list[str],
 ) -> tuple[str, list[str]]:
-    """Separate images from non-image attachments without reading file content.
+    """Reference non-image attachments without reading file content.

    Image paths are preserved for downstream vision-block construction.
-    Non-image paths are appended as ``[Attachment: path]`` references.
+    Non-image paths are appended as ``[Attachment: path]`` references so the
+    model can inspect them on demand with ``read_file`` or pass the original
+    path to another tool that needs exact file bytes.
    """
    image_paths: list[str] = []
    attachment_refs: list[str] = []
    for path in media:
+        path = _canonical_local_media_path(path)
        if is_image_file(path):
            image_paths.append(path)
        else:
@@ -473,51 +487,3 @@ def reference_non_image_attachments(
        suffix = "\n".join(attachment_refs)
        content = f"{content}\n\n{suffix}" if content else suffix
    return content, image_paths
-
-
-def extract_documents(
-    text: str,
-    media_paths: list[str],
-    *,
-    max_file_size: int = _MAX_EXTRACT_FILE_SIZE,
-) -> tuple[str, list[str]]:
-    """Separate images from documents in *media_paths*.
-
-    Documents (PDF, DOCX, XLSX, PPTX, plain-text, …) have their text
-    extracted and appended to *text*.  Only image paths are kept in the
-    returned list so that downstream layers only need to handle vision
-    blocks.
-
-    Files larger than *max_file_size* bytes are skipped with a warning
-    to avoid unbounded memory / CPU usage.
-    """
-    image_paths: list[str] = []
-    doc_texts: list[str] = []
-
-    for path_str in media_paths:
-        p = Path(path_str)
-        if not p.is_file():
-            continue
-
-        try:
-            size = p.stat().st_size
-        except OSError:
-            continue
-        if size > max_file_size:
-            logger.warning(
-                "Skipping oversized file for extraction: {} ({:.1f} MB > {} MB limit)",
-                p.name, size / (1024 * 1024), max_file_size // (1024 * 1024),
-            )
-            continue
-
-        if is_image_file(path_str):
-            image_paths.append(path_str)
-        else:
-            extracted = extract_text(p)
-            if extracted and not extracted.startswith("[error:"):
-                doc_texts.append(f"[File: {p.name}]\n{extracted}")
-
-    if doc_texts:
-        text = text + "\n\n" + "\n\n".join(doc_texts)
-
-    return text, image_paths
@@ -367,6 +367,24 @@ def image_placeholder_text(path: str | None, *, empty: str = "[image]") -> str:
    return f"[image: {path}]" if path else empty


+def content_with_media_breadcrumbs(
+    role: object,
+    content: object,
+    media: object,
+) -> object:
+    """Append persisted media paths to user text using the canonical breadcrumb."""
+    if role != "user" or not isinstance(content, str) or not isinstance(media, list):
+        return content
+    breadcrumbs = "\n".join(
+        image_placeholder_text(path)
+        for path in media
+        if isinstance(path, str) and path
+    )
+    if not breadcrumbs:
+        return content
+    return f"{content}\n{breadcrumbs}" if content else breadcrumbs
+
+
 def truncate_text(text: str, max_chars: int) -> str:
    """Truncate text with a stable suffix."""
    if max_chars <= 0 or len(text) <= max_chars:
@@ -10,6 +10,8 @@ from nanobot.providers.base import GenerationSettings, LLMProvider
 if TYPE_CHECKING:
    from nanobot.providers.factory import ProviderSnapshot

+_IMAGE_CAPABILITY_UNSET = object()
+

@dataclass(frozen=True, slots=True)
 class LLMRuntime:
@@ -26,6 +28,7 @@ class LLMRuntime:
    context_window_tokens: int
    model_preset: str | None = None
    snapshot_signature: tuple[object, ...] | None = None
+    supports_image_input: bool | None = None

    @classmethod
    def capture(
@@ -36,10 +39,18 @@ class LLMRuntime:
        context_window_tokens: int,
        model_preset: str | None = None,
        snapshot_signature: tuple[object, ...] | None = None,
+        supports_image_input: bool | None | object = _IMAGE_CAPABILITY_UNSET,
    ) -> LLMRuntime:
        """Capture provider defaults without retaining mutable generation state."""
        defaults = GenerationSettings()
        generation = getattr(provider, "generation", defaults)
+        provider_image_capability = getattr(provider, "supports_image_input", None)
+        if not (
+            provider_image_capability is True
+            or provider_image_capability is False
+            or provider_image_capability is None
+        ):
+            provider_image_capability = None
        return cls(
            provider=provider,
            model=model,
@@ -55,6 +66,11 @@ class LLMRuntime:
            context_window_tokens=context_window_tokens,
            model_preset=model_preset,
            snapshot_signature=snapshot_signature,
+            supports_image_input=(
+                provider_image_capability
+                if supports_image_input is _IMAGE_CAPABILITY_UNSET
+                else supports_image_input
+            ),
        )

    def with_generation_overrides(
@@ -94,6 +110,7 @@ def runtime_from_provider_snapshot(
            context_window_tokens=snapshot.context_window_tokens,
            model_preset=snapshot.model_preset,
            snapshot_signature=snapshot.signature,
+            supports_image_input=snapshot.supports_image_input,
        )
    return LLMRuntime.capture(
        snapshot.provider,
@@ -101,4 +118,5 @@ def runtime_from_provider_snapshot(
        context_window_tokens=snapshot.context_window_tokens,
        model_preset=snapshot.model_preset,
        snapshot_signature=snapshot.signature,
+        supports_image_input=snapshot.supports_image_input,
    )
@@ -1,4 +1,5 @@
 """Shared WebUI metadata keys."""

 WEBUI_TURN_METADATA_KEY = "webui_turn_id"
+WEBSOCKET_TURN_OWNER_METADATA_KEY = "_websocket_turn_owner"
 WEBUI_MESSAGE_SOURCE_METADATA_KEY = "_webui_message_source"
@@ -54,7 +54,11 @@ def _reconcile_index(session_manager: SessionManager) -> tuple[list[dict[str, An
        for row in existing_rows or []
        if isinstance(row.get("file"), str)
    }
-    paths = sorted(session_manager.sessions_dir.glob("*.jsonl"))
+    paths = sorted(
+        path
+        for path in session_manager.sessions_dir.glob("*.jsonl")
+        if SessionManager._session_key_from_path(path) is not None
+    )
    rows: list[dict[str, Any]] = []
    changed = existing_rows is None

@@ -268,8 +272,9 @@ def _indexed_row_for_session(session: Session, path: Path) -> dict[str, Any]:


 def _scan_session_row(session_manager: SessionManager, path: Path) -> dict[str, Any] | None:
-    storage_key = SessionManager._decode_storage_key(path.stem)
-    fallback_key = storage_key or path.stem.replace("_", ":", 1)
+    storage_key = SessionManager._session_key_from_path(path)
+    if storage_key is None:
+        return None
    try:
        with open(path, encoding="utf-8") as f:
            first_line = f.readline().strip()
@@ -320,7 +325,7 @@ def _scan_session_row(session_manager: SessionManager, path: Path) -> dict[str,
                fallback_time = datetime.fromtimestamp(signature["mtime_ns"] / 1e9).isoformat()
                created_at_s = created_at_s or fallback_time
                updated_at_s = updated_at_s or fallback_time
-            key = data.get("key") or fallback_key
+            key = data.get("key") or storage_key
            activity_signature = _webui_activity_signature(key)
            activity_updated_at = _webui_activity_updated_at(activity_signature)
            return {
@@ -340,7 +345,7 @@ def _scan_session_row(session_manager: SessionManager, path: Path) -> dict[str,
                **activity_signature,
            }
    except Exception:
-        repaired = session_manager._repair(fallback_key)
+        repaired = session_manager._repair(storage_key)
        if repaired is None:
            return None
        return _indexed_row_for_session(repaired, path)
@@ -857,6 +857,13 @@ def _parse_bool(value: str, field: str) -> bool:
    return normalized in {"1", "true", "yes"}


+def _parse_image_input_support(value: str | None) -> bool | None:
+    normalized = (value or "").strip().lower()
+    if normalized in {"", "auto"}:
+        return None
+    return _parse_bool(normalized, "supports_image_input")
+
+
 def _parse_context_window_tokens(value: str | None) -> int | None:
    if value is None:
        return None
@@ -945,28 +952,10 @@ def _provider_display_name_exists(
    return False


-def _unique_model_configuration_name(config: Any, label: str) -> str:
-    """Return a stable, unused preset name for a migrated model configuration."""
-    try:
-        base = _model_configuration_slug(label)
-    except WebUISettingsError:
-        base = "model"
-    candidate = base
-    suffix = 2
-    while candidate in config.model_presets:
-        candidate = f"{base}-{suffix}"
-        suffix += 1
-    return candidate
-
-
-def _model_configuration_label(model: str) -> str:
-    return model.rsplit("/", 1)[-1] or model
-
-
 def _model_call_order_state(config: Any) -> tuple[list[str], bool]:
    defaults = config.agents.defaults
    primary = defaults.model_preset
-    if not primary or primary == "default" or primary not in config.model_presets:
+    if primary not in config.model_presets:
        return [], False
    order = [primary]
    for fallback in defaults.fallback_models:
@@ -1088,7 +1077,7 @@ def settings_payload(
 ) -> dict[str, Any]:
    config = load_config()
    defaults = config.agents.defaults
-    active_preset_name = defaults.model_preset or "default"
+    active_preset_name = defaults.model_preset
    effective_preset = config.resolve_preset()

    provider_name = (
@@ -1132,32 +1121,7 @@ def settings_payload(
        ),
        None,
    )
-    model_presets = [
-        {
-            "name": "default",
-            "label": "Default",
-            "active": active_preset_name == "default",
-            "is_default": True,
-            "model": defaults.model,
-            "provider": defaults.provider,
-            "resolved_provider": config.get_provider_name(
-                defaults.model,
-                preset=config.resolve_default_preset(),
-            ),
-            "max_tokens": defaults.max_tokens,
-            "context_window_tokens": defaults.context_window_tokens,
-            "temperature": defaults.temperature,
-            "reasoning_effort": defaults.reasoning_effort,
-            "reasoning_effort_values": _reasoning_effort_values_for(
-                config.get_provider_name(
-                    defaults.model,
-                    preset=config.resolve_default_preset(),
-                )
-                or defaults.provider,
-                defaults.model,
-            ),
-        }
-    ]
+    model_presets = []
    for name, preset in config.model_presets.items():
        resolved_preset_provider = (
            config.get_provider_name(
@@ -1171,7 +1135,7 @@ def settings_payload(
                "name": name,
                "label": preset.label or name,
                "active": active_preset_name == name,
-                "is_default": False,
+                "is_default": name == "default",
                "model": preset.model,
                "provider": preset.provider,
                "resolved_provider": resolved_preset_provider,
@@ -1179,6 +1143,7 @@ def settings_payload(
                "context_window_tokens": preset.context_window_tokens,
                "temperature": preset.temperature,
                "reasoning_effort": preset.reasoning_effort,
+                "supports_image_input": preset.supports_image_input,
                "reasoning_effort_values": _reasoning_effort_values_for(
                    resolved_preset_provider, preset.model
                ),
@@ -1320,13 +1285,14 @@ def settings_usage_payload() -> dict[str, Any]:
 def update_agent_settings(query: QueryParams) -> dict[str, Any]:
    config = load_config()
    defaults = config.agents.defaults
+    default_preset = config.resolve_default_preset()
    changed = False
    restart_required = False

    if "model_preset" in query or "modelPreset" in query:
        preset = (_query_first_alias(query, "model_preset", "modelPreset") or "").strip()
-        preset_value = None if not preset or preset == "default" else preset
-        if preset_value is not None and preset_value not in config.model_presets:
+        preset_value = preset or "default"
+        if preset_value not in config.model_presets:
            raise WebUISettingsError("unknown model preset")
        if defaults.model_preset != preset_value:
            defaults.model_preset = preset_value
@@ -1337,8 +1303,8 @@ def update_agent_settings(query: QueryParams) -> dict[str, Any]:
        model = model.strip()
        if not model:
            raise WebUISettingsError("model is required")
-        if defaults.model != model:
-            defaults.model = model
+        if default_preset.model != model:
+            default_preset.model = model
            changed = True

    provider = _query_first(query, "provider")
@@ -1347,8 +1313,8 @@ def update_agent_settings(query: QueryParams) -> dict[str, Any]:
        if not provider:
            raise WebUISettingsError("provider is required")
        _validate_configured_provider(config, provider)
-        if defaults.provider != provider:
-            defaults.provider = provider
+        if default_preset.provider != provider:
+            default_preset.provider = provider
            changed = True

    context_window_tokens = _parse_context_window_tokens(
@@ -1356,9 +1322,9 @@ def update_agent_settings(query: QueryParams) -> dict[str, Any]:
    )
    if (
        context_window_tokens is not None
-        and defaults.context_window_tokens != context_window_tokens
+        and default_preset.context_window_tokens != context_window_tokens
    ):
-        defaults.context_window_tokens = context_window_tokens
+        default_preset.context_window_tokens = context_window_tokens
        changed = True

    timezone = _query_first(query, "timezone")
@@ -1449,6 +1415,9 @@ def create_model_configuration(query: QueryParams) -> dict[str, Any]:
        reasoning_effort = (
            _query_first_alias(query, "reasoning_effort", "reasoningEffort") or ""
        ).strip() or None
+    supports_image_input = _parse_image_input_support(
+        _query_first_alias(query, "supports_image_input", "supportsImageInput")
+    )
    config.model_presets[name] = ModelPresetConfig(
        label=label,
        model=model,
@@ -1461,6 +1430,7 @@ def create_model_configuration(query: QueryParams) -> dict[str, Any]:
        ),
        temperature=temperature if temperature is not None else base.temperature,
        reasoning_effort=reasoning_effort,
+        supports_image_input=supports_image_input,
    )
    save_config(config)
    payload = settings_payload()
@@ -1470,7 +1440,7 @@ def create_model_configuration(query: QueryParams) -> dict[str, Any]:

 def update_model_configuration(query: QueryParams) -> dict[str, Any]:
    name = (_query_first(query, "name") or "").strip()
-    if not name or name == "default":
+    if not name:
        raise WebUISettingsError("model configuration is required")

    config = load_config()
@@ -1539,6 +1509,14 @@ def update_model_configuration(query: QueryParams) -> dict[str, Any]:
            preset.reasoning_effort = reasoning_effort
            changed = True

+    if "supports_image_input" in query or "supportsImageInput" in query:
+        supports_image_input = _parse_image_input_support(
+            _query_first_alias(query, "supports_image_input", "supportsImageInput")
+        )
+        if preset.supports_image_input is not supports_image_input:
+            preset.supports_image_input = supports_image_input
+            changed = True
+
    if changed:
        save_config(config)
    return settings_payload()
@@ -1584,68 +1562,16 @@ def update_model_call_order(query: QueryParams) -> dict[str, Any]:


 def migrate_model_configurations(_query: QueryParams | None = None) -> dict[str, Any]:
-    """Materialize legacy primary/inline model settings as named presets."""
-    config = load_config()
-    defaults = config.agents.defaults
-    primary = config.resolve_preset()
-    created: list[str] = []
-
-    if not defaults.model_preset or defaults.model_preset == "default":
-        label = _model_configuration_label(primary.model)
-        name = _unique_model_configuration_name(config, label)
-        config.model_presets[name] = ModelPresetConfig(
-            label=label,
-            model=primary.model,
-            provider=primary.provider,
-            max_tokens=primary.max_tokens,
-            context_window_tokens=primary.context_window_tokens,
-            temperature=primary.temperature,
-            reasoning_effort=primary.reasoning_effort,
-        )
-        defaults.model_preset = name
-        created.append(name)
-
-    fallback_models: list[str] = []
-    for fallback in defaults.fallback_models:
-        if isinstance(fallback, str):
-            fallback_models.append(fallback)
-            continue
-        label = _model_configuration_label(fallback.model)
-        name = _unique_model_configuration_name(config, label)
-        config.model_presets[name] = ModelPresetConfig(
-            label=label,
-            model=fallback.model,
-            provider=fallback.provider,
-            max_tokens=(
-                fallback.max_tokens
-                if fallback.max_tokens is not None
-                else primary.max_tokens
-            ),
-            context_window_tokens=(
-                fallback.context_window_tokens
-                if fallback.context_window_tokens is not None
-                else primary.context_window_tokens
-            ),
-            temperature=(
-                fallback.temperature
-                if fallback.temperature is not None
-                else primary.temperature
-            ),
-            reasoning_effort=fallback.reasoning_effort,
-        )
-        fallback_models.append(name)
-        created.append(name)
-
-    if created:
-        defaults.fallback_models = fallback_models
-        save_config(config)
+    """Compatibility endpoint; loading config now performs this migration."""
    return settings_payload()


 def delete_model_configuration(query: QueryParams) -> dict[str, Any]:
    name = (_query_first(query, "name") or "").strip()
-    if not name or name == "default":
+    if not name:
        raise WebUISettingsError("model configuration is required")
+    if name == "default":
+        raise WebUISettingsError("default model configuration cannot be deleted", status=409)

    config = load_config()
    if name not in config.model_presets:
@@ -41,7 +41,6 @@ def default_webui_sidebar_state() -> dict[str, Any]:
        "project_name_overrides": {},
        "tags_by_key": {},
        "collapsed_groups": {},
-        "activity_seen_at_by_key": {},
        "view": {
            "density": "comfortable",
            "show_previews": False,
@@ -88,19 +87,6 @@ def _clean_bool_map(value: Any) -> dict[str, bool]:
    return out


-def _clean_activity_seen_at_by_key(value: Any) -> dict[str, str]:
-    if not isinstance(value, dict):
-        return {}
-    out: dict[str, str] = {}
-    for key, raw_timestamp in list(value.items())[:_MAX_MAP_ITEMS]:
-        cleaned_key = _clean_string(key)
-        cleaned_timestamp = _clean_string(raw_timestamp, max_len=64)
-        if cleaned_key is None or cleaned_timestamp is None:
-            continue
-        out[cleaned_key] = cleaned_timestamp
-    return out
-
-
 def _clean_title_overrides(value: Any) -> dict[str, str]:
    if not isinstance(value, dict):
        return {}
@@ -156,9 +142,6 @@ def normalize_webui_sidebar_state(raw: Any) -> dict[str, Any]:
    )
    state["tags_by_key"] = _clean_tags_by_key(raw.get("tags_by_key"))
    state["collapsed_groups"] = _clean_bool_map(raw.get("collapsed_groups"))
-    state["activity_seen_at_by_key"] = _clean_activity_seen_at_by_key(
-        raw.get("activity_seen_at_by_key")
-    )
    state["view"] = _clean_view(raw.get("view"))
    updated_at = raw.get("updated_at")
    state["updated_at"] = updated_at if isinstance(updated_at, str) else None
@@ -25,6 +25,7 @@ from nanobot.webui.metadata import WEBUI_MESSAGE_SOURCE_METADATA_KEY, WEBUI_TURN

 WEBUI_TRANSCRIPT_SCHEMA_VERSION = 3
 WEBUI_FORK_MARKER_EVENT = "fork_marker"
+WEBUI_TRANSCRIPT_INCOMPLETE_KEY = "transcript_incomplete"
 _MAX_TRANSCRIPT_FILE_BYTES = 8 * 1024 * 1024
 _TARGET_ACTIVE_TRANSCRIPT_BYTES = _MAX_TRANSCRIPT_FILE_BYTES // 2
 _TRANSCRIPT_SEGMENT_MANIFEST_VERSION = 2
@@ -151,6 +152,12 @@ class _TranscriptChunkRef(NamedTuple):
    user_count: int


+class _SessionBackfillTurn(NamedTuple):
+    user_event: dict[str, Any]
+    assistant_signature: tuple[str, ...]
+    assistant_records: tuple[dict[str, Any], ...]
+
+
 def _record_json_line(record: dict[str, Any]) -> str:
    return json.dumps(record, ensure_ascii=False, separators=(",", ":"))

@@ -665,7 +672,7 @@ class WebUITranscriptRecorder:
        phase: str | None = None,
        include_source: bool = False,
        transcript_overrides: dict[str, Any] | None = None,
-    ) -> None:
+    ) -> bool:
        self.prepare_event(
            chat_id,
            event,
@@ -676,7 +683,7 @@ class WebUITranscriptRecorder:
        record = dict(event)
        if transcript_overrides:
            record.update(transcript_overrides)
-        self.append(chat_id, record)
+        return self.append(chat_id, record)

    def append_user_message(
        self,
@@ -687,9 +694,9 @@ class WebUITranscriptRecorder:
        media_paths: list[str] | None = None,
        cli_apps: list[dict[str, Any]] | None = None,
        mcp_presets: list[dict[str, Any]] | None = None,
-    ) -> None:
+    ) -> bool:
        if text.strip() == "/stop" and not media_paths:
-            return
+            return False
        payload = build_user_transcript_event(
            chat_id,
            text,
@@ -698,15 +705,17 @@ class WebUITranscriptRecorder:
            mcp_presets=mcp_presets,
        )
        if payload is None:
-            return
-        self.prepare_and_append(chat_id, payload, metadata=metadata, phase="user")
+            return False
+        return self.prepare_and_append(chat_id, payload, metadata=metadata, phase="user")

-    def append(self, chat_id: str, event: dict[str, Any]) -> None:
+    def append(self, chat_id: str, event: dict[str, Any]) -> bool:
        try:
            dup = json.loads(json.dumps(event, ensure_ascii=False))
            append_transcript_object(f"websocket:{chat_id}", dup)
        except (OSError, ValueError, TypeError) as e:
            self._log.warning("webui transcript append failed: {}", e)
+            return False
+        return True

    def _next_turn_seq(self, chat_id: str, turn_id: str) -> int:
        key = (chat_id, turn_id)
@@ -921,32 +930,69 @@ def _assistant_text_signature(value: Any) -> str:
    return value.strip() if isinstance(value, str) else ""


+def _session_assistant_event(
+    session_key: str,
+    message: dict[str, Any],
+) -> dict[str, Any] | None:
+    if message.get("role") != "assistant" or is_hidden_history_message(message):
+        return None
+    message = public_history_message(message)
+    content = message.get("content")
+    text = content if isinstance(content, str) else ""
+    media = message.get("media")
+    media_paths = [str(path) for path in media] if isinstance(media, list) else []
+    media_paths = [path for path in media_paths if path]
+    if not text.strip() and not media_paths:
+        return None
+    chat_id = session_key.split(":", 1)[1] if ":" in session_key else session_key
+    event: dict[str, Any] = {
+        "event": "message",
+        "chat_id": chat_id,
+        "text": text,
+    }
+    if media_paths:
+        event["media"] = media_paths
+    latency_ms = message.get("latency_ms")
+    if isinstance(latency_ms, int | float) and latency_ms >= 0:
+        event["latency_ms"] = int(latency_ms)
+    return event
+
+
 def _session_backfill_turns(
    session_key: str,
    session_messages: list[dict[str, Any]],
-) -> list[tuple[dict[str, Any], tuple[str, ...]]]:
-    turns: list[tuple[dict[str, Any], tuple[str, ...]]] = []
+) -> list[_SessionBackfillTurn]:
+    turns: list[_SessionBackfillTurn] = []
    current_user: dict[str, Any] | None = None
-    assistant_texts: list[str] = []
+    assistant_records: list[dict[str, Any]] = []

    def flush() -> None:
-        if current_user is None:
+        if current_user is None or not assistant_records:
            return
-        signature = tuple(text for text in assistant_texts if text)
-        if signature:
-            turns.append((current_user, signature))
+        signature = tuple(
+            text
+            for record in assistant_records
+            if (text := _assistant_text_signature(record.get("text")))
+        )
+        turns.append(
+            _SessionBackfillTurn(
+                current_user,
+                signature,
+                tuple(dict(record) for record in assistant_records),
+            )
+        )

    for message in session_messages:
        role = message.get("role")
        if role == "user":
            flush()
            current_user = _session_user_event(session_key, message)
-            assistant_texts = []
+            assistant_records = []
            continue
        if role == "assistant" and current_user is not None:
-            text = _assistant_text_signature(message.get("content"))
-            if text:
-                assistant_texts.append(text)
+            record = _session_assistant_event(session_key, message)
+            if record is not None:
+                assistant_records.append(record)
    flush()
    return turns

@@ -976,7 +1022,7 @@ def _transcript_turn_signature(records: list[dict[str, Any]]) -> tuple[str, ...]


 def _find_unique_session_turn(
-    session_turns: list[tuple[dict[str, Any], tuple[str, ...]]],
+    session_turns: list[_SessionBackfillTurn],
    signature: tuple[str, ...],
    start: int,
 ) -> int | None:
@@ -984,7 +1030,7 @@ def _find_unique_session_turn(
        return None
    found: int | None = None
    for index in range(start, len(session_turns)):
-        if session_turns[index][1] != signature:
+        if session_turns[index].assistant_signature != signature:
            continue
        if found is not None:
            return None
@@ -992,6 +1038,101 @@ def _find_unique_session_turn(
    return found


+def _user_recovery_signature(event: dict[str, Any]) -> str:
+    fields = {
+        key: event[key]
+        for key in ("text", "media_paths", "cli_apps", "mcp_presets")
+        if key in event
+    }
+    return json.dumps(fields, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _find_unique_session_turn_by_user(
+    session_turns: list[_SessionBackfillTurn],
+    user_event: dict[str, Any],
+) -> _SessionBackfillTurn | None:
+    signature = _user_recovery_signature(user_event)
+    matches = [
+        turn
+        for turn in session_turns
+        if _user_recovery_signature(turn.user_event) == signature
+    ]
+    return matches[0] if len(matches) == 1 else None
+
+
+def _is_recoverable_answer_record(record: dict[str, Any]) -> bool:
+    event = record.get("event")
+    if event in {"delta", "stream_end"}:
+        return True
+    return event == "message" and record.get("kind") not in {
+        "tool_hint",
+        "progress",
+        "reasoning",
+    }
+
+
+def recover_incomplete_turns_from_session(
+    lines: list[dict[str, Any]],
+    session_messages: list[dict[str, Any]] | None,
+    *,
+    session_key: str,
+) -> list[dict[str, Any]]:
+    """Recover marked transcript answers only when one durable session turn matches."""
+    if not lines or not session_messages:
+        return lines
+    session_turns = _session_backfill_turns(session_key, session_messages)
+    if not session_turns:
+        return lines
+
+    recovered: list[dict[str, Any]] = []
+    for turn in _split_transcript_turns(lines):
+        turn_end = turn[-1] if turn else None
+        if (
+            not isinstance(turn_end, dict)
+            or turn_end.get("event") != "turn_end"
+            or turn_end.get(WEBUI_TRANSCRIPT_INCOMPLETE_KEY) is not True
+        ):
+            recovered.extend(turn)
+            continue
+
+        user_events = [record for record in turn if record.get("event") == "user"]
+        if len(user_events) != 1:
+            recovered.extend(turn)
+            continue
+        session_turn = _find_unique_session_turn_by_user(session_turns, user_events[0])
+        if session_turn is None or not session_turn.assistant_records:
+            recovered.extend(turn)
+            continue
+
+        stable_end_ms = _valid_created_at_ms(turn_end.get("created_at_ms"))
+        turn_id = turn_end.get("turn_id")
+        answer_records: list[dict[str, Any]] = []
+        for index, source in enumerate(session_turn.assistant_records):
+            answer = dict(source)
+            if isinstance(turn_id, str) and turn_id:
+                answer["turn_id"] = turn_id
+                answer["turn_phase"] = "answer"
+            if stable_end_ms is not None:
+                answer["created_at_ms"] = max(
+                    0,
+                    stable_end_ms - len(session_turn.assistant_records) + index,
+                )
+            answer_records.append(answer)
+
+        # Session history is the durable source of the completed answer. Keep
+        # traces/reasoning/file edits, but replace any partial answer fragments.
+        recovered.extend(
+            record
+            for record in turn[:-1]
+            if not _is_recoverable_answer_record(record)
+        )
+        recovered.extend(answer_records)
+        completed_end = dict(turn_end)
+        completed_end.pop(WEBUI_TRANSCRIPT_INCOMPLETE_KEY, None)
+        recovered.append(completed_end)
+    return recovered
+
+
 def _with_backfilled_user(
    records: list[dict[str, Any]],
    user_event: dict[str, Any],
@@ -1972,8 +2113,36 @@ def fork_boundary_message_count(lines: list[dict[str, Any]]) -> int | None:
    return None


-def has_pending_tool_calls(lines: list[dict[str, Any]]) -> bool:
+def has_pending_tool_calls(
+    lines: list[dict[str, Any]],
+    *,
+    active_turn_started_at: float | None = None,
+    active_turn_id: str | None = None,
+    active_turn_transcript_persistence_failed: bool = False,
+) -> bool:
    """Return True when the selected transcript tail looks like an unfinished turn."""
+    # An older canonical turn can remain unsafe even after a later turn
+    # completes. Recovery removes this marker only after matching durable
+    # session history, so no later turn_end may hide it.
+    if any(
+        rec.get(WEBUI_TRANSCRIPT_INCOMPLETE_KEY) is True
+        for rec in lines
+    ):
+        return True
+    if active_turn_started_at is not None:
+        if active_turn_transcript_persistence_failed:
+            return True
+        if active_turn_id is None:
+            return True
+        for rec in reversed(lines):
+            transcript_turn_id = rec.get("turn_id")
+            if not isinstance(transcript_turn_id, str) or not transcript_turn_id:
+                continue
+            if transcript_turn_id != active_turn_id:
+                return True
+            return rec.get("event") != "turn_end"
+        return True
+
    for rec in reversed(lines):
        ev = rec.get("event")
        if ev == "turn_end":
@@ -1995,6 +2164,24 @@ def has_pending_tool_calls(lines: list[dict[str, Any]]) -> bool:
    return False


+def completed_turn_ids(lines: list[dict[str, Any]]) -> list[str]:
+    """Return stable identities for turns with an explicitly persisted completion."""
+    completed: list[str] = []
+    seen: set[str] = set()
+    for rec in lines:
+        if (
+            rec.get("event") != "turn_end"
+            or rec.get(WEBUI_TRANSCRIPT_INCOMPLETE_KEY) is True
+        ):
+            continue
+        turn_id = rec.get("turn_id")
+        if not isinstance(turn_id, str) or not turn_id or turn_id in seen:
+            continue
+        seen.add(turn_id)
+        completed.append(turn_id)
+    return completed
+
+
 def build_webui_thread_response(
    session_key: str,
    *,
@@ -2002,6 +2189,9 @@ def build_webui_thread_response(
    augment_assistant_media: Callable[[list[str]], list[dict[str, Any]]] | None = None,
    augment_assistant_text: Callable[[str], str] | None = None,
    session_messages: list[dict[str, Any]] | None = None,
+    active_turn_started_at: float | None = None,
+    active_turn_id: str | None = None,
+    active_turn_transcript_persistence_failed: bool = False,
    limit: int | None = None,
    direction: str | None = None,
    before: str | None = None,
@@ -2013,9 +2203,14 @@ def build_webui_thread_response(
        lines, page = _select_transcript_page(session_key, limit=limit, before=before)
    else:
        lines = read_transcript_lines(session_key)
-    if not lines:
+    if not lines and active_turn_started_at is None:
        return None
    lines = inject_missing_user_events_from_session(session_key, lines, session_messages)
+    lines = recover_incomplete_turns_from_session(
+        lines,
+        session_messages,
+        session_key=session_key,
+    )
    fork_boundary = fork_boundary_message_count(lines)
    msgs = replay_transcript_to_ui_messages(
        lines,
@@ -2027,7 +2222,16 @@ def build_webui_thread_response(
        "schemaVersion": WEBUI_TRANSCRIPT_SCHEMA_VERSION,
        "sessionKey": session_key,
        "messages": msgs,
-        "has_pending_tool_calls": has_pending_tool_calls(lines),
+        "completed_turn_ids": completed_turn_ids(lines),
+        "has_pending_tool_calls": has_pending_tool_calls(
+            lines,
+            active_turn_started_at=active_turn_started_at,
+            active_turn_id=active_turn_id,
+            active_turn_transcript_persistence_failed=(
+                active_turn_transcript_persistence_failed
+            ),
+        ),
+        "active_turn_id": active_turn_id,
    }
    if page is not None:
        page["loaded_message_count"] = len(msgs)
@@ -474,6 +474,18 @@ class GatewayHTTPHandler:
        if direction is not None and direction not in {"latest"}:
            return _http_error(400, "invalid direction")
        before = _query_first(query, "before")
+        from nanobot.session.webui_turns import (
+            websocket_turn_id,
+            websocket_turn_transcript_persistence_failed,
+            websocket_turn_wall_started_at,
+        )
+
+        chat_id = decoded_key.split(":", 1)[1]
+        active_turn_started_at = websocket_turn_wall_started_at(chat_id)
+        active_turn_id = websocket_turn_id(chat_id)
+        active_turn_transcript_persistence_failed = (
+            websocket_turn_transcript_persistence_failed(chat_id)
+        )
        data = build_webui_thread_response(
            decoded_key,
            augment_user_media=self.media.augment_transcript_media,
@@ -483,6 +495,11 @@ class GatewayHTTPHandler:
                workspace_path=scope.project_path,
            ),
            session_messages=session_messages,
+            active_turn_started_at=active_turn_started_at,
+            active_turn_id=active_turn_id,
+            active_turn_transcript_persistence_failed=(
+                active_turn_transcript_persistence_failed
+            ),
            limit=limit,
            direction=direction,
            before=before,
@@ -1,8 +1,14 @@
 {
  "agents": {
    "defaults": {
+      "modelPreset": "default"
+    }
+  },
+  "modelPresets": {
+    "default": {
      "model": "anthropic/claude-opus-4-8",
-      "provider": "auto"
+      "provider": "auto",
+      "supportsImageInput": null
    }
  },
  "providers": {
@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Any

 from nanobot.agent.runner import AgentRunSpec
-from nanobot.config.schema import AgentDefaults
+from nanobot.config.schema import ModelPresetConfig
 from nanobot.providers.base import GenerationSettings, LLMProvider
 from nanobot.utils.llm_runtime import LLMRuntime

@@ -21,7 +21,7 @@ def make_run_spec(provider: LLMProvider, **kwargs: Any) -> AgentRunSpec:
    model = kwargs.pop("model")
    context_window_tokens = kwargs.pop(
        "context_window_tokens",
-        AgentDefaults().context_window_tokens,
+        ModelPresetConfig(model=model).context_window_tokens,
    )
    provider_generation = getattr(provider, "generation", None)
    defaults = GenerationSettings()
@@ -0,0 +1,208 @@
+import asyncio
+import base64
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.agent.loop import AgentLoop, TurnContext, TurnKind
+from nanobot.agent.tools.filesystem import ReadFileTool
+from nanobot.bus.events import InboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.config.schema import ChannelsConfig
+from nanobot.providers.base import LLMResponse
+from nanobot.utils.document import reference_non_image_attachments
+
+
+def _make_loop(
+    workspace: Path,
+    channels_config: ChannelsConfig | None = None,
+) -> AgentLoop:
+    provider = MagicMock()
+    provider.get_default_model.return_value = "test-model"
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(content="ok"))
+    return AgentLoop(
+        bus=MessageBus(),
+        provider=provider,
+        workspace=workspace,
+        model="test-model",
+        channels_config=channels_config,
+    )
+
+
+def _turn_context(loop: AgentLoop, msg: InboundMessage) -> TurnContext:
+    return TurnContext(
+        msg=msg,
+        session_key=f"{msg.channel}:{msg.chat_id}",
+        turn_id="turn-1",
+        runtime=loop.llm_runtime(),
+        kind=TurnKind.USER,
+        delivery=loop.turn_delivery_factory.create(msg, f"{msg.channel}:{msg.chat_id}"),
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("extract_document_text", [True, False])
+async def test_document_attachment_is_referenced_and_read_on_demand(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    extract_document_text: bool,
+) -> None:
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    media_dir = tmp_path / "media"
+    media_dir.mkdir()
+    csv_path = media_dir / "report.csv"
+    csv_path.write_text("name,value\nnanobot,1", encoding="utf-8")
+    monkeypatch.setattr("nanobot.agent.tools.path_utils.get_media_dir", lambda: media_dir)
+
+    loop = _make_loop(
+        workspace,
+        ChannelsConfig(extract_document_text=extract_document_text),
+    )
+    msg = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id="c",
+        content="import this report",
+        media=[str(csv_path)],
+    )
+    ctx = _turn_context(loop, msg)
+
+    await loop._restore_turn(ctx)
+
+    assert ctx.msg.content == f"import this report\n\n[Attachment: {csv_path}]"
+    assert "name,value" not in ctx.msg.content
+    assert ctx.msg.media == []
+
+    read_tool = ReadFileTool(workspace=workspace, allowed_dir=workspace)
+    result = await read_tool.execute(path=str(csv_path))
+
+    assert "1| name,value" in result
+    assert "2| nanobot,1" in result
+
+
+@pytest.mark.asyncio
+async def test_document_reference_survives_session_reload(tmp_path: Path) -> None:
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    doc_path = tmp_path / "report.csv"
+    doc_path.write_text("name,value", encoding="utf-8")
+
+    loop = _make_loop(workspace)
+    loop._run_agent_loop = AsyncMock(side_effect=RuntimeError("interrupt"))  # type: ignore[method-assign]
+    msg = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id="persisted-attachment",
+        content="review this",
+        media=[str(doc_path)],
+    )
+
+    with pytest.raises(RuntimeError, match="interrupt"):
+        await loop._process_message(msg)
+
+    session_key = "websocket:persisted-attachment"
+    loop.sessions.invalidate(session_key)
+    persisted = loop.sessions.get_or_create(session_key)
+
+    assert [message["role"] for message in persisted.messages] == ["user"]
+    assert persisted.messages[0]["content"] == (
+        f"review this\n\n[Attachment: {doc_path.resolve()}]"
+    )
+    assert "media" not in persisted.messages[0]
+
+
+@pytest.mark.asyncio
+async def test_pending_document_attachment_keeps_body_out_of_prompt(
+    tmp_path: Path,
+) -> None:
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    doc_path = tmp_path / "followup.txt"
+    doc_path.write_text("Do not inject this file body", encoding="utf-8")
+    captured_messages: list[list[dict]] = []
+    call_count = 0
+
+    async def chat_with_retry(*, messages: list[dict], **kwargs: object) -> LLMResponse:
+        nonlocal call_count
+        call_count += 1
+        captured_messages.append([dict(message) for message in messages])
+        return LLMResponse(content=f"answer-{call_count}", tool_calls=[], usage={})
+
+    loop = _make_loop(workspace)
+    loop.provider.chat_with_retry = chat_with_retry
+    loop.tools.get_definitions = MagicMock(return_value=[])
+
+    pending_queue: asyncio.Queue[InboundMessage] = asyncio.Queue()
+    await pending_queue.put(
+        InboundMessage(
+            channel="cli",
+            sender_id="u",
+            chat_id="c",
+            content="check this",
+            media=[str(doc_path)],
+        )
+    )
+
+    final_content, _, _, _, had_injections = await loop._run_agent_loop(
+        [{"role": "user", "content": "hello"}],
+        runtime=loop.llm_runtime(),
+        channel="cli",
+        chat_id="c",
+        pending_queue=pending_queue,
+    )
+
+    assert final_content == "answer-2"
+    assert had_injections is True
+    injected_user_content = [
+        message["content"]
+        for message in captured_messages[-1]
+        if message.get("role") == "user" and isinstance(message.get("content"), str)
+    ][-1]
+    assert "check this" in injected_user_content
+    assert f"[Attachment: {doc_path}]" in injected_user_content
+    assert "Do not inject this file body" not in injected_user_content
+
+
+def test_attachment_references_still_preserve_images(tmp_path: Path) -> None:
+    image_path = tmp_path / "chart.png"
+    image_path.write_bytes(
+        base64.b64decode(
+            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+yF9kAAAAASUVORK5CYII="
+        )
+    )
+    doc_path = tmp_path / "report.txt"
+    doc_path.write_text("manual extraction target", encoding="utf-8")
+
+    content, media = reference_non_image_attachments(
+        "review these",
+        [str(image_path), str(doc_path)],
+    )
+
+    assert media == [str(image_path)]
+    assert f"[Attachment: {doc_path}]" in content
+    assert "manual extraction target" not in content
+
+
+def test_attachment_references_canonicalize_existing_relative_paths(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    image_path = tmp_path / "chart.png"
+    image_path.write_bytes(
+        base64.b64decode(
+            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+yF9kAAAAASUVORK5CYII="
+        )
+    )
+    doc_path = tmp_path / "report.csv"
+    doc_path.write_text("name,value", encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+
+    content, media = reference_non_image_attachments(
+        "review these",
+        [image_path.name, doc_path.name],
+    )
+
+    assert media == [str(image_path.resolve())]
+    assert f"[Attachment: {doc_path.resolve()}]" in content
@@ -272,7 +272,13 @@ class TestAgentLoopTTLParam:
        kwargs = session.get_history.call_args.kwargs
        assert isinstance(kwargs.get("max_tokens"), int)
        assert kwargs["max_tokens"] > 0
-        assert set(kwargs) == {"max_messages", "max_tokens", "extend_to_user"}
+        assert set(kwargs) == {
+            "max_messages",
+            "max_tokens",
+            "extend_to_user",
+            "include_media",
+        }
+        assert kwargs["include_media"] is True

    @pytest.mark.asyncio
    async def test_session_file_cap_archives_and_trims_old_messages(self, tmp_path):
@@ -170,6 +170,34 @@ class TestConsolidatorSummarize:
        entries = store.read_unprocessed_history(since_cursor=0)
        assert entries[0]["session_key"] == "telegram:chat-1"

+    async def test_summarize_preserves_media_manifest_deterministically(
+        self,
+        consolidator,
+        mock_provider,
+        store,
+        runtime,
+    ):
+        mock_provider.chat_with_retry.return_value = MagicMock(
+            content="User shared a screenshot.",
+            finish_reason="stop",
+        )
+        messages = [{
+            "role": "user",
+            "content": "",
+            "media": ["/media/screenshot.png"],
+        }]
+
+        result = await consolidator.archive(messages, runtime=runtime)
+
+        assert result == (
+            "Archived attachments:\n- [image: /media/screenshot.png]\n\n"
+            "User shared a screenshot."
+        )
+        prompt = mock_provider.chat_with_retry.call_args.kwargs["messages"][1]["content"]
+        assert "[image: /media/screenshot.png]" in prompt
+        entries = store.read_unprocessed_history(since_cursor=0)
+        assert "[image: /media/screenshot.png]" in entries[0]["content"]
+
    async def test_summarize_raw_dumps_on_llm_failure(
        self, consolidator, mock_provider, store, runtime
    ):
@@ -992,6 +1020,18 @@ class TestRawArchiveTruncation:
        assert len(entries) == 1
        assert "hello" in entries[0]["content"]

+    def test_raw_archive_preserves_late_media_path_before_truncation(self, store):
+        messages = [
+            {"role": "user", "content": "x" * 20_000},
+            {"role": "user", "content": "", "media": ["/media/late.png"]},
+        ]
+
+        store.raw_archive(messages)
+
+        entry = store.read_unprocessed_history(since_cursor=0)[0]["content"]
+        assert "Archived attachments:" in entry
+        assert "[image: /media/late.png]" in entry
+
    def test_raw_archive_excludes_model_only_runtime_context(self, store):
        content, marker = append_runtime_context(
            "ship the feature",
@@ -5,7 +5,11 @@ from pathlib import Path
 import pytest

 from nanobot.agent.context import ContextBuilder
-from nanobot.runtime_context import RuntimeContextBlock
+from nanobot.runtime_context import (
+    RUNTIME_CONTEXT_HISTORY_META,
+    RuntimeContextBlock,
+    append_runtime_context,
+)

 # ---------------------------------------------------------------------------
 # Helpers
@@ -244,38 +248,40 @@ class TestBundledToolContract:


 # ---------------------------------------------------------------------------
-# _build_user_content
+# build_user_content
 # ---------------------------------------------------------------------------


 class TestBuildUserContent:
    def test_no_media_returns_string(self, tmp_path):
        builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", None)
+        result = builder.build_user_content("hello", None)
        assert result == "hello"

    def test_empty_media_returns_string(self, tmp_path):
        builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", [])
+        result = builder.build_user_content("hello", [])
        assert result == "hello"

-    def test_nonexistent_media_file_returns_string(self, tmp_path):
+    def test_nonexistent_media_file_returns_explicit_placeholder(self, tmp_path):
        builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", ["/nonexistent/image.png"])
-        assert result == "hello"
+        result = builder.build_user_content("hello", ["/nonexistent/image.png"])
+        assert isinstance(result, list)
+        assert "unavailable" in result[0]["text"].lower()
+        assert result[1] == {"type": "text", "text": "hello"}

    def test_non_image_file_returns_string(self, tmp_path):
        txt = tmp_path / "doc.txt"
        txt.write_text("not an image", encoding="utf-8")
        builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", [str(txt)])
+        result = builder.build_user_content("hello", [str(txt)])
        assert result == "hello"

    def test_valid_image_returns_list(self, tmp_path):
        png = tmp_path / "test.png"
        png.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
        builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", [str(png)])
+        result = builder.build_user_content("hello", [str(png)])
        assert isinstance(result, list)
        assert len(result) == 2
        assert result[0]["type"] == "image_url"
@@ -287,7 +293,7 @@ class TestBuildUserContent:
        png = tmp_path / "test.png"
        png.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
        builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", [str(png)])
+        result = builder.build_user_content("hello", [str(png)])
        assert "_meta" in result[0]
        assert "path" in result[0]["_meta"]

@@ -353,6 +359,14 @@ class TestBuildSystemPrompt:


 class TestBuildMessages:
+    def test_optional_arguments_are_keyword_only(self, tmp_path):
+        builder = _builder(tmp_path)
+
+        with pytest.raises(TypeError):
+            builder.build_system_prompt(["legacy-skill"])
+        with pytest.raises(TypeError):
+            builder.build_messages([], "hello", ["legacy-skill"])
+
    def test_basic_empty_history(self, tmp_path):
        builder = _builder(tmp_path)
        messages = builder.build_messages([], "hello")
@@ -361,9 +375,28 @@ class TestBuildMessages:
        assert messages[1]["role"] == "user"
        assert "hello" in str(messages[1]["content"])

+    def test_public_builder_preserves_assistant_role_compatibility(self, tmp_path):
+        from nanobot.agent import ContextBuilder as PublicContextBuilder
+
+        builder = PublicContextBuilder(tmp_path)
+        messages = builder.build_messages(
+            history=[{"role": "assistant", "content": "previous result"}],
+            current_message="subagent result",
+            current_role="assistant",
+            runtime_context_blocks=[
+                RuntimeContextBlock(source="test", content="user-only runtime context"),
+            ],
+        )
+
+        assert len(messages) == 2
+        assert messages[-1]["role"] == "assistant"
+        assert messages[-1]["content"] == "previous result\n\nsubagent result"
+        assert "user-only runtime context" not in messages[-1]["content"]
+        assert "_meta" not in messages[-1]
+
    def test_runtime_context_is_not_injected_by_default(self, tmp_path):
        builder = _builder(tmp_path)
-        messages = builder.build_messages([], "hello", channel="cli", chat_id="direct")
+        messages = builder.build_messages([], "hello", channel="cli")
        user_msg = str(messages[-1]["content"])
        assert user_msg == "hello"

@@ -411,3 +444,55 @@ class TestBuildMessages:
        user_msg = messages[-1]["content"]
        assert isinstance(user_msg, list)
        assert any(b.get("type") == "image_url" for b in user_msg)
+
+    def test_persisted_media_rehydrates_to_identical_image_content(self, tmp_path):
+        png = tmp_path / "stable.png"
+        png.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
+        builder = _builder(tmp_path)
+        first_content = builder.build_user_content("describe", [str(png)])
+        history = [
+            {
+                "role": "user",
+                "content": "describe",
+                "_media_paths": [str(png)],
+            },
+            {"role": "assistant", "content": "done"},
+        ]
+
+        messages = builder.build_messages(history, "next")
+
+        assert messages[1]["content"] == first_content
+        assert "_media_paths" not in messages[1]
+
+    def test_persisted_media_and_runtime_context_rehydrate_identically(self, tmp_path):
+        png = tmp_path / "stable-context.png"
+        png.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
+        builder = _builder(tmp_path)
+        blocks = [
+            RuntimeContextBlock(
+                source="cli_apps",
+                content="CLI App Attachment: @drawio (tool=run_cli_app).",
+            )
+        ]
+        first_content = builder.build_messages(
+            [],
+            "describe",
+            media=[str(png)],
+            runtime_context_blocks=blocks,
+        )[-1]["content"]
+        persisted_content, marker = append_runtime_context("describe", blocks)
+        history = [
+            {
+                "role": "user",
+                "content": persisted_content,
+                "_media_paths": [str(png)],
+                RUNTIME_CONTEXT_HISTORY_META: marker,
+            },
+            {"role": "assistant", "content": "done"},
+        ]
+
+        messages = builder.build_messages(history, "next")
+
+        assert messages[1]["content"] == first_content
+        assert "_media_paths" not in messages[1]
+        assert RUNTIME_CONTEXT_HISTORY_META not in messages[1]
@@ -70,7 +70,6 @@ def test_provider_context_appended_after_user_content(tmp_path) -> None:
        history=[],
        current_message="hello world",
        channel="cli",
-        chat_id="direct",
        runtime_context_blocks=[
            RuntimeContextBlock(source="test", content="provider context"),
        ],
@@ -322,7 +321,7 @@ def test_build_messages_passes_channel_to_system_prompt(tmp_path) -> None:

    messages = builder.build_messages(
        history=[], current_message="hi",
-        channel="telegram", chat_id="123",
+        channel="telegram",
    )
    system = messages[0]["content"]
    assert "Format Hint" in system
@@ -341,22 +340,6 @@ def test_system_prompt_keeps_message_tool_out_of_current_chat_replies(tmp_path)
    assert "Wait for the tool results, then answer once" in prompt


-def test_subagent_result_does_not_create_consecutive_assistant_messages(tmp_path) -> None:
-    workspace = _make_workspace(tmp_path)
-    builder = ContextBuilder(workspace)
-
-    messages = builder.build_messages(
-        history=[{"role": "assistant", "content": "previous result"}],
-        current_message="subagent result",
-        channel="cli",
-        chat_id="direct",
-        current_role="assistant",
-    )
-
-    for left, right in zip(messages, messages[1:]):
-        assert not (left.get("role") == right.get("role") == "assistant")
-
-
 def test_memory_skill_is_lazy_loaded_from_skills_index(tmp_path) -> None:
    """Memory search guidance should be discoverable without loading its full body."""
    workspace = _make_workspace(tmp_path)
@@ -400,7 +383,7 @@ def test_template_memory_md_is_skipped(tmp_path) -> None:
    assert "This file is automatically updated by nanobot" not in prompt


-def test_customized_memory_md_is_injected(tmp_path) -> None:
+def test_customized_memory_md_is_injected(tmp_path, monkeypatch) -> None:
    """A Dream-populated MEMORY.md should be injected normally."""
    workspace = _make_workspace(tmp_path)
    from nanobot.utils.helpers import sync_workspace_templates
@@ -411,7 +394,17 @@ def test_customized_memory_md_is_injected(tmp_path) -> None:
    )

    builder = ContextBuilder(workspace)
+    read_memory = builder.memory.read_memory
+    calls = 0
+
+    def tracked_read_memory() -> str:
+        nonlocal calls
+        calls += 1
+        return read_memory()
+
+    monkeypatch.setattr(builder.memory, "read_memory", tracked_read_memory)
    prompt = builder.build_system_prompt()

    assert "# Memory\n\n## Long-term Memory" in prompt
    assert "User prefers dark mode" in prompt
+    assert calls == 1
@@ -1,178 +0,0 @@
-import asyncio
-import base64
-from pathlib import Path
-from unittest.mock import AsyncMock, MagicMock
-
-import pytest
-
-from nanobot.agent.loop import AgentLoop, TurnContext, TurnKind, TurnState
-from nanobot.bus.events import InboundMessage
-from nanobot.bus.queue import MessageBus
-from nanobot.config.schema import ChannelsConfig
-from nanobot.providers.base import LLMResponse
-from nanobot.utils.document import reference_non_image_attachments
-
-
-def _make_loop(tmp_path: Path, channels_config: ChannelsConfig | None = None) -> AgentLoop:
-    provider = MagicMock()
-    provider.get_default_model.return_value = "test-model"
-    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(content="ok"))
-    return AgentLoop(
-        bus=MessageBus(),
-        provider=provider,
-        workspace=tmp_path,
-        model="test-model",
-        channels_config=channels_config,
-    )
-
-
-@pytest.mark.asyncio
-async def test_state_restore_extracts_documents_by_default(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    loop = _make_loop(tmp_path)
-    doc_path = tmp_path / "report.txt"
-    doc_path.write_text("Quarterly revenue is $5M", encoding="utf-8")
-    calls: list[tuple[str, list[str]]] = []
-
-    def fake_extract_documents(content: str, media: list[str]) -> tuple[str, list[str]]:
-        calls.append((content, media))
-        return f"{content}\n\n[File: report.txt]\nQuarterly revenue is $5M", []
-
-    monkeypatch.setattr("nanobot.agent.loop.extract_documents", fake_extract_documents)
-
-    msg = InboundMessage(
-        channel="cli",
-        sender_id="u",
-        chat_id="c",
-        content="summarize",
-        media=[str(doc_path)],
-    )
-    ctx = TurnContext(
-        msg=msg,
-        session_key="cli:c",
-        state=TurnState.RESTORE,
-        turn_id="turn-1",
-        runtime=loop.llm_runtime(),
-        kind=TurnKind.USER,
-        delivery=loop.turn_delivery_factory.create(msg, "cli:c"),
-    )
-
-    assert await loop._state_restore(ctx) == "ok"
-
-    assert calls == [("summarize", [str(doc_path)])]
-    assert "Quarterly revenue" in ctx.msg.content
-    assert ctx.msg.media == []
-
-
-@pytest.mark.asyncio
-async def test_state_restore_references_documents_when_extraction_disabled(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    loop = _make_loop(tmp_path, ChannelsConfig(extract_document_text=False))
-    doc_path = tmp_path / "report.txt"
-    doc_path.write_text("Quarterly revenue is $5M", encoding="utf-8")
-
-    def fail_extract_documents(content: str, media: list[str]) -> tuple[str, list[str]]:
-        raise AssertionError("document extraction should be disabled")
-
-    monkeypatch.setattr("nanobot.agent.loop.extract_documents", fail_extract_documents)
-
-    msg = InboundMessage(
-        channel="cli",
-        sender_id="u",
-        chat_id="c",
-        content="summarize",
-        media=[str(doc_path)],
-    )
-    ctx = TurnContext(
-        msg=msg,
-        session_key="cli:c",
-        state=TurnState.RESTORE,
-        turn_id="turn-1",
-        runtime=loop.llm_runtime(),
-        kind=TurnKind.USER,
-        delivery=loop.turn_delivery_factory.create(msg, "cli:c"),
-    )
-
-    assert await loop._state_restore(ctx) == "ok"
-
-    assert "Quarterly revenue" not in ctx.msg.content
-    assert f"[Attachment: {doc_path}]" in ctx.msg.content
-    assert ctx.msg.media == []
-
-
-@pytest.mark.asyncio
-async def test_pending_followup_references_documents_when_extraction_disabled(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    doc_path = tmp_path / "followup.txt"
-    doc_path.write_text("Do not inject this file body", encoding="utf-8")
-    captured_messages: list[list[dict]] = []
-    call_count = {"n": 0}
-
-    async def chat_with_retry(*, messages: list[dict], **kwargs: object) -> LLMResponse:
-        call_count["n"] += 1
-        captured_messages.append([dict(message) for message in messages])
-        return LLMResponse(content=f"answer-{call_count['n']}", tool_calls=[], usage={})
-
-    loop = _make_loop(tmp_path, ChannelsConfig(extract_document_text=False))
-    loop.provider.chat_with_retry = chat_with_retry
-    loop.tools.get_definitions = MagicMock(return_value=[])
-
-    def fail_extract_documents(content: str, media: list[str]) -> tuple[str, list[str]]:
-        raise AssertionError("document extraction should be disabled")
-
-    monkeypatch.setattr("nanobot.agent.loop.extract_documents", fail_extract_documents)
-
-    pending_queue: asyncio.Queue[InboundMessage] = asyncio.Queue()
-    await pending_queue.put(
-        InboundMessage(
-            channel="cli",
-            sender_id="u",
-            chat_id="c",
-            content="check this",
-            media=[str(doc_path)],
-        )
-    )
-
-    final_content, _, _, _, had_injections = await loop._run_agent_loop(
-        [{"role": "user", "content": "hello"}],
-        runtime=loop.llm_runtime(),
-        channel="cli",
-        chat_id="c",
-        pending_queue=pending_queue,
-    )
-
-    assert final_content == "answer-2"
-    assert had_injections is True
-    injected_user_content = [
-        message["content"]
-        for message in captured_messages[-1]
-        if message.get("role") == "user" and isinstance(message.get("content"), str)
-    ][-1]
-    assert "check this" in injected_user_content
-    assert f"[Attachment: {doc_path}]" in injected_user_content
-    assert "Do not inject this file body" not in injected_user_content
-
-
-def test_document_extraction_disabled_still_preserves_images(tmp_path: Path) -> None:
-    image_path = tmp_path / "chart.png"
-    image_path.write_bytes(
-        base64.b64decode(
-            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+yF9kAAAAASUVORK5CYII="
-        )
-    )
-    doc_path = tmp_path / "report.txt"
-    doc_path.write_text("manual extraction target", encoding="utf-8")
-
-    content, media = reference_non_image_attachments(
-        "review these",
-        [str(image_path), str(doc_path)],
-    )
-
-    assert media == [str(image_path)]
-    assert f"[Attachment: {doc_path}]" in content
@@ -3,6 +3,7 @@
 import pytest

 from nanobot.agent.memory import MemoryStore
+from nanobot.config.schema import ModelPresetConfig
 from nanobot.providers.base import LLMResponse
 from nanobot.security.workspace_access import (
    bind_workspace_scope,
@@ -126,15 +127,15 @@ class TestBuildDreamPrompt:
        prompt, _ = result
        assert "memory consolidation engine" in prompt

-    def test_truncates_long_entries(self, store):
+    def test_truncates_long_entries_at_1000_chars(self, store):
        long_content = "x" * 2000
        store.append_history(long_content)
        result = store.build_dream_prompt()
        assert result is not None
        prompt, _ = result
-        # The full 2000 chars should not appear — truncated to 500
        assert long_content not in prompt
-        assert "x" * 500 in prompt
+        assert "x" * 1000 in prompt
+        assert "x" * 1001 not in prompt

    def test_batches_oldest_unprocessed_entries_first(self, store):
        for i in range(25):
@@ -221,11 +222,20 @@ class TestDreamTools:
                "new_text": "Precise",
            },
        )
+        user_result = await tools.execute(
+            "write_file",
+            {
+                "path": "USER.md",
+                "content": "# User Profile\n\n- **Name**: Ada\n",
+            },
+        )

        assert "Patch applied" in memory_result
        assert "Successfully edited" in soul_result
+        assert "Successfully wrote" in user_result
        assert "Project Y active" in store.memory_file.read_text(encoding="utf-8")
        assert "Precise" in store.soul_file.read_text(encoding="utf-8")
+        assert "**Name**: Ada" in store.user_file.read_text(encoding="utf-8")

    @pytest.mark.asyncio
    async def test_dream_can_write_workspace_skills(self, store):
@@ -305,9 +315,17 @@ class TestDreamTools:
                "new_text": "2",
            },
        )
+        history_write_result = await tools.execute(
+            "write_file",
+            {
+                "path": "memory/history.jsonl",
+                "content": "after\n",
+            },
+        )

        assert "outside allowed directory" in history_result
        assert "outside allowed directory" in cursor_result
+        assert "outside allowed directory" in history_write_result
        assert store.history_file.read_text(encoding="utf-8") == "before\n"
        assert store._dream_cursor_file.read_text(encoding="utf-8") == "1"

@@ -330,11 +348,10 @@ class TestDreamTools:
            },
        )
        user_result = await tools.execute(
-            "edit_file",
+            "write_file",
            {
                "path": "USER.md/evil.txt",
-                "old_text": "",
-                "new_text": "owned",
+                "content": "owned",
            },
        )

@@ -385,6 +402,21 @@ class TestEphemeralDirect:

        return loop, store

+    def test_dream_runtime_uses_preset_without_changing_default(self, _make_loop):
+        loop, _ = _make_loop
+        loop.runtime_resolver._model_presets = {
+            "dream": ModelPresetConfig(model="dream-model"),
+        }
+        loop.dream_model_preset = "dream"
+
+        runtime = loop.dream_runtime()
+
+        assert runtime is not None
+        assert runtime.model == "dream-model"
+        assert runtime.model_preset == "dream"
+        assert loop.model == "test-model"
+        assert loop.model_preset is None
+
    async def test_ephemeral_skips_raw_archive(self, tmp_path, _make_loop):
        """When ephemeral=True, raw_archive must not be called."""
        from unittest.mock import patch
@@ -414,13 +446,13 @@ class TestEphemeralDirect:

        captured = {}

-        original_save = loop._state_save
+        original_save = loop._persist_turn

        async def patched_save(ctx):
            captured["ephemeral"] = ctx.ephemeral
            return await original_save(ctx)

-        with patch.object(loop, "_state_save", side_effect=patched_save):
+        with patch.object(loop, "_persist_turn", side_effect=patched_save):
            await loop.process_direct(
                "test", session_key="dream:check", ephemeral=True,
            )
@@ -435,13 +467,13 @@ class TestEphemeralDirect:

        captured = {}

-        original_save = loop._state_save
+        original_save = loop._persist_turn

        async def patched_save(ctx):
            captured["ephemeral"] = ctx.ephemeral
            return await original_save(ctx)

-        with patch.object(loop, "_state_save", side_effect=patched_save):
+        with patch.object(loop, "_persist_turn", side_effect=patched_save):
            await loop.process_direct("test", session_key="cli:normal")

        assert captured.get("ephemeral") is False
@@ -7,8 +7,11 @@ from nanobot.agent.loop import AgentLoop
 from nanobot.bus.events import OutboundMessage
 from nanobot.bus.outbound_events import GoalStatusEvent
 from nanobot.bus.queue import MessageBus
+from nanobot.channels.websocket.runtime import WebSocketChannel
 from nanobot.providers.base import GenerationSettings, LLMResponse
-from nanobot.session.webui_turns import WebuiTurnCoordinator
+from nanobot.session import webui_turns as wth
+from nanobot.session.webui_turns import WebuiTurnCoordinator, WebuiTurnRoutePolicy
+from nanobot.webui.metadata import WEBSOCKET_TURN_OWNER_METADATA_KEY


 def _make_loop(tmp_path):
@@ -32,6 +35,7 @@ def _make_loop(tmp_path):
        sessions=loop.sessions,
        schedule_background=lambda coro: loop._schedule_background(coro),
    ).subscribe(loop.runtime_events)
+    loop.turn_delivery_factory.route_policy = WebuiTurnRoutePolicy(loop.sessions)
    loop.tools.get_definitions = MagicMock(return_value=[])
    return loop

@@ -39,29 +43,51 @@ def _make_loop(tmp_path):
@pytest.mark.asyncio
 async def test_process_direct_websocket_clears_run_status(tmp_path) -> None:
    loop = _make_loop(tmp_path)
-
-    response = await loop.process_direct(
-        "deliver reminder",
-        session_key="cron:reminder-1",
-        channel="websocket",
-        chat_id="chat-1",
+    gateway = MagicMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        loop.bus,
+        gateway=gateway,
    )

-    assert response is not None
-    assert response.content == "done"
+    try:
+        response = await loop.process_direct(
+            "deliver reminder",
+            session_key="cron:reminder-1",
+            channel="websocket",
+            chat_id="chat-1",
+        )

-    events = []
-    while loop.bus.outbound_size:
-        events.append(await loop.bus.consume_outbound())
+        assert response is not None
+        assert response.content == "done"

-    statuses = [
-        event.event
-        for event in events
-        if isinstance(event.event, GoalStatusEvent)
-    ]
-    assert [status.status for status in statuses] == ["running", "idle"]
-    assert isinstance(statuses[0].started_at, float)
-    assert statuses[1].started_at is None
+        events = []
+        while loop.bus.outbound_size:
+            event = await loop.bus.consume_outbound()
+            events.append(event)
+            await channel.send(event)
+
+        status_messages = [
+            event
+            for event in events
+            if isinstance(event.event, GoalStatusEvent)
+        ]
+        statuses = [event.event for event in status_messages]
+        assert [status.status for status in statuses] == ["running", "idle"]
+        assert isinstance(statuses[0].started_at, float)
+        assert statuses[1].started_at is None
+        owners = {
+            event.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+            for event in status_messages
+        }
+        assert len(owners) == 1
+        assert wth.websocket_turn_wall_started_at("chat-1") is None
+        assert "chat-1" not in wth._WEBSOCKET_ACTIVE_TURNS
+    finally:
+        wth._WEBSOCKET_ACTIVE_TURNS.clear()
+        wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+        wth._WEBSOCKET_TURN_IDS.clear()
+        wth._WEBSOCKET_TURN_OWNERS.clear()


@pytest.mark.asyncio
@@ -28,7 +28,10 @@ from nanobot.utils.progress_events import (
    invoke_file_edit_progress,
    on_progress_accepts_file_edit_events,
 )
-from nanobot.webui.metadata import WEBUI_TURN_METADATA_KEY
+from nanobot.webui.metadata import (
+    WEBSOCKET_TURN_OWNER_METADATA_KEY,
+    WEBUI_TURN_METADATA_KEY,
+)


 def _make_loop(tmp_path: Path) -> AgentLoop:
@@ -903,6 +906,12 @@ class TestToolEventProgress:
        turn_id = turn_ids.pop()
        assert isinstance(turn_id, str)
        assert turn_id.startswith("subagent:")
+        owners = {
+            message.metadata.get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
+            for message in visible_events
+        }
+        assert len(owners) == 1
+        assert isinstance(owners.pop(), str)
        assert all(
            (message.channel, message.chat_id) == ("websocket", "chat-a")
            and message.metadata.get("webui") is True
@@ -910,6 +919,7 @@ class TestToolEventProgress:
            and set(message.metadata) <= {
                "webui",
                "_wants_stream",
+                WEBSOCKET_TURN_OWNER_METADATA_KEY,
                WEBUI_TURN_METADATA_KEY,
                "latency_ms",
            }
@@ -7,7 +7,7 @@ import pytest
 from loguru import logger

 from nanobot.agent.context import ContextBuilder
-from nanobot.agent.loop import AgentLoop, TurnState
+from nanobot.agent.loop import AgentLoop
 from nanobot.agent.tools.context import RequestContext, request_context
 from nanobot.bus.events import InboundMessage
 from nanobot.bus.outbound_events import (
@@ -34,7 +34,7 @@ from nanobot.session.keys import (
    LAST_CHANNEL_METADATA_KEY,
    UNIFIED_SESSION_KEY,
 )
-from nanobot.session.manager import Session, SessionManager
+from nanobot.session.manager import Session
 from nanobot.session.turn_continuation import (
    INTERNAL_CONTINUATION_META,
    INTERNAL_CONTINUATION_RUN_STARTED_AT_META,
@@ -49,7 +49,6 @@ from nanobot.session.webui_turns import (
    maybe_generate_webui_title,
 )
 from nanobot.triggers.local_session_turns import LOCAL_TRIGGER_META
-from nanobot.utils.llm_runtime import LLMRuntime


 def _mk_loop() -> AgentLoop:
@@ -314,55 +313,6 @@ async def test_generate_webui_title_ignores_cron_internal_turns(tmp_path: Path)
    loop.provider.chat_with_retry.assert_not_awaited()


-def test_webui_title_update_uses_captured_llm_runtime(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    bus = MessageBus()
-    sessions = SessionManager(tmp_path)
-    scheduled: list[object] = []
-    captured: dict[str, object] = {}
-
-    async def fake_title_after_turn(**kwargs: object) -> bool:
-        captured.update(kwargs)
-        return False
-
-    monkeypatch.setattr(
-        "nanobot.session.webui_turns.maybe_generate_webui_title_after_turn",
-        fake_title_after_turn,
-    )
-    coordinator = WebuiTurnCoordinator(
-        bus=bus,
-        sessions=sessions,
-        schedule_background=lambda coro: scheduled.append(coro),
-    )
-    provider = MagicMock()
-    msg = InboundMessage(
-        channel="websocket",
-        sender_id="u1",
-        chat_id="chat1",
-        content="say hello",
-        metadata={"webui": True},
-    )
-
-    coordinator.capture_title_context(
-        "websocket:chat1",
-        msg,
-        LLMRuntime.capture(provider, "turn-model", context_window_tokens=32_768),
-    )
-    asyncio.run(coordinator.handle_turn_end(
-        msg,
-        session_key="websocket:chat1",
-        latency_ms=None,
-    ))
-
-    assert len(scheduled) == 1
-    asyncio.run(scheduled[0])  # type: ignore[arg-type]
-
-    assert captured["provider"] is provider
-    assert captured["model"] == "turn-model"
-
-
 def test_save_turn_keeps_multimodal_runtime_context_for_model_replay() -> None:
    loop = _mk_loop()
    session = Session(key="test:runtime-only")
@@ -451,7 +401,6 @@ def test_build_and_save_preserves_user_text_containing_goal_guidance_tag(tmp_pat
        [],
        user_text,
        channel="cli",
-        chat_id="direct",
    )
    assert "_meta" not in messages[-1]

@@ -476,7 +425,6 @@ def test_build_and_save_preserves_multimodal_user_block_starting_with_runtime_ta
        user_text,
        media=[str(image)],
        channel="cli",
-        chat_id="direct",
    )

    loop._save_turn(session, messages, skip=1)
@@ -765,10 +713,9 @@ def test_unified_session_route_ignores_non_user_destinations(
    assert session.metadata[LAST_CHANNEL_METADATA_KEY] == "telegram:existing"


-# 1x1 PNG used by the media-persistence tests. ``extract_documents`` runs
-# at the top of ``_process_message`` and filters ``msg.media`` down to
-# paths that magic-byte-sniff as images, so the test fixture needs real
-# bytes on disk (not just placeholder paths).
+# 1x1 PNG used by the media-persistence tests. Attachment preparation filters
+# ``msg.media`` down to paths that magic-byte-sniff as images, so the test
+# fixture needs real bytes on disk (not just placeholder paths).
 _PNG_1X1 = (
    b"\x89PNG\r\n\x1a\n"
    b"\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01"
@@ -1101,7 +1048,7 @@ async def test_websocket_internal_continuation_keeps_single_visible_run(


@pytest.mark.asyncio
-async def test_process_message_uses_context_chat_id_for_runtime_prompt(tmp_path: Path) -> None:
+async def test_process_message_keeps_delivery_chat_for_thread_session(tmp_path: Path) -> None:
    loop = _make_full_loop(tmp_path)
    loop.consolidator.maybe_consolidate_by_tokens = AsyncMock(return_value=False)  # type: ignore[method-assign]
    loop.context.build_messages = MagicMock(  # type: ignore[method-assign]
@@ -1135,12 +1082,11 @@ async def test_process_message_uses_context_chat_id_for_runtime_prompt(tmp_path:

    assert result is not None
    assert result.chat_id == "thread-777"
-    assert loop.context.build_messages.call_args.kwargs["chat_id"] == "parent-456"
    assert loop._run_agent_loop.call_args.kwargs["chat_id"] == "thread-777"


@pytest.mark.asyncio
-async def test_process_message_uses_explicit_session_metadata_for_goal_context(
+async def test_process_message_uses_explicit_session_for_goal_context(
    tmp_path: Path,
 ) -> None:
    loop = _make_full_loop(tmp_path)
@@ -1185,10 +1131,10 @@ async def test_process_message_uses_explicit_session_metadata_for_goal_context(

    assert result is not None
    assert result.content == "ok"
-    kwargs = loop.context.build_messages.call_args.kwargs
-    assert kwargs["chat_id"] == "chat-with-goal"
-    assert kwargs["session_metadata"] is system_session.metadata
-    assert GOAL_STATE_KEY not in kwargs["session_metadata"]
+    kwargs = loop._run_agent_loop.call_args.kwargs
+    assert kwargs["session"] is system_session
+    assert kwargs["session_key"] == "system"
+    assert GOAL_STATE_KEY not in kwargs["session"].metadata


@pytest.mark.asyncio
@@ -1389,7 +1335,7 @@ async def test_stop_preserves_runtime_checkpoint_for_next_turn(tmp_path: Path) -

    first_msg = InboundMessage(channel="feishu", sender_id="u1", chat_id="c4", content="keep progress")
    task = asyncio.create_task(loop._process_message(first_msg))
-    loop._active_tasks[first_msg.session_key] = [task]
+    loop._active_tasks[first_msg.session_key] = {task}
    await asyncio.wait_for(checkpoint_saved.wait(), timeout=1.0)

    stop_msg = InboundMessage(channel="feishu", sender_id="u1", chat_id="c4", content="/stop")
@@ -1454,7 +1400,7 @@ async def test_system_subagent_followup_is_persisted_before_prompt_assembly(tmp_

    runtime = loop.llm_runtime()
    seen: dict[str, object] = {}
-    record_runtime = MagicMock(wraps=loop._runtime_events().record_turn_runtime)
+    record_runtime = MagicMock(wraps=loop.runtime_event_publisher.record_turn_runtime)
    loop.runtime_event_publisher.record_turn_runtime = record_runtime

    async def fake_run_agent_loop(initial_messages, **kwargs):
@@ -1570,27 +1516,26 @@ async def test_system_subagent_followup_does_not_log_content(tmp_path: Path) ->


@pytest.mark.asyncio
-async def test_system_subagent_followup_uses_common_turn_state_machine(tmp_path: Path) -> None:
+async def test_system_subagent_followup_uses_common_turn_lifecycle(tmp_path: Path) -> None:
    loop = _make_full_loop(tmp_path)
    loop.consolidator.maybe_consolidate_by_tokens = AsyncMock(  # type: ignore[method-assign]
        return_value=False
    )
-    visited: list[TurnState] = []
+    visited: list[str] = []

-    for state in (
-        TurnState.RESTORE,
-        TurnState.COMPACT,
-        TurnState.COMMAND,
-        TurnState.BUILD,
-        TurnState.RUN,
-        TurnState.SAVE,
-        TurnState.RESPOND,
+    for name in (
+        "_restore_turn",
+        "_compact_session",
+        "_dispatch_command",
+        "_build_turn",
+        "_run_turn",
+        "_persist_turn",
+        "_prepare_outbound",
    ):
-        name = f"_state_{state.name.lower()}"
        original = getattr(loop, name)

-        async def record(ctx, *, _original=original, _state=state):
-            visited.append(_state)
+        async def record(ctx, *, _original=original, _name=name):
+            visited.append(_name)
            return await _original(ctx)

        setattr(loop, name, record)
@@ -1606,25 +1551,33 @@ async def test_system_subagent_followup_uses_common_turn_state_machine(tmp_path:

    loop._run_agent_loop = fake_run_agent_loop  # type: ignore[method-assign]

-    await loop._process_message(
-        InboundMessage(
-            channel="system",
-            sender_id="subagent",
-            chat_id="cli:test",
-            content="subagent result",
-            metadata={"subagent_task_id": "sub-1"},
+    logs: list[str] = []
+    sink_id = logger.add(logs.append, level="DEBUG", format="{message}")
+    try:
+        await loop._process_message(
+            InboundMessage(
+                channel="system",
+                sender_id="subagent",
+                chat_id="cli:test",
+                content="subagent result",
+                metadata={"subagent_task_id": "sub-1"},
+            )
        )
-    )
+    finally:
+        logger.remove(sink_id)

    assert visited == [
-        TurnState.RESTORE,
-        TurnState.COMPACT,
-        TurnState.COMMAND,
-        TurnState.BUILD,
-        TurnState.RUN,
-        TurnState.SAVE,
-        TurnState.RESPOND,
+        "_restore_turn",
+        "_compact_session",
+        "_dispatch_command",
+        "_build_turn",
+        "_run_turn",
+        "_persist_turn",
+        "_prepare_outbound",
    ]
+    logged = "".join(logs)
+    for stage in ("restore", "compact", "command", "build", "run", "save", "respond"):
+        assert f"Stage {stage} completed in" in logged


@pytest.mark.asyncio
@@ -1687,9 +1640,7 @@ def test_subagent_followup_uses_user_model_input_and_assistant_history(tmp_path:
    projected = builder.build_messages(
        history=history,
        current_message="subagent result",
-        current_role="user",
        channel="cli",
-        chat_id="merge",
    )

    non_system = [m for m in projected if m.get("role") != "system"]
@@ -225,7 +225,7 @@ async def test_process_message_captures_original_text_before_restore(
        seen.append((ctx.original_user_text, ctx.runtime))
        raise RuntimeError("captured before restore")

-    loop._state_restore = stop_after_capture  # type: ignore[method-assign]
+    loop._restore_turn = stop_after_capture  # type: ignore[method-assign]

    with pytest.raises(RuntimeError, match="captured before restore"):
        await loop._process_message(
@@ -135,7 +135,7 @@ async def test_tool_fails_after_retry_exhausted():

    assert "failed after retry" in output
    assert "ClosedResourceError" in output
-    assert is_tool_error_result(wrapper.name, output)
+    assert is_tool_error_result(output)
    assert session.call_tool.call_count == 2


@@ -235,11 +235,23 @@ class TestHistoryWithCursor:
        store.append_history("event 3")
        store.append_history("event 4")
        store.append_history("event 5")
+        store.set_last_dream_cursor(5)
        store.compact_history()
        entries = store.read_unprocessed_history(since_cursor=0)
        assert len(entries) == 2
        assert entries[0]["cursor"] in {4, 5}

+    def test_compact_history_preserves_entries_after_dream_cursor(self, tmp_path):
+        store = MemoryStore(tmp_path, max_history_entries=50)
+        for index in range(1, 101):
+            store.append_history(f"event {index}")
+        store.set_last_dream_cursor(20)
+
+        store.compact_history()
+
+        entries = store.read_unprocessed_history(since_cursor=0)
+        assert [entry["cursor"] for entry in entries] == list(range(21, 101))
+
    def test_write_entries_uses_atomic_write(self, tmp_path):
        """_write_entries uses temp file + os.replace for atomicity."""
        store = MemoryStore(tmp_path)
@@ -95,6 +95,33 @@ def test_resolver_resolves_preset_without_mutating_selected_runtime() -> None:
    assert resolved.generation == GenerationSettings(0.5, 512, None)


+def test_static_presets_keep_image_capability_request_scoped() -> None:
+    provider = _provider()
+    provider.supports_image_input = None
+    resolver = ModelRuntimeResolver(
+        _runtime(provider),
+        model_presets={
+            "vision": ModelPresetConfig(
+                model="shared-model",
+                supports_image_input=True,
+            ),
+            "text": ModelPresetConfig(
+                model="shared-model",
+                supports_image_input=False,
+            ),
+        },
+    )
+
+    vision = resolver.resolve_preset("vision")
+    text = resolver.resolve_preset("text")
+
+    assert vision.provider is provider
+    assert text.provider is provider
+    assert vision.supports_image_input is True
+    assert text.supports_image_input is False
+    assert provider.supports_image_input is None
+
+
 def test_resolver_reuses_preset_until_runtime_config_is_invalidated() -> None:
    initial = _runtime()
    preset = ModelPresetConfig(model="fast-model")
@@ -537,7 +537,7 @@ class TestRunOnboardExitBehavior:

        def fake_configure_general_settings(config, section):
            if section == "Agent Settings":
-                config.agents.defaults.model = "test/provider-model"
+                config.resolve_default_preset().model = "test/provider-model"

        monkeypatch.setattr(onboard_wizard, "_show_main_menu_header", lambda: None)
        monkeypatch.setattr(onboard_wizard, "_select_with_back", fake_select_with_back)
@@ -1997,7 +1997,7 @@ class TestModelPresetWizard:
        config.model_presets["fast"] = ModelPresetConfig(model="gpt-4.1-mini")
        config.model_presets["power"] = ModelPresetConfig(model="gpt-4.1")
        _sync_preset_cache(config)
-        assert _MODEL_PRESET_CACHE == {"fast", "power"}
+        assert _MODEL_PRESET_CACHE == {"default", "fast", "power"}
        _MODEL_PRESET_CACHE.clear()

    def test_model_preset_add(self, monkeypatch):
@@ -2106,10 +2106,9 @@ class TestModelPresetWizard:
        assert defaults.model_preset == "fast"
        _MODEL_PRESET_CACHE.clear()

-    def test_model_preset_field_handler_clear(self, monkeypatch):
-        """_handle_model_preset_field should clear preset when Clear value is chosen."""
+    def test_model_preset_field_handler_selects_default(self, monkeypatch):
+        """The concrete default preset replaces the legacy clear selection."""
        from nanobot.cli.onboard import (
-            _CLEAR_CHOICE,
            _MODEL_PRESET_CACHE,
            _handle_model_preset_field,
        )
@@ -2118,11 +2117,11 @@ class TestModelPresetWizard:
        _MODEL_PRESET_CACHE.clear()
        _MODEL_PRESET_CACHE.add("fast")

-        monkeypatch.setattr(onboard_wizard, "_select_with_back", lambda *a, **kw: _CLEAR_CHOICE)
+        monkeypatch.setattr(onboard_wizard, "_select_with_back", lambda *a, **kw: "default")

        defaults = AgentDefaults(model_preset="fast")
        _handle_model_preset_field(defaults, "model_preset", "Model Preset", "fast")
-        assert defaults.model_preset is None
+        assert defaults.model_preset == "default"
        _MODEL_PRESET_CACHE.clear()

    def test_main_menu_dispatch_includes_model_presets(self):
@@ -2208,13 +2207,13 @@ class TestModelPresetWizard:
    def test_provider_field_handler(self, monkeypatch):
        """_handle_provider_field should set provider from choices."""
        from nanobot.cli.onboard import _handle_provider_field
-        from nanobot.config.schema import AgentDefaults
+        from nanobot.config.schema import ModelPresetConfig

        monkeypatch.setattr(onboard_wizard, "_select_with_back", lambda *a, **kw: "anthropic")

-        defaults = AgentDefaults()
-        _handle_provider_field(defaults, "provider", "Provider", "auto")
-        assert defaults.provider == "anthropic"
+        preset = ModelPresetConfig(model="anthropic/claude-opus-4-5")
+        _handle_provider_field(preset, "provider", "Provider", "auto")
+        assert preset.provider == "anthropic"

    def test_search_provider_field_handler(self, monkeypatch):
        """_handle_search_provider_field should set the search engine from choices."""
@@ -2235,7 +2234,10 @@ class TestModelPresetWizard:
            _handle_search_provider_field,
            _resolve_field_handler,
        )
-        from nanobot.config.schema import AgentDefaults
+        from nanobot.config.schema import ModelPresetConfig

        assert _resolve_field_handler(WebSearchConfig(), "provider") is _handle_search_provider_field
-        assert _resolve_field_handler(AgentDefaults(), "provider") is _handle_provider_field
+        assert (
+            _resolve_field_handler(ModelPresetConfig(model="test"), "provider")
+            is _handle_provider_field
+        )
@@ -3,7 +3,7 @@
 from __future__ import annotations

 from typing import Any
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch

 import pytest
 from loguru import logger
@@ -46,6 +46,7 @@ def _fallback(
    context_window_tokens: int = 65_536,
    temperature: float = 0.1,
    reasoning_effort: str | None = None,
+    supports_image_input: bool | None = None,
 ) -> ModelPresetConfig:
    return ModelPresetConfig(
        model=model,
@@ -54,6 +55,7 @@ def _fallback(
        context_window_tokens=context_window_tokens,
        temperature=temperature,
        reasoning_effort=reasoning_effort,
+        supports_image_input=supports_image_input,
    )


@@ -93,33 +95,35 @@ def test_fallback_models_default_empty() -> None:
    assert defaults.fallback_models == []


-def test_fallback_models_accept_preset_refs_and_inline_configs() -> None:
-    from nanobot.config.schema import Config, InlineFallbackConfig
+def test_fallback_models_accept_preset_refs() -> None:
+    from nanobot.config.schema import Config

    config = Config.model_validate({
        "agents": {
            "defaults": {
-                "fallbackModels": [
-                    "deep",
-                    {
-                        "provider": "openai",
-                        "model": "gpt-4.1",
-                        "maxTokens": 4096,
-                    },
-                ]
+                "fallbackModels": ["deep"]
            }
        },
        "modelPresets": {
+            "default": {"provider": "openai", "model": "gpt-4.1"},
            "deep": {"provider": "anthropic", "model": "claude-opus-4-7"}
        },
    })

-    assert config.agents.defaults.fallback_models[0] == "deep"
-    assert config.agents.defaults.fallback_models[1] == InlineFallbackConfig(
-        provider="openai",
-        model="gpt-4.1",
-        max_tokens=4096,
-    )
+    assert config.agents.defaults.fallback_models == ["deep"]
+
+
+def test_fallback_models_reject_inline_configs_after_schema_migration() -> None:
+    from nanobot.config.schema import Config
+
+    with pytest.raises(ValueError):
+        Config.model_validate({
+            "agents": {
+                "defaults": {
+                    "fallbackModels": [{"provider": "openai", "model": "gpt-4.1"}]
+                }
+            }
+        })


 def test_fallback_model_preset_ref_must_exist() -> None:
@@ -128,7 +132,7 @@ def test_fallback_model_preset_ref_must_exist() -> None:
    with pytest.raises(ValueError, match="fallback_models.*not found"):
        Config.model_validate({
            "agents": {"defaults": {"fallbackModels": ["missing"]}},
-            "modelPresets": {},
+            "modelPresets": {"default": {"model": "primary"}},
        })


@@ -144,6 +148,7 @@ def test_provider_signature_tracks_fallback_presets_and_provider_config() -> Non
            }
        },
        "modelPresets": {
+            "default": {"model": "primary", "provider": "openai"},
            "fast": {"model": "openai/gpt-4.1", "provider": "openai"},
            "deep": {"model": "anthropic/claude-sonnet-4-6", "provider": "anthropic"},
        },
@@ -190,6 +195,7 @@ def test_provider_snapshot_uses_smallest_fallback_context_window() -> None:
            }
        },
        "modelPresets": {
+            "default": {"model": "primary", "provider": "openai"},
            "fast": {
                "model": "openai/gpt-4.1",
                "provider": "openai",
@@ -213,36 +219,49 @@ def test_provider_snapshot_uses_smallest_fallback_context_window() -> None:
    assert snapshot.context_window_tokens == 64000


-def test_inline_fallback_reasoning_effort_does_not_inherit_primary() -> None:
+def test_provider_signature_tracks_fallback_image_capability() -> None:
    from nanobot.config.schema import Config
    from nanobot.providers.factory import provider_signature

-    config = Config.model_validate({
+    base = {
        "agents": {
            "defaults": {
                "modelPreset": "fast",
-                "fallbackModels": [
-                    {"provider": "openai", "model": "gpt-4.1"}
-                ],
+                "fallbackModels": ["fallback"],
            }
        },
        "modelPresets": {
+            "default": {"model": "primary"},
            "fast": {
                "model": "anthropic/claude-opus-4-5",
                "provider": "anthropic",
                "reasoningEffort": "high",
-            }
+            },
+            "fallback": {
+                "provider": "openai",
+                "model": "gpt-4.1",
+                "supportsImageInput": False,
+            },
        },
        "providers": {
            "anthropic": {"apiKey": "primary-key"},
            "openai": {"apiKey": "fallback-key"},
        },
-    })
+    }
+    changed = {
+        **base,
+        "modelPresets": {
+            **base["modelPresets"],
+            "fallback": {
+                **base["modelPresets"]["fallback"],
+                "supportsImageInput": True,
+            },
+        },
+    }

-    signature = provider_signature(config)
-    fallback_signatures = signature[-1]
-
-    assert fallback_signatures[0][13] is None
+    assert provider_signature(Config.model_validate(base)) != provider_signature(
+        Config.model_validate(changed)
+    )


 # -- FallbackProvider tests --
@@ -333,6 +352,204 @@ class TestFallbackOnPrimaryError:
            for line in logs
        )

+    @pytest.mark.asyncio
+    async def test_primary_and_fallback_apply_their_own_image_capability(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider("primary", _error_response())
+        primary.supports_image_input = True
+        fallback = _FakeProvider("fallback", _make_response("fallback ok"))
+        factory = MagicMock(return_value=fallback)
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", supports_image_input=False)
+            ],
+            provider_factory=factory,
+        )
+
+        result = await fb.chat(messages=image_messages, model="primary-model")
+
+        assert result.content == "fallback ok"
+        primary_content = primary.chat_calls[0]["messages"][0]["content"]
+        fallback_content = fallback.chat_calls[0]["messages"][0]["content"]
+        assert any(block.get("type") == "image_url" for block in primary_content)
+        assert all(block.get("type") != "image_url" for block in fallback_content)
+
+    @pytest.mark.asyncio
+    async def test_text_only_primary_does_not_remove_images_from_vision_fallback(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider("primary", _error_response())
+        primary.supports_image_input = False
+        fallback = _FakeProvider("fallback", _make_response("fallback ok"))
+        factory = MagicMock(return_value=fallback)
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", supports_image_input=True)
+            ],
+            provider_factory=factory,
+        )
+
+        result = await fb.chat(messages=image_messages, model="primary-model")
+
+        assert result.content == "fallback ok"
+        primary_content = primary.chat_calls[0]["messages"][0]["content"]
+        fallback_content = fallback.chat_calls[0]["messages"][0]["content"]
+        assert all(block.get("type") != "image_url" for block in primary_content)
+        assert any(block.get("type") == "image_url" for block in fallback_content)
+
+    @pytest.mark.asyncio
+    async def test_explicit_vision_rejection_advances_to_vision_fallback(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider(
+            "primary",
+            _make_response(
+                "image input is not supported",
+                finish_reason="error",
+                error_kind="invalid_request",
+                error_status_code=400,
+            ),
+        )
+        primary.supports_image_input = True
+        fallback = _FakeProvider("fallback", _make_response("fallback ok"))
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", supports_image_input=True)
+            ],
+            provider_factory=MagicMock(return_value=fallback),
+        )
+
+        result = await fb.chat(messages=image_messages, model="primary-model")
+
+        assert result.content == "fallback ok"
+        fallback_content = fallback.chat_calls[0]["messages"][0]["content"]
+        assert any(block.get("type") == "image_url" for block in fallback_content)
+        assert fb._primary_failures == 0
+
+    @pytest.mark.asyncio
+    async def test_auto_primary_retries_without_images_through_retry_wrapper(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider("primary")
+        primary.chat = AsyncMock(side_effect=[
+            _make_response(
+                "image input is not supported",
+                finish_reason="error",
+                error_kind="invalid_request",
+            ),
+            _make_response("primary text fallback ok"),
+        ])
+        fallback_factory = MagicMock()
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[_fallback("fallback-a", supports_image_input=True)],
+            provider_factory=fallback_factory,
+        )
+
+        result = await fb.chat_with_retry(
+            messages=image_messages,
+            model="primary-model",
+        )
+
+        assert result.content == "primary text fallback ok"
+        assert primary.chat.await_count == 2
+        retry_content = primary.chat.await_args_list[1].kwargs["messages"][0]["content"]
+        assert all(block.get("type") != "image_url" for block in retry_content)
+        fallback_factory.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_streaming_vision_rejection_advances_to_text_fallback(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider("primary")
+        primary.supports_image_input = True
+        primary.chat_stream = AsyncMock(return_value=_make_response(
+            "image input is not supported",
+            finish_reason="error",
+            error_kind="invalid_request",
+            error_status_code=400,
+        ))
+        fallback = _FakeProvider("fallback")
+        fallback.chat_stream = AsyncMock(return_value=_make_response("fallback ok"))
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", supports_image_input=False)
+            ],
+            provider_factory=MagicMock(return_value=fallback),
+        )
+
+        result = await fb.chat_stream(
+            messages=image_messages,
+            model="primary-model",
+            on_content_delta=AsyncMock(),
+        )
+
+        assert result.content == "fallback ok"
+        fallback_content = fallback.chat_stream.await_args.kwargs["messages"][0]["content"]
+        assert all(block.get("type") != "image_url" for block in fallback_content)
+
+    @pytest.mark.asyncio
+    async def test_auto_capability_does_not_retry_after_streaming_content(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider(
+            "primary",
+            _make_response(
+                "model does not support images",
+                finish_reason="error",
+                error_kind="invalid_request",
+            ),
+        )
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[_fallback("fallback-a")],
+            provider_factory=MagicMock(),
+        )
+
+        result = await fb.chat_stream(
+            messages=image_messages,
+            model="primary-model",
+            on_content_delta=AsyncMock(),
+        )
+
+        assert result.finish_reason == "error"
+        assert len(primary.chat_stream_calls) == 1
+

 class TestNoFallbackWhenContentStreamed:
    @pytest.mark.asyncio
@@ -10,7 +10,6 @@ import pytest
 from agent.runner_helpers import make_run_spec
 from nanobot.agent.context_governance import (
    BACKFILL_CONTENT,
-    MICROCOMPACT_KEEP_RECENT,
    ContextGovernanceConfig,
    ContextGovernor,
 )
@@ -495,7 +494,7 @@ def test_microcompact_skips_when_prompt_under_hard_budget(monkeypatch):
    tools = MagicMock()
    tools.get_definitions.return_value = []

-    total = MICROCOMPACT_KEEP_RECENT + 5
+    total = 15
    long_content = "x" * 600
    messages = _microcompact_messages(total=total, tool_name="read_file", content=long_content)
    spec = make_run_spec(provider,
@@ -529,7 +528,7 @@ def test_microcompact_overflow_compacts_to_low_watermark(monkeypatch):
    tools = MagicMock()
    tools.get_definitions.return_value = []

-    total = MICROCOMPACT_KEEP_RECENT + 8
+    total = 18
    long_content = "x" * 600
    messages = _microcompact_messages(total=total, tool_name="read_file", content=long_content)
    spec = make_run_spec(provider,
@@ -617,7 +616,7 @@ def test_context_governor_keeps_compaction_boundary_stable(monkeypatch):
    tools = MagicMock()
    tools.get_definitions.return_value = []

-    total = MICROCOMPACT_KEEP_RECENT + 8
+    total = 18
    long_content = "x" * 600
    messages = _microcompact_messages(total=total, tool_name="read_file", content=long_content)
    spec = make_run_spec(provider,
@@ -658,7 +657,7 @@ def test_microcompact_preserves_short_results(monkeypatch):
    tools = MagicMock()
    tools.get_definitions.return_value = []

-    total = MICROCOMPACT_KEEP_RECENT + 5
+    total = 15
    messages = _microcompact_messages(total=total, tool_name="exec", content="short")
    spec = make_run_spec(provider,
        initial_messages=messages,
@@ -690,7 +689,7 @@ def test_microcompact_skips_non_compactable_tools(monkeypatch):
    tools = MagicMock()
    tools.get_definitions.return_value = []

-    total = MICROCOMPACT_KEEP_RECENT + 5
+    total = 15
    long_content = "y" * 1000
    messages = _microcompact_messages(total=total, tool_name="message", content=long_content)
    spec = make_run_spec(provider,
@@ -19,9 +19,11 @@ async def test_active_run_keeps_provider_captured_at_admission() -> None:
    second_provider = MagicMock(spec=LLMProvider)
    first_provider.generation = GenerationSettings(temperature=0.2, max_tokens=2048)
    second_provider.generation = GenerationSettings(temperature=0.9, max_tokens=512)
+    first_provider.supports_image_input = False
    first_calls = 0
    second_calls = 0
    request_temperatures: list[float] = []
+    request_image_capabilities: list[bool | None] = []
    selected_runtime = LLMRuntime.capture(
        first_provider,
        "captured-model",
@@ -33,6 +35,7 @@ async def test_active_run_keeps_provider_captured_at_admission() -> None:
        nonlocal first_calls, selected_runtime
        first_calls += 1
        request_temperatures.append(kwargs["temperature"])
+        request_image_capabilities.append(kwargs["supports_image_input"])
        selected_runtime = LLMRuntime.capture(
            second_provider,
            "future-model",
@@ -68,4 +71,5 @@ async def test_active_run_keeps_provider_captured_at_admission() -> None:
    assert first_calls == 2
    assert second_calls == 0
    assert request_temperatures == [0.2, 0.2]
+    assert request_image_capabilities == [False, False]
    assert selected_runtime.provider is second_provider
@@ -1,4 +1,5 @@
 import asyncio
+import json
 from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import MagicMock
@@ -8,6 +9,7 @@ import pytest
 from nanobot.agent.loop import AgentLoop
 from nanobot.bus.queue import MessageBus
 from nanobot.bus.runtime_events import RuntimeModelChanged
+from nanobot.config.errors import ConfigLoadError
 from nanobot.config.loader import save_config
 from nanobot.config.schema import Config, ModelPresetConfig
 from nanobot.providers.base import GenerationSettings
@@ -127,6 +129,24 @@ def test_llm_runtime_surfaces_invalidated_config_errors(tmp_path: Path) -> None:
        loop.llm_runtime()


+def test_provider_snapshot_missing_env_reports_explicit_config_path(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    name = "NANOBOT_TEST_REFRESH_MISSING_KEY"
+    monkeypatch.delenv(name, raising=False)
+    config_path = tmp_path / "custom.json"
+    config_path.write_text(
+        json.dumps({"providers": {"openrouter": {"apiKey": f"${{{name}}}"}}}),
+        encoding="utf-8",
+    )
+
+    with pytest.raises(ConfigLoadError) as exc_info:
+        load_provider_snapshot(config_path)
+
+    assert exc_info.value.path == config_path
+
+
 def test_same_snapshot_default_clears_preset_and_publishes_update(tmp_path: Path) -> None:
    base_provider = _provider("base-model")
    fast_provider = _provider("fast-model")
@@ -282,9 +302,9 @@ def test_settings_context_window_refreshes_runtime_state(
    config_path = tmp_path / "config.json"
    config = Config()
    config.agents.defaults.workspace = str(tmp_path / "workspace")
-    config.agents.defaults.model = "openai/gpt-4o"
-    config.agents.defaults.provider = "openai"
-    config.agents.defaults.context_window_tokens = 65_536
+    config.resolve_default_preset().model = "openai/gpt-4o"
+    config.resolve_default_preset().provider = "openai"
+    config.resolve_default_preset().context_window_tokens = 65_536
    config.providers.openai.api_key = "sk-test"
    save_config(config, config_path)
    monkeypatch.setattr("nanobot.config.loader._current_config_path", config_path)
@@ -301,3 +321,44 @@ def test_settings_context_window_refreshes_runtime_state(
    assert payload["requires_restart"] is False
    assert loop.context_window_tokens == 262_144
    assert loop.llm_runtime().context_window_tokens == 262_144
+
+
+def test_from_config_uses_snapshot_loader_for_preset_switch_with_injected_provider(
+    tmp_path: Path,
+) -> None:
+    config = Config()
+    config.agents.defaults.workspace = str(tmp_path / "workspace")
+    config.agents.defaults.model_preset = "default"
+    config.model_presets = {
+        "default": ModelPresetConfig(model="base-model", provider="openai"),
+        "fast": ModelPresetConfig(model="fast-model", provider="deepseek"),
+    }
+    initial_provider = _provider("base-model")
+    default_provider = _provider("base-model")
+    fast_provider = _provider("fast-model")
+    loaded_presets: list[str | None] = []
+
+    def loader(*, preset_name: str | None = None) -> ProviderSnapshot:
+        loaded_presets.append(preset_name)
+        provider = fast_provider if preset_name == "fast" else default_provider
+        model = "fast-model" if preset_name == "fast" else "base-model"
+        return ProviderSnapshot(
+            provider=provider,
+            model=model,
+            context_window_tokens=32_768,
+            signature=(model, preset_name),
+        )
+
+    loop = AgentLoop.from_config(
+        config,
+        provider=initial_provider,
+        provider_snapshot_loader=loader,
+    )
+
+    runtime = loop.runtime_resolver.resolve_preset("fast")
+
+    assert runtime.provider is fast_provider
+    assert runtime.model == "fast-model"
+    assert runtime.model_preset == "fast"
+    assert loop.provider is default_provider
+    assert loaded_presets == ["default", "fast"]
@@ -378,13 +378,14 @@ def test_from_config_injects_default_preset(tmp_path) -> None:

    from nanobot.config.schema import Config
    config = Config.model_validate({
-        "agents": {"defaults": {"model": "openai/gpt-4.1", "workspace": str(tmp_path)}},
+        "agents": {"defaults": {"workspace": str(tmp_path)}},
+        "modelPresets": {"default": {"model": "openai/gpt-4.1"}},
    })
    fake_provider = _provider("openai/gpt-4.1")
    with patch("nanobot.providers.factory.make_provider", return_value=fake_provider):
        loop = AgentLoop.from_config(config)
    assert loop.model == "openai/gpt-4.1"
-    assert loop.model_preset is None
+    assert loop.model_preset == "default"
    assert "default" in loop.model_presets
    assert loop.model_presets["default"].model == "openai/gpt-4.1"

@@ -394,8 +395,11 @@ def test_from_config_static_preset_loader_does_not_enable_hot_reload(tmp_path) -

    from nanobot.config.schema import Config
    config = Config.model_validate({
-        "agents": {"defaults": {"model": "openai/gpt-4.1", "workspace": str(tmp_path)}},
-        "model_presets": {"fast": {"model": "openai/gpt-4.1-mini"}},
+        "agents": {"defaults": {"workspace": str(tmp_path)}},
+        "model_presets": {
+            "default": {"model": "openai/gpt-4.1"},
+            "fast": {"model": "openai/gpt-4.1-mini"},
+        },
    })
    fake_provider = _provider("openai/gpt-4.1")
    with patch("nanobot.providers.factory.make_provider", return_value=fake_provider):
@@ -65,7 +65,7 @@ def test_save_uses_new_path_not_lossy(tmp_path: Path, monkeypatch) -> None:
    assert lossy_path.read_text(encoding="utf-8") == stale_lossy


-def test_load_falls_back_to_lossy_path(tmp_path: Path, monkeypatch) -> None:
+def test_load_ignores_legacy_lossy_path(tmp_path: Path, monkeypatch) -> None:
    sm = _manager(tmp_path, monkeypatch)
    key = "telegram:legacy:lossy"
    lossy_path = sm._get_legacy_lossy_path(key)
@@ -73,49 +73,23 @@ def test_load_falls_back_to_lossy_path(tmp_path: Path, monkeypatch) -> None:

    session = sm._load(key)

-    assert session is not None
-    assert session.metadata == {"source": "test"}
-    assert session.messages[0]["content"] == "loaded from lossy"
+    assert session is None
+    assert lossy_path.exists()
+    assert not sm._get_session_path(key).exists()


-def test_load_migrates_lossy_to_new_path(tmp_path: Path, monkeypatch) -> None:
+def test_load_ignores_legacy_global_path(tmp_path: Path, monkeypatch) -> None:
    sm = _manager(tmp_path, monkeypatch)
-    key = "telegram:migrate:lossy"
+    key = "telegram:legacy:global"
    new_path = sm._get_session_path(key)
-    lossy_path = sm._get_legacy_lossy_path(key)
-    _write_session_file(lossy_path, key, "migrate me")
+    legacy_path = sm._get_legacy_session_path(key)
+    _write_session_file(legacy_path, key, "loaded from global")

    session = sm._load(key)

-    assert session is not None
-    assert session.messages[0]["content"] == "migrate me"
-    assert new_path.exists()
-    assert not lossy_path.exists()
-
-
-def test_load_does_not_migrate_lossy_path_for_different_stored_key(
-    tmp_path: Path,
-    monkeypatch,
-) -> None:
-    sm = _manager(tmp_path, monkeypatch)
-    first_key = "telegram:a_b"
-    second_key = "telegram:a:b"
-    lossy_path = sm._get_legacy_lossy_path(first_key)
-    assert lossy_path == sm._get_legacy_lossy_path(second_key)
-    _write_session_file(lossy_path, first_key, "belongs to first")
-
-    loaded_second = sm._load(second_key)
-
-    assert loaded_second is None
-    assert lossy_path.exists()
-    assert not sm._get_session_path(second_key).exists()
-
-    loaded_first = sm._load(first_key)
-
-    assert loaded_first is not None
-    assert loaded_first.messages[0]["content"] == "belongs to first"
-    assert sm._get_session_path(first_key).exists()
-    assert not lossy_path.exists()
+    assert session is None
+    assert legacy_path.exists()
+    assert not new_path.exists()


 def test_safe_key_is_lossy() -> None:
@@ -405,6 +405,44 @@ def test_get_history_synthesizes_breadcrumb_for_image_only_turn():
    assert history[0] == {"role": "user", "content": "[image: /m/pic.png]"}


+def test_get_history_can_return_internal_media_refs_without_breadcrumbs():
+    session = Session(key="test:media-internal")
+    session.messages.append(
+        {"role": "user", "content": "look", "media": ["/m/a.png", "/m/b.png"]}
+    )
+
+    history = session.get_history(max_messages=500, include_media=True)
+
+    assert history == [{
+        "role": "user",
+        "content": "look",
+        "_media_paths": ["/m/a.png", "/m/b.png"],
+    }]
+
+
+def test_get_history_keeps_runtime_context_boundary_with_internal_media_refs():
+    content, marker = append_runtime_context(
+        "look",
+        [RuntimeContextBlock(source="test", content="trusted runtime context")],
+    )
+    session = Session(key="test:media-runtime-context")
+    session.messages.append({
+        "role": "user",
+        "content": content,
+        "media": ["/m/a.png"],
+        RUNTIME_CONTEXT_HISTORY_META: marker,
+    })
+
+    history = session.get_history(max_messages=500, include_media=True)
+
+    assert history == [{
+        "role": "user",
+        "content": content,
+        "_media_paths": ["/m/a.png"],
+        RUNTIME_CONTEXT_HISTORY_META: marker,
+    }]
+
+
 def test_get_history_synthesizes_cli_app_attachment_breadcrumb():
    session = Session(key="test:cli-app")
    session.messages.append(
@@ -73,7 +73,9 @@ class TestHandleStop:

        task = asyncio.create_task(slow_task())
        await asyncio.sleep(0)
-        loop._active_tasks["test:c1"] = [task]
+        active_tasks = {task}
+        loop._active_tasks["test:c1"] = active_tasks
+        task.add_done_callback(active_tasks.discard)

        msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
        ctx = CommandContext(msg=msg, session=None, key=msg.session_key, raw="/stop", loop=loop)
@@ -100,7 +102,7 @@ class TestHandleStop:

        tasks = [asyncio.create_task(slow(i)) for i in range(2)]
        await asyncio.sleep(0)
-        loop._active_tasks["test:c1"] = tasks
+        loop._active_tasks["test:c1"] = set(tasks)

        msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
        ctx = CommandContext(msg=msg, session=None, key=msg.session_key, raw="/stop", loop=loop)
@@ -140,5 +140,5 @@ async def test_loader_entry_point_error_wrapper_preserves_tool_api(tmp_path):
    assert tool.to_schema() == {"name": "api_plugin", "custom": True}

    result = await tool.execute(value="1")
-    assert is_tool_error_result("api_plugin", result) is True
+    assert is_tool_error_result(result) is True
    assert str(result) == "Error: plugin failed"
@@ -1,12 +1,147 @@
 from pathlib import Path

+import pytest
+
 from nanobot.agent.turn_delivery import TurnDeliveryFactory
 from nanobot.bus.events import InboundMessage
 from nanobot.bus.queue import MessageBus
 from nanobot.bus.runtime_events import RuntimeEventBus
 from nanobot.session.manager import SessionManager
 from nanobot.session.webui_turns import WebuiTurnRoutePolicy
-from nanobot.webui.metadata import WEBUI_TURN_METADATA_KEY
+from nanobot.webui.metadata import (
+    WEBSOCKET_TURN_OWNER_METADATA_KEY,
+    WEBUI_TURN_METADATA_KEY,
+)
+
+
+def test_websocket_lifecycles_get_distinct_internal_owners(tmp_path: Path) -> None:
+    factory = TurnDeliveryFactory(
+        MessageBus(),
+        RuntimeEventBus(),
+        route_policy=WebuiTurnRoutePolicy(SessionManager(tmp_path / "sessions")),
+    )
+    first_msg = InboundMessage(
+        channel="websocket",
+        sender_id="user",
+        chat_id="chat-a",
+        content="first",
+        metadata={WEBSOCKET_TURN_OWNER_METADATA_KEY: "attacker-reused-owner"},
+    )
+    second_msg = InboundMessage(
+        channel="websocket",
+        sender_id="user",
+        chat_id="chat-a",
+        content="second",
+        metadata={WEBSOCKET_TURN_OWNER_METADATA_KEY: "attacker-reused-owner"},
+    )
+
+    first = factory.create(first_msg, first_msg.session_key)
+    second = factory.create(second_msg, second_msg.session_key)
+    first_owner = first.lifecycle_message.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+    second_owner = second.lifecycle_message.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+
+    assert first_owner == first.delivery_message.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+    assert first_owner != second_owner
+    assert first_owner != "attacker-reused-owner"
+    assert second_owner != "attacker-reused-owner"
+    assert WEBUI_TURN_METADATA_KEY not in first.lifecycle_message.metadata
+    assert first_msg.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] == first_owner
+    assert second_msg.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] == second_owner
+
+
+def test_websocket_lifecycle_reuses_registered_ingress_owner(tmp_path: Path) -> None:
+    from nanobot.session import webui_turns as wth
+
+    owner = wth.register_queued_websocket_turn_if_idle("chat-queued", "turn-queued")
+    assert owner is not None
+    msg = InboundMessage(
+        channel="websocket",
+        sender_id="user",
+        chat_id="chat-queued",
+        content="queued",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            WEBUI_TURN_METADATA_KEY: "turn-queued",
+        },
+    )
+    factory = TurnDeliveryFactory(
+        MessageBus(),
+        RuntimeEventBus(),
+        route_policy=WebuiTurnRoutePolicy(SessionManager(tmp_path / "sessions")),
+    )
+
+    try:
+        delivery = factory.create(msg, msg.session_key)
+
+        assert delivery.lifecycle_message.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] == owner
+        assert msg.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] == owner
+    finally:
+        wth.clear_websocket_turn_if_current("chat-queued", owner)
+
+
+@pytest.mark.asyncio
+async def test_same_chat_different_sessions_restore_previous_active_projection(
+    tmp_path: Path,
+) -> None:
+    from unittest.mock import AsyncMock, MagicMock
+
+    from nanobot.session import webui_turns as wth
+
+    factory = TurnDeliveryFactory(
+        MessageBus(),
+        RuntimeEventBus(),
+        route_policy=WebuiTurnRoutePolicy(SessionManager(tmp_path / "sessions")),
+    )
+    first_msg = InboundMessage(
+        channel="websocket",
+        sender_id="user",
+        chat_id="shared-chat",
+        content="first",
+        metadata={WEBUI_TURN_METADATA_KEY: "turn-first"},
+        session_key_override="websocket:session-first",
+    )
+    second_msg = InboundMessage(
+        channel="websocket",
+        sender_id="user",
+        chat_id="shared-chat",
+        content="second",
+        metadata={WEBUI_TURN_METADATA_KEY: "turn-second"},
+        session_key_override="websocket:session-second",
+    )
+    first = factory.create(first_msg, first_msg.session_key)
+    second = factory.create(second_msg, second_msg.session_key)
+    first_owner = first.lifecycle_message.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+    second_owner = second.lifecycle_message.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+
+    try:
+        await wth.publish_turn_run_status(
+            bus,
+            first.lifecycle_message,
+            "running",
+            started_at=100.0,
+        )
+        await wth.publish_turn_run_status(
+            bus,
+            second.lifecycle_message,
+            "running",
+            started_at=200.0,
+        )
+
+        assert wth.websocket_turn_wall_started_at("shared-chat") == 200.0
+        assert wth.websocket_turn_id("shared-chat") == "turn-second"
+        assert wth.clear_websocket_turn_if_current("shared-chat", second_owner) is True
+        assert wth.websocket_turn_wall_started_at("shared-chat") == 100.0
+        assert wth.websocket_turn_id("shared-chat") == "turn-first"
+        assert wth._WEBSOCKET_TURN_OWNERS["shared-chat"] == first_owner
+        assert wth.clear_websocket_turn_if_current("shared-chat", first_owner) is True
+        assert wth.websocket_turn_wall_started_at("shared-chat") is None
+    finally:
+        wth._WEBSOCKET_ACTIVE_TURNS.pop("shared-chat", None)
+        wth._WEBSOCKET_TURN_WALL_STARTED_AT.pop("shared-chat", None)
+        wth._WEBSOCKET_TURN_IDS.pop("shared-chat", None)
+        wth._WEBSOCKET_TURN_OWNERS.pop("shared-chat", None)


 def test_late_subagent_route_requires_webui_owned_session(tmp_path: Path) -> None:
@@ -45,6 +180,7 @@ def test_late_subagent_route_requires_webui_owned_session(tmp_path: Path) -> Non
    assert set(first_visible_route.metadata) == {
        "webui",
        "_wants_stream",
+        WEBSOCKET_TURN_OWNER_METADATA_KEY,
        WEBUI_TURN_METADATA_KEY,
    }
    assert first_visible_route.metadata["webui"] is True
@@ -54,6 +190,10 @@ def test_late_subagent_route_requires_webui_owned_session(tmp_path: Path) -> Non
    assert first_turn_id.startswith("subagent:")
    assert second_turn_id.startswith("subagent:")
    assert first_turn_id != second_turn_id
+    assert (
+        first_visible_route.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+        != second_visible_route.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+    )
    assert msg.metadata == {
        "injected_event": "subagent_result",
        "subagent_task_id": "sub-1",
@@ -14,6 +14,23 @@ class RecordingHook(AgentHook):
        self._events.append(f"{self._label}:{context.iteration}")


+def test_turn_hook_context_preserves_legacy_positional_arguments(tmp_path) -> None:
+    context = AgentTurnHookContext(
+        None,
+        tmp_path,
+        "sdk",
+        "chat-a",
+        "message-1",
+        "sdk:chat-a",
+        {"trusted": True},
+        True,
+    )
+
+    assert context.metadata == {"trusted": True}
+    assert context.ephemeral is True
+    assert context.attributes == {}
+
+
@pytest.mark.asyncio
 async def test_turn_hook_builder_runs_progress_hook_before_extra_hooks() -> None:
    events: list[str] = []
@@ -65,6 +82,7 @@ async def test_turn_hook_builder_runs_factories_with_matching_registration_order
        session_key="websocket:chat-1",
        workspace=tmp_path,
        metadata={"source": "test"},
+        attributes={"tenant": "acme"},
        registered_hook_factories=[factory("registered_factory")],
        registered_hooks=[RecordingHook(events, "registered")],
        turn_hook_factories=[factory("turn_factory")],
@@ -92,6 +110,10 @@ async def test_turn_hook_builder_runs_factories_with_matching_registration_order
        {"source": "test"},
        {"source": "test"},
    ]
+    assert [context.attributes for context in captured] == [
+        {"tenant": "acme"},
+        {"tenant": "acme"},
+    ]


@pytest.mark.asyncio
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
chengyongru	6ed4ccb68e	fix(agent): rebuild provider on preset switch	2026-07-29 01:41:28 +08:00
chengyongru	4e7c57eb1a	fix(config): warn on legacy model migration	2026-07-29 01:11:41 +08:00
chengyongru	8bd53d6e26	fix(config): enforce preset-only model selection	2026-07-29 00:46:23 +08:00
chengyongru	f239b45900	feat(config): add image-aware model presets	2026-07-29 00:02:21 +08:00
chengyongruandchengyongru	9070d7489a	fix(ci): scope PR path detection to head changes	2026-07-28 20:24:52 +08:00
chengyongruandGitHub	019d7816a7	fix(webui): animate reasoning drawer transitions (#5143 )	2026-07-28 19:13:16 +08:00
chengyongruandGitHub	24a392b671	fix(webui): open threads at latest message (#5142 )	2026-07-28 18:52:34 +08:00
chengyongruandGitHub	0c6c0438d4	feat(config): add actionable startup diagnostics and WebUI recovery (#5110 )	2026-07-28 18:52:05 +08:00
chengyongruandGitHub	76ab04ac48	fix(webui): keep streaming tail visible (#5140 )	2026-07-28 18:18:44 +08:00
chengyongruandchengyongru	1faf0826f6	fix(webui): keep composer stable while scrolling	2026-07-28 17:13:47 +08:00
chengyongruandchengyongru	ae089aa3ae	fix(webui): reconcile threads after browser resume	2026-07-28 16:25:08 +08:00
chengyongruandchengyongru	78cf68c291	fix(agent): snapshot active tasks before cancellation	2026-07-28 15:42:52 +08:00
Xubin Ren	ce3e532643	fix(sdk): use shared runtime event publisher	2026-07-28 15:30:28 +08:00
chengyongruandXubin Ren	ae7b4c8792	fix(sdk): narrow persisted turn callback API	2026-07-28 15:30:28 +08:00
chengyongruandXubin Ren	fd17c1352a	fix(sdk): harden host integration contracts	2026-07-28 15:30:28 +08:00
chengyongruandXubin Ren	c050955ae3	feat(sdk): add host integration extension points	2026-07-28 15:30:28 +08:00
chengyongruandGitHub	12f828ea3d	fix(agent): read document attachments on demand (#5122 )	2026-07-28 13:33:06 +08:00
chengyongruandchengyongru	096a86a7f4	docs: move README title above introduction	2026-07-28 13:06:09 +08:00
Xubin Ren	8ef5bc414d	docs(readme): preserve Render launch anchor	2026-07-28 12:44:45 +08:00
Xubin Ren	328251289d	docs(deploy): explain Render setup and updates	2026-07-28 12:44:45 +08:00
Xubin Ren	7a741e2b50	docs(readme): add one-click deployment section	2026-07-28 12:44:45 +08:00
Xubin Ren	60e67fbe0f	docs(readme): surface one-click Render deployment	2026-07-28 12:44:45 +08:00
chengyongruandchengyongru	fa5d27696a	fix(webui): rank skill autocomplete results	2026-07-28 11:36:10 +08:00
chengyongruandGitHub	ef9e687f19	refactor(core): remove redundant runtime scaffolding (#5127 )	2026-07-28 11:07:58 +08:00
chengyongru	4c77126b3d	docs: improve README landing page	2026-07-28 01:48:34 +08:00
chengyongruandGitHub	6bc454dab4	fix(webui): prevent composer resize scroll jitter (#5121 )	2026-07-28 01:01:49 +08:00
chengyongruandchengyongru	b99e0f937e	fix(webui): soften model selector emphasis	2026-07-27 23:13:14 +08:00
chengyongruandGitHub	f78ad59ed0	fix(memory): preserve Dream input integrity (#5114 )	2026-07-27 21:37:13 +08:00
chengyongruandchengyongru	e819b7eea4	fix(webui): stabilize repeated model preset rows	2026-07-27 18:11:10 +08:00
chengyongruandchengyongru	3f808d0a68	docs: improve README discoverability	2026-07-27 15:57:03 +08:00
yu-xin-candXubin Ren	7fd28c9f06	fix(memory): preserve unprocessed dream history	2026-07-27 15:47:21 +08:00
chengyongruandGitHub	c13df29457	feat(memory): restore Dream model preset override (#5107 )	2026-07-27 14:43:25 +08:00
chengyongruandGitHub	281b4b7f0b	chore: remove expired v0.3.1 compatibility shims (#5106 )	2026-07-27 13:53:04 +08:00
chengyongruandchengyongru	39348dfafe	refactor(agent): remove dead lifecycle scaffolding	2026-07-27 12:00:06 +08:00