feat(webui): add persistent Quick Chat

When an LLM response arrives with finish_reason='length' and has_tool_calls
but blank text content (e.g. the model spent its whole output budget on a
tool call whose closing tag was truncated), the runner dropped the tool
calls and then misrouted the blank response into the empty-response retry
branch. Retrying the same prompt cannot recover from output-budget
exhaustion, so every retry hit the same length ceiling and the turn ended
in the generic apology.

The length-recovery branch was gated on 'finish_reason == length and not
is_blank_text(clean)', so a blank-but-truncated turn could never reach it.

- The empty-response retry branch now excludes finish_reason == 'length'
  (in addition to 'error').
- The length-recovery branch no longer requires non-blank content, so a
  blank-but-truncated turn enters recovery and appends
  build_length_recovery_message (which handles a blank tail safely).

Adds a regression test asserting the length-recovery path is taken; it
fails on the unfixed code and passes with the fix.

Fixes #5133

docs/architecture.md

@@ -146,7 +146,6 @@ Defaults:
 | Memory | `<workspace>/memory/` |
 | Cron store | `<workspace>/cron/jobs.json` |
 | WebUI/media/log runtime data | config directory subdirectories such as `webui/`, `media/`, and `logs/` |
-| Resource path aliases | `<config-dir>/resources/<view-id>/` (best-effort, derived state) |
 
 The schema accepts both camelCase and snake_case keys, but saves config with camelCase aliases.
 
@@ -168,10 +167,6 @@ and receive only capability-specific read access to built-in/agent skills and
 the exact agent history file. Keep those cross-root capabilities read-only and
 explicit; do not treat the entire agent workspace as an allowed root.
 
-Resource path aliases are created outside the workspace and resolve to these
-same canonical targets. Authorization must continue to follow the resolved
-target; the alias root itself must never be treated as a blanket capability.
-
 ## Memory and Sessions
 
 Session history is the near-term conversation replay. Memory is the longer-term workspace state.

docs/concepts.md

@@ -55,35 +55,6 @@ When no separate project is selected, one directory normally serves both roles.
 Selecting a project changes the working context for that chat; it does not create
 a second agent or relocate the configured agent workspace.
 
-### Resource Path Aliases
-
-When an agent runtime starts, nanobot makes a best-effort filesystem view under
-the active config directory:
-
-```text
-<config-dir>/resources/<view-id>/
-├── agent   -> <agent-workspace>
-├── media   -> <config-dir>/media
-└── package -> <installed-nanobot-package>
-```
-
-`<view-id>` is deterministic for the config, agent workspace, and installed
-package paths. Separate workspaces or Python environments therefore receive
-separate views instead of competing for a mutable `current` link. Project files
-are not linked into this view; relative paths continue to resolve from the
-effective project workspace.
-
-These links are convenient names, not a new permission boundary. Restricted
-file access still checks the resolved target, and a shell sandbox may not expose
-the aliases at all. Full-access prompts use the agent alias for profile, memory,
-history, and custom-skill paths; restricted prompts expose only alias subtrees
-that are already readable and retain canonical exact-file paths where required.
-Nanobot keeps canonical paths in config and runtime state, continues to accept
-real paths, and falls back to them when links are unavailable. Creating the view
-never blocks startup and never replaces an existing unowned file or directory.
-The `resources/` tree is derived state, so backup and indexing tools should skip
-it or preserve its links instead of following them into their targets.
-
 ## Config Format
 
 `config.json` accepts both camelCase and snake_case keys. The docs use camelCase because nanobot writes config back to disk with camelCase aliases, for example `apiKey`, `modelPresets`, `intervalS`, and `maxToolResultChars`.

docs/configuration.md

@@ -348,6 +348,20 @@ Valid `apiType` values are exactly `auto`, `chat_completions`, and `responses`.
 
 </details>
 
+<a id="responses-state-and-compaction"></a>
+
+### Responses conversation state and compaction
+
+Providers that use the Responses API can keep reasoning context across a
+conversation, which helps with multi-step tasks. Supported providers can also
+compact long conversations automatically.
+
+nanobot preserves Responses conversation state automatically for OpenAI
+Responses, OpenAI Codex, Azure OpenAI, and compatible GitHub Copilot models.
+Native compaction is also automatic when the provider supports it. The
+threshold is derived from the active model's context window and reserved output
+headroom; no provider configuration is required.
+
 <details>
 <summary><b>Azure OpenAI</b></summary>
 

docs/providers.md

@@ -229,7 +229,7 @@ Arbitrary custom provider names are OpenAI-compatible only; they do not use the
 }
 ```
 
-`providers.openai.apiType` may be set when you need to force a specific OpenAI API surface. Other providers reject `apiType`; leave it unset outside `providers.openai`. Replace the model with a model ID available to your OpenAI account.
+`providers.openai.apiType` may be set when you need to force a specific OpenAI API surface. Other providers reject `apiType`; leave it unset outside `providers.openai`. Replace the model with a model ID available to your OpenAI account. Direct OpenAI Responses, OpenAI Codex, Azure OpenAI Responses, and eligible GitHub Copilot models share [opaque Responses state retention](./configuration.md#responses-state-and-compaction); native compaction is enabled only where the backend supports it.
 
 ### Custom OpenAI-Compatible Endpoint
 
@@ -458,7 +458,7 @@ For GitHub Copilot:
 nanobot provider login github-copilot --set-main
 ```
 
-Each command authenticates the selected provider and makes its current default model active. OAuth providers are not valid automatic fallbacks. See [`troubleshooting.md`](./troubleshooting.md#provider-and-model-problems) for proxy, headless-login, model-name, and config-key errors.
+Each command authenticates the selected provider and makes its current default model active. OpenAI Codex and eligible GitHub Copilot models participate in [Responses state retention](./configuration.md#responses-state-and-compaction), while native compaction remains provider-capability-specific. OAuth providers are not valid automatic fallbacks. See [`troubleshooting.md`](./troubleshooting.md#provider-and-model-problems) for proxy, headless-login, model-name, and config-key errors.
 
 ## Provider Resolution
 

docs/troubleshooting.md

@@ -150,7 +150,7 @@ If you need a known-good snippet instead of diagnosis, use [`provider-cookbook.m
 | 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`. |
 | Codex OAuth needs a proxy | Set `providers.openaiCodex.proxy` before running the login command. The proxy applies to login, token refresh, and Codex API requests. |
-| Codex login runs on a remote/headless machine | Open the printed URL in a local browser, then paste the final `http://localhost:1455/auth/callback?...` URL back into the terminal. |
+| Codex login runs on a remote/headless machine | In the WebUI, open ChatGPT in your local browser; when the localhost callback page cannot load, copy the full `http://localhost:1455/auth/callback?...` URL from the address bar and paste it into the WebUI dialog. From the CLI, open the printed URL locally and paste the same callback URL back into the terminal. |
 | Codex login runs in Docker | Start the container with `docker run -it` so the OAuth flow has an interactive terminal. |
 | Codex says a model is not supported with a ChatGPT account | Use provider `openai_codex` with a Codex model such as `openai-codex/gpt-5.6-sol`. Do not use the direct-API `openai/...` prefix with Codex OAuth. |
 | Config says `providers.openai_codex` conflicts with the built-in provider | Under `providers`, keep only the canonical `openaiCodex` settings key and remove a duplicate `openai_codex` key. A model preset's `provider` value remains `openai_codex`. |

nanobot/agent/autocompact.py

@@ -31,9 +31,19 @@ class AutoCompact:
                     now: datetime | None = None) -> bool:
         if self._ttl <= 0 or not ts:
             return False
-        if isinstance(ts, str):
-            ts = datetime.fromisoformat(ts)
-        return ((now or datetime.now()) - ts).total_seconds() >= self._ttl * 60
+        try:
+            if isinstance(ts, str):
+                ts = datetime.fromisoformat(ts)
+            current = now or datetime.now()
+            if getattr(ts, "tzinfo", None) is not None or current.tzinfo is not None:
+                idle_seconds = current.timestamp() - ts.timestamp()
+            else:
+                idle_seconds = (current - ts).total_seconds()
+        except (OSError, OverflowError, TypeError, ValueError):
+            # list_sessions() forwards raw persisted metadata; an unusable value
+            # must not escape the idle scan and stop the agent loop.
+            return False
+        return idle_seconds >= self._ttl * 60
 
     def _has_compactable_idle_tail(self, key: str) -> bool:
         session = self.sessions.get_or_create(key)

nanobot/agent/context.py

@@ -1,7 +1,5 @@
 """Context builder for assembling agent prompts."""
 
-from __future__ import annotations
-
 import base64
 import mimetypes
 import platform
@@ -9,17 +7,12 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence, cast
 
 from nanobot.agent.memory import MemoryStore
-from nanobot.agent.skills import (
-    ResourceViewMode,
-    SkillsLoader,
-    build_resource_aliases_section,
-)
+from nanobot.agent.skills import SkillsLoader
 from nanobot.agent.tools import image_generation as image_generation_tools
 from nanobot.agent.tools import mcp as mcp_tools
 from nanobot.agent.tools.registry import ToolRegistry
 from nanobot.apps.cli import utils as cli_app_utils
 from nanobot.bus.events import InboundMessage
-from nanobot.resource_links import ResourceView
 from nanobot.runtime_context import (
     RUNTIME_CONTEXT_END,
     RUNTIME_CONTEXT_MESSAGE_META,
@@ -68,23 +61,11 @@ class ContextBuilder:
     _MAX_HISTORY_TOKENS = 8_000  # hard cap on recent history section size (tokens)
     _RUNTIME_CONTEXT_END = RUNTIME_CONTEXT_END
 
-    def __init__(
-        self,
-        workspace: Path,
-        timezone: str | None = None,
-        disabled_skills: list[str] | None = None,
-        *,
-        resource_view: ResourceView | None = None,
-    ):
+    def __init__(self, workspace: Path, timezone: str | None = None, disabled_skills: list[str] | None = None):
         self.workspace = workspace
         self.timezone = timezone
-        self.resource_view = resource_view
-        self.memory = MemoryStore(workspace, resource_view=resource_view)
-        self.skills = SkillsLoader(
-            workspace,
-            disabled_skills=set(disabled_skills) if disabled_skills else None,
-            resource_view=resource_view,
-        )
+        self.memory = MemoryStore(workspace)
+        self.skills = SkillsLoader(workspace, disabled_skills=set(disabled_skills) if disabled_skills else None)
 
     def build_system_prompt(
         self,
@@ -96,24 +77,10 @@ class ContextBuilder:
         include_memory_recent_history: bool = True,
         session_key: str | None = None,
         unified_session: bool = False,
-        resource_view_mode: ResourceViewMode | None = None,
     ) -> str:
         """Build the system prompt from identity, bootstrap files, memory, and skills."""
         root = workspace or self.workspace
-        parts = [
-            self._get_identity(
-                channel=channel,
-                workspace=root,
-                resource_view_mode=resource_view_mode,
-            )
-        ]
-
-        resource_aliases = build_resource_aliases_section(
-            self.resource_view,
-            resource_view_mode,
-        )
-        if resource_aliases:
-            parts.append(resource_aliases)
+        parts = [self._get_identity(channel=channel, workspace=root)]
 
         bootstrap = self._load_bootstrap_files(root)
         if bootstrap:
@@ -159,24 +126,11 @@ class ContextBuilder:
 
         return "\n\n---\n\n".join(parts)
 
-    def _get_identity(
-        self,
-        channel: str | None = None,
-        workspace: Path | None = None,
-        *,
-        resource_view_mode: ResourceViewMode | None = None,
-    ) -> str:
+    def _get_identity(self, channel: str | None = None, workspace: Path | None = None) -> str:
         """Get the core identity section."""
         root = workspace or self.workspace
         workspace_path = str(root.expanduser().resolve())
         agent_workspace_path = str(self.workspace.expanduser().resolve())
-        agent_resource_path = agent_workspace_path
-        if (
-            resource_view_mode == "full"
-            and self.resource_view is not None
-            and self.resource_view.agent is not None
-        ):
-            agent_resource_path = str(self.resource_view.agent)
         system = platform.system()
         runtime = f"{'macOS' if system == 'Darwin' else system} {platform.machine()}, Python {platform.python_version()}"
 
@@ -184,7 +138,6 @@ class ContextBuilder:
             "agent/identity.md",
             workspace_path=workspace_path,
             agent_workspace_path=agent_workspace_path,
-            agent_resource_path=agent_resource_path,
             runtime=runtime,
             platform_policy=render_template("agent/platform_policy.md", system=system),
             channel=channel or "",
@@ -264,7 +217,6 @@ class ContextBuilder:
         include_memory_recent_history: bool = True,
         session_key: str | None = None,
         unified_session: bool = False,
-        resource_view_mode: ResourceViewMode | None = None,
     ) -> list[dict[str, Any]]:
         """Build the complete message list for an LLM call."""
         root = workspace or self.workspace
@@ -273,9 +225,6 @@ class ContextBuilder:
             if current_role == "user"
             else []
         )
-        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: list[dict[str, Any]] = [
             {
                 "role": "system",
@@ -287,26 +236,51 @@ class ContextBuilder:
                     include_memory_recent_history=include_memory_recent_history,
                     session_key=session_key,
                     unified_session=unified_session,
-                    resource_view_mode=resource_view_mode,
                 ),
             },
             *history,
         ]
+        current = self.build_current_message(
+            current_message,
+            media=media,
+            current_role=current_role,
+            runtime_context_blocks=runtime_context_blocks,
+        )
         if messages[-1].get("role") == current_role:
             last = dict(messages[-1])
-            last["content"] = self._merge_message_content(last.get("content"), merged)
-            if current_role == "user" and runtime_context_meta is not None:
+            last["content"] = self._merge_message_content(
+                last.get("content"),
+                current.get("content"),
+            )
+            current_meta = current.get("_meta")
+            if current_role == "user" and isinstance(current_meta, dict):
                 internal_meta = dict(last.get("_meta") or {})
-                internal_meta[RUNTIME_CONTEXT_MESSAGE_META] = runtime_context_meta
+                internal_meta.update(cast(dict[str, Any], current_meta))
                 last["_meta"] = internal_meta
             messages[-1] = last
             return messages
-        current: dict[str, Any] = {"role": current_role, "content": merged}
-        if current_role == "user" and runtime_context_meta is not None:
-            current["_meta"] = {RUNTIME_CONTEXT_MESSAGE_META: runtime_context_meta}
         messages.append(current)
         return messages
 
+    def build_current_message(
+        self,
+        current_message: str,
+        *,
+        media: list[str] | None = None,
+        current_role: str = "user",
+        runtime_context_blocks: Sequence[RuntimeContextBlock] | None = None,
+    ) -> dict[str, Any]:
+        """Build only the fresh turn message without merging it into history."""
+        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(content, blocks)
+        current: dict[str, Any] = {"role": current_role, "content": merged}
+        if current_role == "user" and runtime_context_meta is not None:
+            current["_meta"] = {
+                RUNTIME_CONTEXT_MESSAGE_META: runtime_context_meta,
+            }
+        return current
+
     def build_user_content(
         self,
         text: str,

nanobot/agent/loop.py

@@ -9,6 +9,7 @@ import dataclasses
 import inspect
 import os
 import time
+import weakref
 from collections.abc import Coroutine, Iterable, Mapping
 from contextlib import AbstractContextManager, ExitStack, nullcontext, suppress
 from dataclasses import dataclass, field
@@ -48,7 +49,7 @@ from nanobot.bus.queue import MessageBus
 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
+from nanobot.providers.base import LLMProvider, ProviderConversationState
 from nanobot.providers.factory import ProviderSnapshot
 from nanobot.runtime_context import (
     RUNTIME_CONTEXT_HISTORY_META,
@@ -93,7 +94,6 @@ from nanobot.utils.runtime import (
 )
 
 if TYPE_CHECKING:
-    from nanobot.agent.skills import ResourceViewMode
     from nanobot.agent.tools.mcp import MCPConnection
     from nanobot.config.schema import (
         ChannelsConfig,
@@ -103,11 +103,10 @@ if TYPE_CHECKING:
         ToolsConfig,
     )
     from nanobot.cron.service import CronService
-    from nanobot.resource_links import ResourceView
-    from nanobot.security.workspace_access import WorkspaceScope
     from nanobot.triggers.local_store import LocalTriggerStore
 
 _T = TypeVar("_T")
+_SUBAGENT_PROVIDER_TASK_META = "subagent_provider_task_id"
 
 
 class TurnKind(Enum):
@@ -128,6 +127,7 @@ class TurnContext:
 
     history: list[dict[str, Any]] = field(default_factory=list)
     initial_messages: list[dict[str, Any]] = field(default_factory=list)
+    provider_state: ProviderConversationState | None = field(default=None, repr=False)
     request_context: RequestContext | None = None
     runtime_context_blocks: list[RuntimeContextBlock] = field(default_factory=list)
     attributes: dict[str, Any] = field(default_factory=dict)
@@ -245,6 +245,8 @@ class AgentLoop:
 
     _RUNTIME_CHECKPOINT_KEY = "runtime_checkpoint"
     _PENDING_USER_TURN_KEY = "pending_user_turn"
+    _PROVIDER_STATE_CHECKPOINT_VERSION_KEY = "provider_state_checkpoint_version"
+    _PROVIDER_STATE_CHECKPOINT_VERSION = "v1"
 
     def __init__(
         self,
@@ -288,7 +290,6 @@ class AgentLoop:
         restart_mode: str = "auto",
         local_trigger_store: LocalTriggerStore | None = None,
         idle_compact_check_interval_seconds: int = 0,
-        resource_view: ResourceView | None = None,
     ):
         from nanobot.config.schema import ToolsConfig
 
@@ -360,7 +361,6 @@ class AgentLoop:
         self.cron_service = cron_service
         self.local_trigger_store = local_trigger_store
         self.restrict_to_workspace = restrict_to_workspace
-        self.resource_view = resource_view
         self.workspace_scopes = WorkspaceScopeResolver(
             default_workspace=workspace,
             default_restrict_to_workspace=restrict_to_workspace,
@@ -370,12 +370,7 @@ class AgentLoop:
         self._extra_hooks: list[AgentHook] = hooks or []
         self._hook_factories: list[AgentTurnHookFactory] = hook_factories or []
 
-        self.context = ContextBuilder(
-            workspace,
-            timezone=timezone,
-            disabled_skills=disabled_skills,
-            resource_view=resource_view,
-        )
+        self.context = ContextBuilder(workspace, timezone=timezone, disabled_skills=disabled_skills)
         self.sessions = session_manager or SessionManager(workspace)
         self.sessions.set_file_cap_archiver(self.context.memory.raw_archive)
         self.tools = ToolRegistry()
@@ -395,7 +390,6 @@ class AgentLoop:
             max_concurrent_subagents=max_concurrent_subagents,
             fail_on_tool_error=fail_on_tool_error,
             llm_wall_timeout_for_session=lambda sk: runner_wall_llm_timeout_s(self.sessions, sk),
-            resource_view=resource_view,
         )
         self._unified_session = unified_session
         self._running = False
@@ -405,7 +399,9 @@ class AgentLoop:
         self._runtime_context_providers: list[RuntimeContextProvider] = []
         self._active_tasks: dict[str, set[asyncio.Task[Any]]] = {}
         self._background_tasks: set[asyncio.Task[Any]] = set()
-        self._session_locks: dict[str, asyncio.Lock] = {}
+        self._session_locks: weakref.WeakValueDictionary[str, asyncio.Lock] = (
+            weakref.WeakValueDictionary()
+        )
         # Per-session pending queues for mid-turn message injection.
         # When a session has an active task, new messages for that session
         # are routed here instead of creating a new task.
@@ -727,20 +723,8 @@ class AgentLoop:
             include_memory_recent_history=not ctx.ephemeral,
             session_key=ctx.session.key,
             unified_session=self._unified_session,
-            resource_view_mode=self._resource_view_mode_for_scope(scope),
         )
 
-    def _resource_view_mode_for_scope(
-        self,
-        scope: WorkspaceScope,
-    ) -> ResourceViewMode | None:
-        """Return the alias visibility supported by this turn's tool boundary."""
-        if self.resource_view is None:
-            return None
-        if scope.restrict_to_workspace or bool(self.exec_config.sandbox):
-            return "restricted"
-        return "full"
-
     def _request_context_for_turn(self, ctx: TurnContext) -> RequestContext:
         assert ctx.session is not None
         scope = self.workspace_scopes.for_turn(
@@ -877,6 +861,7 @@ class AgentLoop:
         turn_scopes: list[AbstractContextManager[Any]] | None = None,
         tools: ToolRegistry | None = None,
         request_context: RequestContext | None = None,
+        provider_state: ProviderConversationState | None = None,
     ) -> tuple[str | None, list[str], list[dict[str, Any]], str, bool]:
         """Run the agent iteration loop.
 
@@ -892,7 +877,18 @@ class AgentLoop:
         async def _checkpoint(payload: dict[str, Any]) -> None:
             if session is None:
                 return
-            self._set_runtime_checkpoint(session, payload)
+            public_payload = dict(payload)
+            private_state = public_payload.pop("provider_state", None)
+            public_payload.pop(self._PROVIDER_STATE_CHECKPOINT_VERSION_KEY, None)
+            if "provider_state" in payload and (
+                private_state is None
+                or isinstance(private_state, ProviderConversationState)
+            ):
+                session.provider_state = private_state
+                public_payload[self._PROVIDER_STATE_CHECKPOINT_VERSION_KEY] = (
+                    self._PROVIDER_STATE_CHECKPOINT_VERSION
+                )
+            self._set_runtime_checkpoint(session, public_payload)
 
         async def _drain_pending(*, limit: int = _MAX_INJECTIONS_PER_TURN) -> list[dict[str, Any]]:
             """Drain follow-up messages from the pending queue.
@@ -1090,6 +1086,7 @@ class AgentLoop:
                     session_metadata=session_metadata,
                     message_metadata=metadata,
                 ),
+                provider_state=provider_state,
             ))
         finally:
             turn_scope_stack.close()
@@ -1097,6 +1094,8 @@ class AgentLoop:
             reset_request_context(request_token)
             reset_file_states(file_state_token)
         self._last_usage = result.usage
+        if session is not None and not ephemeral:
+            session.provider_state = result.provider_state
         if result.stop_reason == "max_iterations":
             logger.warning("Max iterations ({}) reached", self.max_iterations)
             should_stream = turn_continuation.should_stream_budget_response(
@@ -1126,7 +1125,7 @@ class AgentLoop:
             return
         self._next_idle_compact_check_at = now + self._idle_compact_check_interval_s
         self.auto_compact.check_expired(
-            self._schedule_background,
+            self.schedule_background,
             self.runtime_for_session,
             active_session_keys=self._pending_queues.keys(),
         )
@@ -1229,7 +1228,7 @@ class AgentLoop:
         session_key = self._effective_session_key(msg)
         if session_key != msg.session_key:
             msg = dataclasses.replace(msg, session_key_override=session_key)
-        lock = self._session_locks.setdefault(session_key, asyncio.Lock())
+        lock = self._get_session_lock(session_key)
         gate = self._concurrency_gate or nullcontext()
 
         delivery = self.turn_delivery_factory.unrouted(msg, session_key)
@@ -1359,7 +1358,7 @@ class AgentLoop:
         if errors:
             raise BaseExceptionGroup("failed to close agent resources", errors)
 
-    def _schedule_background(self, coro: Coroutine[Any, Any, Any]) -> None:
+    def schedule_background(self, coro: Coroutine[Any, Any, Any]) -> None:
         """Schedule a coroutine as a tracked background task (drained on shutdown)."""
         task = asyncio.create_task(coro)
         self._background_tasks.add(task)
@@ -1680,14 +1679,24 @@ class AgentLoop:
             "extend_to_user": is_subagent,
         }
         ctx.history = session.get_history(**_hist_kwargs)
+        stored_state = session.provider_state
+        subagent_followup_persisted = False
         if is_subagent:
             # Keep the durable internal delivery as an assistant record, but
             # present this completion to the model as fresh follow-up input.
             # Providers without assistant-prefill support drop trailing
             # assistant messages, so using the persisted record as the current
             # prompt would hide an independently dispatched subagent result.
-            if self._persist_subagent_followup(session, ctx.msg):
+            subagent_followup_persisted = self._persist_subagent_followup(
+                session,
+                ctx.msg,
+            )
+            if subagent_followup_persisted:
                 logger.debug("Subagent result persisted for session {}", ctx.session_key)
+                # Establish a durable, replay-safe baseline before any fallible
+                # provider compatibility or prompt assembly work. A compatible
+                # staged state replaces this in a second atomic save below.
+                session.provider_state = None
                 self.sessions.save(session)
             ctx.input_persisted_early = True
         ctx.delivery.record_runtime(runtime)
@@ -1695,13 +1704,65 @@ class AgentLoop:
         ctx.request_context = self._request_context_for_turn(ctx)
         if ctx.kind is TurnKind.USER:
             ctx.runtime_context_blocks = await self._resolve_runtime_context_for_turn(ctx)
-        ctx.initial_messages = self._build_initial_messages(ctx)
+        staged_provider_state = False
+        if stored_state is not None and runtime.provider.can_resume_conversation_state(
+            stored_state,
+            runtime.model,
+        ):
+            current_provider_message = self.context.build_current_message(
+                ctx.msg.content,
+                media=ctx.msg.media if ctx.kind is TurnKind.USER and ctx.msg.media else None,
+                runtime_context_blocks=ctx.runtime_context_blocks,
+            )
+            task_id = ctx.msg.metadata.get("subagent_task_id") if is_subagent else None
+            already_staged = False
+            if isinstance(task_id, str) and task_id:
+                internal_meta = current_provider_message.get("_meta")
+                current_provider_message["_meta"] = {
+                    **(
+                        cast(dict[str, Any], internal_meta)
+                        if isinstance(internal_meta, dict)
+                        else {}
+                    ),
+                    _SUBAGENT_PROVIDER_TASK_META: task_id,
+                }
+                already_staged = any(
+                    isinstance(message.get("_meta"), dict)
+                    and cast(dict[str, Any], message["_meta"]).get(
+                        _SUBAGENT_PROVIDER_TASK_META
+                    )
+                    == task_id
+                    for message in stored_state.pending_messages
+                )
+            ctx.provider_state = (
+                stored_state
+                if already_staged
+                else stored_state.with_pending_messages([
+                    *stored_state.pending_messages,
+                    current_provider_message,
+                ])
+            )
+            if (
+                not ctx.ephemeral
+                and (ctx.kind is TurnKind.USER or subagent_followup_persisted)
+            ):
+                session.provider_state = ctx.provider_state
+                staged_provider_state = True
+        elif stored_state is not None:
+            session.provider_state = None
         if ctx.kind is TurnKind.USER:
             ctx.input_persisted_early = self._persist_user_message_early(
                 ctx.msg,
                 session,
                 runtime_context_blocks=ctx.runtime_context_blocks,
             )
+            if staged_provider_state and not ctx.input_persisted_early:
+                session.provider_state = stored_state
+        elif subagent_followup_persisted and staged_provider_state:
+            # Upgrade the replay-safe baseline to the resumable state before
+            # prompt assembly and the first model checkpoint.
+            self.sessions.save(session)
+        ctx.initial_messages = self._build_initial_messages(ctx)
 
         if ctx.on_progress is None:
             ctx.on_progress = ctx.delivery.progress_callback()
@@ -1735,6 +1796,7 @@ class AgentLoop:
             turn_scopes=ctx.turn_scopes,
             tools=ctx.tools,
             request_context=ctx.request_context,
+            provider_state=ctx.provider_state,
         )
         final_content, _, all_msgs, stop_reason, had_injections = result
         ctx.final_content = final_content
@@ -1775,7 +1837,7 @@ class AgentLoop:
             session.enforce_file_cap(
                 on_archive=partial(self.context.memory.raw_archive, session_key=ctx.session_key)
             )
-            self._schedule_background(
+            self.schedule_background(
                 self.consolidator.maybe_consolidate_by_tokens(
                     session,
                     runtime=runtime,
@@ -2072,7 +2134,36 @@ class AgentLoop:
             ):
                 overlap = size
                 break
-        session.messages.extend(restored_messages[overlap:])
+        appended_messages = restored_messages[overlap:]
+        session.messages.extend(appended_messages)
+        assistant_message_data = (
+            cast(dict[str, Any], assistant_message)
+            if isinstance(assistant_message, dict)
+            else None
+        )
+        provider_state_is_synchronized = (
+            checkpoint_data.get(self._PROVIDER_STATE_CHECKPOINT_VERSION_KEY)
+            == self._PROVIDER_STATE_CHECKPOINT_VERSION
+        )
+        phase = checkpoint_data.get("phase")
+        exact_final_response = (
+            phase == "final_response"
+            and assistant_message_data is not None
+            and assistant_message_data.get("role") == "assistant"
+            and not bool(checkpoint_data.get("completed_tool_results"))
+            and not bool(checkpoint_data.get("pending_tool_calls"))
+        )
+        exact_completed_tools = (
+            phase == "tools_completed"
+            and assistant_message_data is not None
+            and assistant_message_data.get("role") == "assistant"
+            and not bool(checkpoint_data.get("pending_tool_calls"))
+        )
+        if not (
+            provider_state_is_synchronized
+            and (exact_final_response or exact_completed_tools)
+        ):
+            session.provider_state = None
 
         self._clear_pending_user_turn(session)
         self._clear_runtime_checkpoint(session)
@@ -2093,6 +2184,7 @@ class AgentLoop:
                     "timestamp": datetime.now().isoformat(),
                 }
             )
+            session.provider_state = None
             session.updated_at = datetime.now()
 
         self._clear_pending_user_turn(session)
@@ -2131,7 +2223,7 @@ class AgentLoop:
             content=content, media=media or [], metadata=metadata,
         )
         # Share the dispatch lock so direct calls serialize with bus turns.
-        lock = self._session_locks.setdefault(session_key, asyncio.Lock())
+        lock = self._get_session_lock(session_key)
         try:
             async with lock:
                 kwargs: dict[str, Any] = {
@@ -2162,3 +2254,11 @@ class AgentLoop:
         finally:
             await self.runtime_event_publisher.run_status_changed(msg, session_key, "idle")
             self.runtime_event_publisher.clear_turn(session_key)
+
+    def _get_session_lock(self, session_key: str) -> asyncio.Lock:
+        """Return the shared lock while allowing idle session entries to expire."""
+        lock = self._session_locks.get(session_key)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._session_locks[session_key] = lock
+        return lock

nanobot/agent/memory.py

@@ -20,7 +20,6 @@ from typing import TYPE_CHECKING, Any, Callable, Iterator, cast
 
 from loguru import logger
 
-from nanobot.resource_links import ResourceView
 from nanobot.runtime_context import public_history_messages
 from nanobot.session.manager import Session, SessionManager
 from nanobot.utils.gitstore import GitStore
@@ -91,16 +90,9 @@ class MemoryStore:
         r"^\[\d{4}-\d{2}-\d{2}[^\]]*\]\s+[A-Z][A-Z0-9_]*(?:\s+\[tools:\s*[^\]]+\])?:"
     )
 
-    def __init__(
-        self,
-        workspace: Path,
-        max_history_entries: int = _DEFAULT_MAX_HISTORY,
-        *,
-        resource_view: ResourceView | None = None,
-    ):
+    def __init__(self, workspace: Path, max_history_entries: int = _DEFAULT_MAX_HISTORY):
         self.workspace = workspace
         self.max_history_entries = max_history_entries
-        self.resource_view = resource_view
         self.memory_dir = ensure_dir(workspace / "memory")
         self.memory_file = self.memory_dir / "MEMORY.md"
         self.history_file = self.memory_dir / "history.jsonl"
@@ -562,18 +554,13 @@ class MemoryStore:
         return has_workspace_prompt_override(self.dream_prompt_file)
 
     @staticmethod
-    def default_dream_prompt(resource_view: ResourceView | None = None) -> str:
+    def default_dream_prompt() -> str:
         from nanobot.agent.skills import BUILTIN_SKILLS_DIR
 
-        skill_creator_path = BUILTIN_SKILLS_DIR / "skill-creator" / "SKILL.md"
-        if resource_view is not None and resource_view.package is not None:
-            skill_creator_path = (
-                resource_view.package / "skills" / "skill-creator" / "SKILL.md"
-            )
         return render_template(
             "agent/dream.md",
             strip=True,
-            skill_creator_path=str(skill_creator_path),
+            skill_creator_path=str(BUILTIN_SKILLS_DIR / "skill-creator" / "SKILL.md"),
         )
 
     def _dream_template(self) -> str:
@@ -590,7 +577,7 @@ class MemoryStore:
                     WORKSPACE_PROMPT_MAX_CHARS, original_chars,
                 )
             return text
-        return self.default_dream_prompt(self.resource_view)
+        return self.default_dream_prompt()
 
     def build_dream_prompt(self, *, max_entries: int = 20) -> tuple[str, int] | None:
         """Build the Dream prompt with unprocessed history context.
@@ -820,7 +807,7 @@ _HISTORY_ENTRY_HARD_CAP = 64_000      # emergency cap in append_history
 
 
 class Consolidator:
-    """Lightweight consolidation: summarizes evicted messages into history.jsonl."""
+    """Summarize compacted messages into history.jsonl."""
 
     _MAX_CONSOLIDATION_ROUNDS = 5
 
@@ -944,6 +931,7 @@ class Consolidator:
             session_key=session.key,
         )
         session.last_consolidated = end_idx
+        session.provider_state = None
         self.sessions.save(session)
         return summary
 
@@ -1011,14 +999,9 @@ class Consolidator:
         session_key: str | None = None,
         summary_messages: list[dict[str, Any]] | None = None,
     ) -> str | None:
-        """Summarize messages via LLM and append to history.jsonl.
+        """Summarize messages and append the result to history.jsonl.
 
-        ``messages`` are the messages being archived (removed from the live
-        session); they are what gets raw-dumped if the LLM call fails.
-        ``summary_messages``, when given, lets callers include retained
-        messages in the summary without archiving them.
-
-        Returns the summary text on success, None if nothing to archive.
+        ``summary_messages`` adds context but is excluded from raw fallback.
         """
         if not messages:
             return None
@@ -1154,6 +1137,7 @@ class Consolidator:
                 if summary:
                     last_summary = summary
                 session.last_consolidated = end_idx
+                session.provider_state = None
                 self.sessions.save(session)
                 if not summary:
                     # LLM is degraded — stop hammering it this call;
@@ -1179,13 +1163,7 @@ class Consolidator:
         runtime: LLMRuntime,
         max_suffix: int = 8,
     ) -> str | None:
-        """Hard-truncate an idle session under the consolidation lock.
-
-        Used by AutoCompact so all session mutation goes through a single
-        lock-protected path.  Returns the summary text on success, ``None``
-        if the LLM failed (raw_archive fallback), or ``""`` if there was
-        nothing to archive.
-        """
+        """Archive an idle prefix and hide it from replay without deleting it."""
         lock = self.get_lock(session_key)
         async with lock:
             self.sessions.invalidate(session_key)
@@ -1205,24 +1183,21 @@ class Consolidator:
                 last_consolidated=0,
             )
             result = probe.retain_recent_legal_suffix(max_suffix, extend_to_user=True)
-            messages_to_keep = probe.messages
-            messages_to_remove = result.dropped[result.already_consolidated_count:]
+            visible_suffix = probe.messages
+            messages_to_remove = result.dropped
 
-            if not messages_to_remove and not messages_to_keep:
+            if not messages_to_remove:
                 self.sessions.save(session)
                 return ""
 
             last_active = session.updated_at
-            summary: str | None = ""
-            if messages_to_remove:
-                # Summarize the retained suffix too, but only remove/raw-dump
-                # the messages that are no longer kept in the live session.
-                summary = await self.archive(
-                    messages_to_remove,
-                    runtime=runtime,
-                    session_key=session_key,
-                    summary_messages=messages_to_summarize,
-                )
+            # The visible suffix informs the summary but stays out of raw fallback.
+            summary = await self.archive(
+                messages_to_remove,
+                runtime=runtime,
+                session_key=session_key,
+                summary_messages=messages_to_summarize,
+            )
 
             if summary and summary != "(nothing)":
                 session.metadata["_last_summary"] = {
@@ -1230,17 +1205,18 @@ class Consolidator:
                     "last_active": last_active.isoformat(),
                 }
 
-            session.messages = messages_to_keep
-            session.last_consolidated = 0
+            # Preserve history and advance only the replay boundary.
+            session.last_consolidated = len(session.messages) - len(visible_suffix)
+            session.provider_state = None
             self.sessions.save(session)
 
-            if messages_to_remove:
-                logger.info(
-                    "Idle-session compact for {}: archived={}, kept={}, summary={}",
-                    session_key,
-                    len(messages_to_remove),
-                    len(messages_to_keep),
-                    bool(summary),
-                )
+            logger.info(
+                "Idle-session compact for {}: archived={}, visible={}, retained={}, summary={}",
+                session_key,
+                len(messages_to_remove),
+                len(visible_suffix),
+                len(session.messages),
+                bool(summary),
+            )
 
             return summary

nanobot/agent/runner.py

@@ -19,7 +19,17 @@ from nanobot.agent.context_governance import (
 )
 from nanobot.agent.hook import AgentHook, AgentHookContext, AgentRunHookContext
 from nanobot.agent.tools.registry import ToolRegistry, is_tool_error_result
-from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+from nanobot.providers.base import (
+    LLMProvider,
+    LLMResponse,
+    ProviderCallContext,
+    ProviderConversationState,
+    ToolCallRequest,
+)
+from nanobot.providers.conversation_state import (
+    ProviderConversationStateController,
+    allows_conversation_message_merge,
+)
 from nanobot.runtime_context import (
     RUNTIME_CONTEXT_MESSAGE_META,
     detach_runtime_context,
@@ -104,6 +114,7 @@ class AgentRunSpec:
     goal_active_predicate: Callable[[], bool] | None = None
     goal_continue_message: GoalContinueMessage | None = None
     finalize_on_max_iterations: bool = True
+    provider_state: ProviderConversationState | None = None
 
 
 @dataclass(slots=True)
@@ -120,6 +131,7 @@ class AgentRunResult:
     had_injections: bool = False
     # Terminal tail to emit when the preceding final-content prefix was already streamed.
     pending_stream_content: str | None = None
+    provider_state: ProviderConversationState | None = field(default=None, repr=False)
 
 
 class AgentRunner:
@@ -161,6 +173,7 @@ class AgentRunner:
                 and messages[-1].get("role") == "user"
                 and not is_hidden_history_message(injection)
                 and not is_hidden_history_message(messages[-1])
+                and allows_conversation_message_merge(messages[-1])
             ):
                 merged = dict(messages[-1])
                 left_meta = merged.get("_meta")
@@ -231,6 +244,7 @@ class AgentRunner:
         assistant_message: dict[str, Any] | None,
         injection_cycles: int,
         *,
+        conversation_state: ProviderConversationStateController | None = None,
         phase: str = "after error",
         iteration: int | None = None,
         allow_goal_continue: bool = False,
@@ -258,16 +272,21 @@ class AgentRunner:
         if assistant_message is not None:
             messages.append(assistant_message)
             if iteration is not None:
+                checkpoint: dict[str, Any] = {
+                    "phase": "final_response",
+                    "iteration": iteration,
+                    "model": spec.runtime.model,
+                    "assistant_message": assistant_message,
+                    "completed_tool_results": [],
+                    "pending_tool_calls": [],
+                }
+                if conversation_state is not None:
+                    checkpoint["provider_state"] = conversation_state.checkpoint(
+                        messages
+                    )
                 await self._emit_checkpoint(
                     spec,
-                    {
-                        "phase": "final_response",
-                        "iteration": iteration,
-                        "model": spec.runtime.model,
-                        "assistant_message": assistant_message,
-                        "completed_tool_results": [],
-                        "pending_tool_calls": [],
-                    },
+                    checkpoint,
                 )
         self._append_injected_messages(messages, injections)
         if real_injection:
@@ -420,6 +439,12 @@ class AgentRunner:
         injection_cycles = 0
         compacted_tool_call_ids: set[str] = set()
         pending_stream_content: str | None = None
+        conversation_state = ProviderConversationStateController(
+            provider=spec.runtime.provider,
+            model=spec.runtime.model,
+            messages=messages,
+            state=spec.provider_state,
+        )
         governance_config = ContextGovernanceConfig(
             provider=spec.runtime.provider,
             model=spec.runtime.model,
@@ -450,7 +475,20 @@ class AgentRunner:
                 session_key=spec.session_key,
             )
             await hook.before_iteration(context)
-            response = await self._request_model(spec, messages_for_model, hook, context)
+            provider_context = conversation_state.prepare_request(
+                messages,
+                context_window_tokens=spec.runtime.context_window_tokens,
+                model_messages=messages_for_model,
+            )
+            response = await self._request_model(
+                spec,
+                messages_for_model,
+                hook,
+                context,
+                conversation_state=conversation_state,
+                provider_context=provider_context,
+            )
+            conversation_state.observe_response(response, messages)
             context.response = response
             context.tool_calls = list(response.tool_calls)
 
@@ -480,6 +518,10 @@ class AgentRunner:
                     reasoning_content=response.reasoning_content,
                     thinking_blocks=response.thinking_blocks,
                 )
+                assistant_message = conversation_state.project_response_message(
+                    assistant_message,
+                    response,
+                )
                 messages.append(assistant_message)
                 await self._emit_checkpoint(
                     spec,
@@ -544,6 +586,15 @@ class AgentRunner:
                         length_recovery_parts.clear()
                         continue
                     break
+                checkpoint_model_messages = (
+                    self.context_governor.prepare_for_model(
+                        governance_config,
+                        messages,
+                        compacted_tool_call_ids,
+                    )
+                    if response.provider_state is not None
+                    else None
+                )
                 await self._emit_checkpoint(
                     spec,
                     {
@@ -553,6 +604,10 @@ class AgentRunner:
                         "assistant_message": assistant_message,
                         "completed_tool_results": completed_tool_results,
                         "pending_tool_calls": [],
+                        "provider_state": conversation_state.checkpoint(
+                            messages,
+                            model_messages=checkpoint_model_messages,
+                        ),
                     },
                 )
                 empty_content_retries = 0
@@ -575,7 +630,11 @@ class AgentRunner:
                 )
 
             clean = hook.finalize_content(context, response.content)
-            if response.finish_reason != "error" and is_blank_text(clean):
+            if (
+                response.finish_reason
+                not in {"error", "length", "refusal", "content_filter"}
+                and is_blank_text(clean)
+            ):
                 empty_content_retries += 1
                 if empty_content_retries < _MAX_EMPTY_RETRIES:
                     logger.warning(
@@ -598,7 +657,12 @@ class AgentRunner:
                 if hook.wants_streaming():
                     await hook.on_stream_end(context, resuming=False)
                 retry_messages = self._finalization_retry_messages(messages_for_model)
-                response = await self._request_finalization_retry(spec, messages_for_model)
+                response = await self._request_finalization_retry(
+                    spec,
+                    messages_for_model,
+                    transcript=messages,
+                    conversation_state=conversation_state,
+                )
                 retry_usage = self._usage_or_estimate(spec, retry_messages, response)
                 self._accumulate_usage(usage, retry_usage)
                 raw_usage = self._merge_usage(raw_usage, retry_usage)
@@ -608,7 +672,7 @@ class AgentRunner:
                 original_content = response.content
                 clean = hook.finalize_content(context, response.content)
 
-            if response.finish_reason == "length" and not is_blank_text(clean):
+            if response.finish_reason == "length":
                 if len(length_recovery_parts) < _MAX_LENGTH_RECOVERIES:
                     length_recovery_parts.append(
                         _restore_outer_whitespace(clean or "", original_content)
@@ -623,10 +687,13 @@ class AgentRunner:
                     if hook.wants_streaming():
                         context.stream_continues_current_message = True
                         await hook.on_stream_end(context, resuming=True)
-                    messages.append(build_assistant_message(
-                        clean,
-                        reasoning_content=response.reasoning_content,
-                        thinking_blocks=response.thinking_blocks,
+                    messages.append(conversation_state.project_response_message(
+                        build_assistant_message(
+                            clean,
+                            reasoning_content=response.reasoning_content,
+                            thinking_blocks=response.thinking_blocks,
+                        ),
+                        response,
                     ))
                     messages.append(build_length_recovery_message(clean or ""))
                     await hook.after_iteration(context)
@@ -656,15 +723,22 @@ class AgentRunner:
                     reasoning_content=response.reasoning_content,
                     thinking_blocks=response.thinking_blocks,
                 )
+                assistant_message = conversation_state.project_response_message(
+                    assistant_message,
+                    response,
+                )
 
             # Check for mid-turn injections BEFORE signaling stream end.
             # If injections are found we keep the stream alive (resuming=True)
             # so streaming channels don't prematurely finalize the card.
             should_continue, injection_cycles = await self._try_drain_injections(
                 spec, messages, assistant_message, injection_cycles,
+                conversation_state=conversation_state,
                 phase="after final response",
                 iteration=iteration,
-                allow_goal_continue=True,
+                allow_goal_continue=(
+                    response.finish_reason not in {"refusal", "content_filter"}
+                ),
             )
             if should_continue:
                 had_injections = True
@@ -717,11 +791,17 @@ class AgentRunner:
                     continue
                 break
 
-            messages.append(assistant_message or build_assistant_message(
-                clean,
-                reasoning_content=response.reasoning_content,
-                thinking_blocks=response.thinking_blocks,
-            ))
+            messages.append(
+                assistant_message
+                or conversation_state.project_response_message(
+                    build_assistant_message(
+                        clean,
+                        reasoning_content=response.reasoning_content,
+                        thinking_blocks=response.thinking_blocks,
+                    ),
+                    response,
+                )
+            )
             await self._emit_checkpoint(
                 spec,
                 {
@@ -731,6 +811,7 @@ class AgentRunner:
                     "assistant_message": messages[-1],
                     "completed_tool_results": [],
                     "pending_tool_calls": [],
+                    "provider_state": conversation_state.checkpoint(messages),
                 },
             )
             if length_recovery_parts:
@@ -764,6 +845,7 @@ class AgentRunner:
                     hook,
                     messages,
                     usage,
+                    conversation_state,
                 )
             if terminal_content is None:
                 terminal_content = self._max_iterations_fallback(spec)
@@ -787,6 +869,7 @@ class AgentRunner:
             tool_events=tool_events,
             had_injections=had_injections,
             pending_stream_content=pending_stream_content,
+            provider_state=conversation_state.finish(messages),
         )
 
     def _build_request_kwargs(
@@ -817,6 +900,8 @@ class AgentRunner:
         context: AgentHookContext,
         *,
         malformed_retry: bool = False,
+        conversation_state: ProviderConversationStateController,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         timeout_s: float | None = spec.llm_timeout_s
         if timeout_s is None:
@@ -886,6 +971,7 @@ class AgentRunner:
 
             coro = spec.runtime.provider.chat_stream_with_retry(
                 **kwargs,
+                provider_context=provider_context,
                 on_content_delta=_stream,
                 on_thinking_delta=_thinking,
                 on_tool_call_delta=_provider_tool_event,
@@ -920,11 +1006,15 @@ class AgentRunner:
 
             coro = spec.runtime.provider.chat_stream_with_retry(
                 **kwargs,
+                provider_context=provider_context,
                 on_content_delta=_stream_progress,
                 on_tool_call_delta=_provider_tool_event,
             )
         else:
-            coro = spec.runtime.provider.chat_with_retry(**kwargs)
+            coro = spec.runtime.provider.chat_with_retry(
+                **kwargs,
+                provider_context=provider_context,
+            )
 
         # Streaming requests also have provider-level idle timeouts
         # (NANOBOT_STREAM_IDLE_TIMEOUT_S), but a stream that keeps producing
@@ -986,6 +1076,10 @@ class AgentRunner:
             return await self._request_model(
                 spec, retry_messages, hook, context,
                 malformed_retry=True,
+                conversation_state=conversation_state,
+                provider_context=conversation_state.independent_request_context(
+                    context_window_tokens=spec.runtime.context_window_tokens,
+                ),
             )
         if (
             all_dropped
@@ -998,7 +1092,13 @@ class AgentRunner:
             fallback_messages = self._malformed_tool_call_retry_messages(
                 messages, response.content,
             )
-            return await self._request_no_tools(spec, fallback_messages)
+            return await self._request_no_tools(
+                spec,
+                fallback_messages,
+                provider_context=conversation_state.independent_request_context(
+                    context_window_tokens=spec.runtime.context_window_tokens,
+                ),
+            )
         return response
 
     @staticmethod
@@ -1031,6 +1131,10 @@ class AgentRunner:
             original_finish_reason,
         )
         response.tool_calls = valid
+        # The opaque candidate still contains every raw function_call item.
+        # Advancing it after dropping even one call would replay an unmatched
+        # call without a corresponding tool output on the next request.
+        response.provider_state = None
         if not valid:
             response.finish_reason = "stop"
         return (dropped, not valid, original_finish_reason)
@@ -1060,9 +1164,27 @@ class AgentRunner:
         self,
         spec: AgentRunSpec,
         messages: list[dict[str, Any]],
+        *,
+        transcript: list[dict[str, Any]],
+        conversation_state: ProviderConversationStateController,
     ) -> LLMResponse:
         retry_messages = self._finalization_retry_messages(messages)
-        return await self._request_no_tools(spec, retry_messages)
+        provider_context = conversation_state.prepare_request(
+            transcript,
+            context_window_tokens=spec.runtime.context_window_tokens,
+            supplemental_messages=[retry_messages[-1]],
+        )
+        response = await self._request_no_tools(
+            spec,
+            retry_messages,
+            provider_context=provider_context,
+        )
+        conversation_state.observe_response(
+            response,
+            transcript,
+            adopt_candidate_state=False,
+        )
+        return response
 
     @staticmethod
     def _finalization_retry_messages(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
@@ -1076,10 +1198,17 @@ class AgentRunner:
         hook: AgentHook,
         messages: list[dict[str, Any]],
         usage: dict[str, int],
+        conversation_state: ProviderConversationStateController,
     ) -> str | None:
         retry_messages = self._budget_exhausted_finalization_messages(messages)
         try:
-            response = await self._request_no_tools(spec, retry_messages)
+            response = await self._request_no_tools(
+                spec,
+                retry_messages,
+                provider_context=conversation_state.independent_request_context(
+                    context_window_tokens=spec.runtime.context_window_tokens,
+                ),
+            )
         except Exception:
             logger.exception(
                 "Budget-exhausted finalization failed for {}; using fallback",
@@ -1115,9 +1244,18 @@ class AgentRunner:
         self,
         spec: AgentRunSpec,
         messages: list[dict[str, Any]],
+        *,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
-        kwargs = self._build_request_kwargs(spec, messages, tools=None)
-        return await spec.runtime.provider.chat_with_retry(**kwargs)
+        kwargs = self._build_request_kwargs(
+            spec,
+            messages,
+            tools=None,
+        )
+        return await spec.runtime.provider.chat_with_retry(
+            **kwargs,
+            provider_context=provider_context,
+        )
 
     @staticmethod
     def _budget_exhausted_finalization_messages(

nanobot/agent/skills.py

@@ -1,24 +1,17 @@
 """Skills loader for agent capabilities."""
 
-from __future__ import annotations
-
 import json
 import os
 import re
 import shutil
 from pathlib import Path
-from typing import Any, Literal, TypeAlias, cast
+from typing import Any, cast
 
 import yaml
 
-from nanobot.resource_links import ResourceView
-from nanobot.utils.prompt_templates import render_template
-
 # Default builtin skills directory (relative to this file)
 BUILTIN_SKILLS_DIR = Path(__file__).parent.parent / "skills"
 
-ResourceViewMode: TypeAlias = Literal["full", "restricted"]
-
 # Opening ---, YAML body (group 1), closing --- on its own line; supports CRLF.
 _STRIP_SKILL_FRONTMATTER = re.compile(
     r"^---\s*\r?\n(.*?)\r?\n---\s*\r?\n?",
@@ -27,39 +20,6 @@ _STRIP_SKILL_FRONTMATTER = re.compile(
 _SKILL_REFERENCE = re.compile(r"(?<![\w$])\$([A-Za-z0-9_-]+)")
 
 
-def build_resource_aliases_section(
-    resource_view: ResourceView | None,
-    mode: ResourceViewMode | None,
-) -> str:
-    """Render healthy resource aliases without changing their access policy."""
-    if resource_view is None or mode is None:
-        return ""
-
-    aliases: list[tuple[str, str]] = []
-    if mode == "full":
-        if resource_view.agent is not None:
-            aliases.append(("Agent workspace", str(resource_view.agent)))
-        if resource_view.media is not None:
-            aliases.append(("Media", str(resource_view.media)))
-        if resource_view.package is not None:
-            aliases.append(("Nanobot package", str(resource_view.package)))
-    else:
-        if resource_view.agent is not None:
-            aliases.append(("Custom skills", str(resource_view.agent / "skills")))
-        if resource_view.media is not None:
-            aliases.append(("Media", str(resource_view.media)))
-        if resource_view.package is not None:
-            aliases.append(("Built-in skills", str(resource_view.package / "skills")))
-
-    if not aliases:
-        return ""
-    return render_template(
-        "agent/resource_aliases.md",
-        strip=True,
-        aliases=aliases,
-    )
-
-
 class SkillsLoader:
     """
     Loader for agent skills.
@@ -68,19 +28,11 @@ class SkillsLoader:
     specific tools or perform certain tasks.
     """
 
-    def __init__(
-        self,
-        workspace: Path,
-        builtin_skills_dir: Path | None = None,
-        disabled_skills: set[str] | None = None,
-        *,
-        resource_view: ResourceView | None = None,
-    ):
+    def __init__(self, workspace: Path, builtin_skills_dir: Path | None = None, disabled_skills: set[str] | None = None):
         self.workspace = workspace
         self.workspace_skills = workspace / "skills"
         self.builtin_skills = builtin_skills_dir or BUILTIN_SKILLS_DIR
         self.disabled_skills = disabled_skills or set()
-        self.resource_view = resource_view
 
     def _skill_entries_from_dir(self, base: Path, source: str, *, skip_names: set[str] | None = None) -> list[dict[str, str]]:
         if not base.exists():
@@ -190,32 +142,12 @@ class SkillsLoader:
         if not all_skills:
             return ""
 
-        workspace_alias_root = (
-            self.resource_view.agent / "skills"
-            if self.resource_view is not None and self.resource_view.agent is not None
-            else None
-        )
-        builtin_alias_root = (
-            self.resource_view.package / "skills"
-            if self.resource_view is not None and self.resource_view.package is not None
-            else None
-        )
         sections: list[str] = []
         groups = (
-            (
-                "Workspace skills",
-                "workspace",
-                self.workspace_skills,
-                workspace_alias_root,
-            ),
-            (
-                "Built-in skills",
-                "builtin",
-                self.builtin_skills,
-                builtin_alias_root,
-            ),
+            ("Workspace skills", "workspace", self.workspace_skills),
+            ("Built-in skills", "builtin", self.builtin_skills),
         )
-        for label, source, root, alias_root in groups:
+        for label, source, root in groups:
             entries = [
                 entry
                 for entry in all_skills
@@ -224,8 +156,7 @@ class SkillsLoader:
             if not entries:
                 continue
 
-            display_root = alias_root or root.expanduser().resolve()
-            lines = [f"### {label} (`{display_root}`)"]
+            lines = [f"### {label} (`{root.expanduser().resolve()}`)"]
             for entry in entries:
                 skill_name = entry["name"]
                 meta = self._get_skill_meta(skill_name)

nanobot/agent/subagent.py

@@ -1,7 +1,5 @@
 """Subagent manager for background task execution."""
 
-from __future__ import annotations
-
 import asyncio
 import json
 import time
@@ -15,11 +13,6 @@ from loguru import logger
 
 from nanobot.agent.hook import AgentHook, AgentHookContext
 from nanobot.agent.runner import AgentRunner, AgentRunResult, AgentRunSpec
-from nanobot.agent.skills import (
-    ResourceViewMode,
-    SkillsLoader,
-    build_resource_aliases_section,
-)
 from nanobot.agent.tools.base import ToolResult
 from nanobot.agent.tools.context import (
     RequestContext,
@@ -35,7 +28,6 @@ from nanobot.bus.events import InboundMessage
 from nanobot.bus.queue import MessageBus
 from nanobot.config.schema import AgentDefaults, ToolsConfig
 from nanobot.providers.base import LLMProvider
-from nanobot.resource_links import ResourceView
 from nanobot.security.workspace_access import (
     WorkspaceScope,
     bind_workspace_scope,
@@ -111,7 +103,6 @@ class SubagentManager:
         max_concurrent_subagents: int | None = None,
         fail_on_tool_error: bool | None = None,
         llm_wall_timeout_for_session: Callable[[str | None], float | None] | None = None,
-        resource_view: ResourceView | None = None,
     ):
         if workspace is None:
             raise TypeError("SubagentManager.__init__() missing required argument: 'workspace'")
@@ -162,7 +153,6 @@ class SubagentManager:
         self.runner = AgentRunner()
         self._exec_session_manager = ExecSessionManager()
         self._llm_wall_timeout_for_session = llm_wall_timeout_for_session
-        self.resource_view = resource_view
         self._running_tasks: dict[str, asyncio.Task[str]] = {}
         self._task_statuses: dict[str, SubagentStatus] = {}
         self._session_tasks: dict[str, set[str]] = {}  # session_key -> {task_id, ...}
@@ -386,20 +376,7 @@ class SubagentManager:
                 cfg.restrict_to_workspace = workspace_scope.restrict_to_workspace
             # Construct from the agent workspace; the bound scope below supplies the project cwd.
             tools = self._build_tools(tools_config=cfg)
-            scope_restricted = (
-                workspace_scope.restrict_to_workspace
-                if workspace_scope is not None
-                else self.restrict_to_workspace
-            )
-            resource_view_mode: ResourceViewMode = (
-                "restricted"
-                if scope_restricted or bool(self.tools_config.exec.sandbox)
-                else "full"
-            )
-            system_prompt = self._build_subagent_prompt(
-                workspace=root,
-                resource_view_mode=resource_view_mode,
-            )
+            system_prompt = self._build_subagent_prompt(workspace=root)
             messages: list[dict[str, Any]] = [
                 {"role": "system", "content": system_prompt},
                 {"role": "user", "content": task},
@@ -549,37 +526,22 @@ class SubagentManager:
             lines.append(f"- {result.error}")
         return "\n".join(lines) or (result.error or "Error: subagent execution failed.")
 
-    def _build_subagent_prompt(
-        self,
-        workspace: Path | None = None,
-        *,
-        resource_view_mode: ResourceViewMode | None = None,
-    ) -> str:
+    def _build_subagent_prompt(self, workspace: Path | None = None) -> str:
         """Build a focused system prompt for the subagent."""
+        from nanobot.agent.skills import SkillsLoader
+
         agent_workspace = self.workspace.expanduser().resolve()
         project_workspace = workspace.expanduser().resolve() if workspace else agent_workspace
-        history_root = agent_workspace
-        if (
-            resource_view_mode == "full"
-            and self.resource_view is not None
-            and self.resource_view.agent is not None
-        ):
-            history_root = self.resource_view.agent
         skills_summary = SkillsLoader(
             self.workspace,
             disabled_skills=self.disabled_skills,
-            resource_view=self.resource_view,
         ).build_skills_summary()
         return render_template(
             "agent/subagent_system.md",
             workspace=str(project_workspace),
             agent_workspace=str(agent_workspace),
-            history_log=str(history_root / "memory" / "history.jsonl"),
+            history_log=str(agent_workspace / "memory" / "history.jsonl"),
             skills_summary=skills_summary or "",
-            resource_aliases=build_resource_aliases_section(
-                self.resource_view,
-                resource_view_mode,
-            ),
         )
 
     async def cancel_by_session(self, session_key: str) -> int:

nanobot/agent/tools/exec_session.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import time
 import uuid
+from collections import deque
 from contextlib import suppress
 from dataclasses import dataclass
 from typing import Any
@@ -51,6 +52,66 @@ class ExecSessionInfo:
     owner_session_key: str | None = None
 
 
+class _BoundedOutputBuffer:
+    """Keep the first and most recent characters within a fixed budget."""
+
+    def __init__(self, max_chars: int) -> None:
+        self.max_chars = max_chars
+        self._content = ""
+        self._tail: deque[str] = deque()
+        self._tail_chars = 0
+        self._total_chars = 0
+        self._truncated = False
+
+    @property
+    def has_output(self) -> bool:
+        return self._total_chars > 0
+
+    @property
+    def retained_chars(self) -> int:
+        return len(self._content) + self._tail_chars
+
+    def append(self, text: str) -> None:
+        if not text:
+            return
+        self._total_chars += len(text)
+        if not self._truncated:
+            combined = self._content + text
+            if len(combined) <= self.max_chars:
+                self._content = combined
+                return
+            head_chars = self.max_chars // 2
+            tail_chars = self.max_chars - head_chars
+            self._content = combined[:head_chars]
+            self._tail.append(combined[-tail_chars:])
+            self._tail_chars = tail_chars
+            self._truncated = True
+            return
+
+        tail_chars = self.max_chars - len(self._content)
+        self._tail.append(text)
+        self._tail_chars += len(text)
+        while self._tail_chars > tail_chars:
+            excess = self._tail_chars - tail_chars
+            first = self._tail[0]
+            if len(first) <= excess:
+                self._tail.popleft()
+                self._tail_chars -= len(first)
+            else:
+                self._tail[0] = first[excess:]
+                self._tail_chars -= excess
+
+    def drain(self) -> tuple[str, int]:
+        output = self._content + "".join(self._tail)
+        truncated_chars = self._total_chars - len(output)
+        self._content = ""
+        self._tail.clear()
+        self._tail_chars = 0
+        self._total_chars = 0
+        self._truncated = False
+        return output, truncated_chars
+
+
 class _ExecSession:
     def __init__(
         self,
@@ -73,30 +134,27 @@ class _ExecSession:
         # timeout None/0 means no limit; an infinite deadline is never reached.
         self.deadline = time.monotonic() + timeout if timeout else float("inf")
         self.last_access = time.monotonic()
-        self._chunks: list[str] = []
+        self._stdout = _BoundedOutputBuffer(MAX_OUTPUT_CHARS)
+        self._stderr = _BoundedOutputBuffer(MAX_OUTPUT_CHARS)
         self._lock = asyncio.Lock()
         self._timed_out = False
-        self._stdout_task = asyncio.create_task(self._read_stream(process.stdout, ""))
-        self._stderr_task = asyncio.create_task(self._read_stream(process.stderr, "STDERR:\n"))
+        self._stdout_task = asyncio.create_task(self._read_stream(process.stdout, self._stdout))
+        self._stderr_task = asyncio.create_task(self._read_stream(process.stderr, self._stderr))
 
     async def _read_stream(
         self,
         stream: asyncio.StreamReader | None,
-        prefix: str,
+        buffer: _BoundedOutputBuffer,
     ) -> None:
         if stream is None:
             return
-        first = True
         while True:
             chunk = await stream.read(4096)
             if not chunk:
                 break
             text = chunk.decode("utf-8", errors="replace")
-            if prefix and first:
-                text = prefix + text
-                first = False
             async with self._lock:
-                self._chunks.append(text)
+                buffer.append(text)
 
     async def write(self, chars: str) -> str | None:
         if self.process.returncode is not None:
@@ -157,10 +215,14 @@ class _ExecSession:
             await self._wait_for_buffered_output()
 
         async with self._lock:
-            output = "".join(self._chunks)
-            self._chunks.clear()
+            stdout, stdout_truncated = self._stdout.drain()
+            stderr, stderr_truncated = self._stderr.drain()
 
-        output, truncated = _truncate_output(output, max_output_chars)
+        output_parts = [stdout] if stdout else []
+        if stderr:
+            output_parts.append(f"STDERR:\n{stderr}")
+        output = "\n".join(output_parts)
+        output, response_truncated = _truncate_output(output, max_output_chars)
         return _SessionPoll(
             output=output,
             done=self.process.returncode is not None,
@@ -169,7 +231,7 @@ class _ExecSession:
             timed_out=self._timed_out,
             terminated=terminated,
             stdin_closed=stdin_closed,
-            truncated_chars=truncated,
+            truncated_chars=stdout_truncated + stderr_truncated + response_truncated,
         )
 
     async def kill(self) -> None:
@@ -195,7 +257,7 @@ class _ExecSession:
         deadline = time.monotonic() + OUTPUT_DRAIN_GRACE_S
         while time.monotonic() < deadline:
             async with self._lock:
-                if self._chunks:
+                if self._stdout.has_output or self._stderr.has_output:
                     return
             await asyncio.sleep(0.01)
 
@@ -403,20 +465,16 @@ def clamp_session_int(value: int | None, default: int, minimum: int, maximum: in
 def _truncate_output(output: str, max_output_chars: int) -> tuple[str, int]:
     if len(output) <= max_output_chars:
         return output, 0
-    half = max_output_chars // 2
+    head_chars = max_output_chars // 2
+    tail_chars = max_output_chars - head_chars
     omitted = len(output) - max_output_chars
-    return (
-        output[:half]
-        + f"\n\n... ({omitted:,} chars truncated) ...\n\n"
-        + output[-half:],
-        omitted,
-    )
+    return output[:head_chars] + output[-tail_chars:], omitted
 
 
 def format_session_poll(session_id: str, poll: _SessionPoll) -> str:
     parts = [poll.output] if poll.output else []
     if poll.truncated_chars:
-        parts.append(f"(output truncated by {poll.truncated_chars:,} chars)")
+        parts.append(f"({poll.truncated_chars:,} chars truncated from output)")
     if poll.timed_out:
         parts.append("Error: Command timed out; session was terminated.")
     if poll.terminated and not poll.timed_out:
@@ -587,7 +645,9 @@ class WriteStdinTool(Tool):
         max_output_chars: int,
     ) -> str:
         deadline = time.monotonic() + (wait_timeout_ms / 1000)
-        aggregate: list[str] = []
+        aggregate = _BoundedOutputBuffer(max_output_chars)
+        upstream_truncated = 0
+        search_overlap = ""
         first = True
         poll: _SessionPoll | None = None
 
@@ -604,15 +664,20 @@ class WriteStdinTool(Tool):
                 owner_session_key=current_request_session_key(),
             )
             first = False
+            upstream_truncated += poll.truncated_chars
             if poll.output:
                 aggregate.append(poll.output)
-                joined = "".join(aggregate)
-                if wait_for in joined:
-                    poll.output = joined
+                searchable = search_overlap + poll.output
+                if wait_for in searchable:
+                    poll.output, aggregate_truncated = aggregate.drain()
+                    poll.truncated_chars = upstream_truncated + aggregate_truncated
                     result = format_session_poll(session_id, poll)
                     return ToolResult.error(result) if poll.timed_out else result
+                overlap_chars = max(0, len(wait_for) - 1)
+                search_overlap = searchable[-overlap_chars:] if overlap_chars else ""
             if poll.done or remaining_ms <= 0:
-                poll.output = "".join(aggregate)
+                poll.output, aggregate_truncated = aggregate.drain()
+                poll.truncated_chars = upstream_truncated + aggregate_truncated
                 result = format_session_poll(session_id, poll)
                 if wait_for not in poll.output:
                     result += f"\nWait target not observed: {wait_for!r}"

nanobot/channels/base.py

@@ -248,7 +248,15 @@ class BaseChannel(ABC):
         permission_id = authorization_id if authorization_id is not None else sender_id
         if not self.is_allowed(permission_id):
             if is_dm:
-                code = generate_code(self.name, str(sender_id))
+                try:
+                    code = generate_code(self.name, str(sender_id))
+                except OSError:
+                    # Transient pairing-store I/O failure: skip the pairing
+                    # reply for this message rather than crash the handler.
+                    self.logger.warning(
+                        "Pairing store unavailable; dropping DM from {}", sender_id
+                    )
+                    return
                 await self.send(
                     OutboundMessage(
                         channel=self.name,

nanobot/channels/websocket/runtime.py

@@ -67,6 +67,7 @@ from nanobot.webui.http_utils import (
 from nanobot.webui.mcp_presets_api import normalize_mcp_preset_mentions
 from nanobot.webui.metadata import (
     WEBSOCKET_TURN_OWNER_METADATA_KEY,
+    WEBUI_SYSTEM_COMMAND_TURN_PREFIX,
     WEBUI_TURN_METADATA_KEY,
 )
 from nanobot.webui.transcript import WEBUI_TRANSCRIPT_INCOMPLETE_KEY
@@ -1003,6 +1004,13 @@ class WebSocketChannel(BaseChannel):
             return
         # Signal that the agent has fully finished processing the current turn.
         if isinstance(event, TurnEndEvent):
+            turn_id = (msg.metadata or {}).get(WEBUI_TURN_METADATA_KEY)
+            session_update_scope = (
+                "metadata"
+                if isinstance(turn_id, str)
+                and turn_id.startswith(WEBUI_SYSTEM_COMMAND_TURN_PREFIX)
+                else "thread"
+            )
             turn_owner = (msg.metadata or {}).get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
             await self.send_turn_end(
                 msg.chat_id,
@@ -1011,7 +1019,7 @@ class WebSocketChannel(BaseChannel):
                 metadata=msg.metadata,
                 turn_owner=turn_owner if isinstance(turn_owner, str) else None,
             )
-            await self.send_session_updated(msg.chat_id, scope="thread")
+            await self.send_session_updated(msg.chat_id, scope=session_update_scope)
             return
         if isinstance(event, SessionUpdatedEvent):
             if conns:
@@ -1208,6 +1216,7 @@ class WebSocketChannel(BaseChannel):
             body,
             metadata=meta,
             phase="answer",
+            include_source=True,
         )
         raw = json.dumps(body, ensure_ascii=False)
         if not conns:

nanobot/channels/websocket/tests/test_websocket_channel.py

@@ -49,7 +49,12 @@ 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.metadata import (
+    WEBSOCKET_TURN_OWNER_METADATA_KEY,
+    WEBUI_MESSAGE_SOURCE_METADATA_KEY,
+    WEBUI_SYSTEM_COMMAND_TURN_PREFIX,
+    WEBUI_TURN_METADATA_KEY,
+)
 from nanobot.webui.settings_api import settings_payload, update_provider_settings
 from nanobot.webui.transcript import (
     append_transcript_object,
@@ -1346,6 +1351,35 @@ async def test_send_delta_emits_delta_and_stream_end() -> None:
     assert "text" not in second
 
 
+@pytest.mark.asyncio
+async def test_send_delta_preserves_webui_source_metadata() -> None:
+    bus = MagicMock()
+    channel = WebSocketChannel({"enabled": True, "allowFrom": ["*"], "streaming": True}, bus, gateway=_basic_handler(bus))
+    mock_ws = AsyncMock()
+    channel._attach(mock_ws, "chat-source-stream")
+    source = {"kind": "cron", "label": "Repo check"}
+    metadata = {WEBUI_MESSAGE_SOURCE_METADATA_KEY: source}
+
+    await channel.send_delta("chat-source-stream", "done", metadata=metadata, stream_id="sid")
+    await channel.send_delta(
+        "chat-source-stream",
+        "",
+        metadata=metadata,
+        stream_id="sid",
+        stream_end=True,
+    )
+
+    first = json.loads(mock_ws.send.call_args_list[0][0][0])
+    second = json.loads(mock_ws.send.call_args_list[1][0][0])
+    assert first["event"] == "delta"
+    assert first["source"] == source
+    assert second["event"] == "stream_end"
+    assert second["source"] == source
+    lines = read_transcript_lines("websocket:chat-source-stream")
+    assert lines[-2]["source"] == source
+    assert lines[-1]["source"] == source
+
+
 @pytest.mark.asyncio
 async def test_send_delta_marks_resuming_stream_end() -> None:
     bus = MagicMock()
@@ -1618,6 +1652,43 @@ async def test_send_turn_end_emits_turn_end_event() -> None:
     ]
 
 
+@pytest.mark.asyncio
+async def test_system_command_turn_end_only_refreshes_session_metadata() -> None:
+    bus = MagicMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    mock_ws = AsyncMock()
+    channel._attach(mock_ws, "chat-model")
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id="chat-model",
+        content="",
+        metadata={
+            WEBUI_TURN_METADATA_KEY: f"{WEBUI_SYSTEM_COMMAND_TURN_PREFIX}model-switch",
+        },
+        event=TurnEndEvent(),
+    ))
+
+    assert _sent_ws_payloads(mock_ws) == [
+        {
+            "event": "turn_end",
+            "chat_id": "chat-model",
+            "turn_id": f"{WEBUI_SYSTEM_COMMAND_TURN_PREFIX}model-switch",
+            "turn_phase": "complete",
+            "turn_seq": 1,
+        },
+        {
+            "event": "session_updated",
+            "chat_id": "chat-model",
+            "scope": "metadata",
+        },
+    ]
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     ("active_owner", "event_owner", "expected_cleared"),

nanobot/channels/websocket/tests/test_websocket_http_routes.py

@@ -2937,6 +2937,17 @@ async def test_webui_thread_resigns_assistant_media_urls(
         assert media[0]["url"].startswith("/api/media/")
         assert media[0]["url"] != "/api/media/old-sig/old-payload"
 
+        repeated = await _http_get(
+            "http://127.0.0.1:29914/api/sessions/websocket:video-replay/webui-thread",
+            headers=auth,
+        )
+        repeated_assistant = next(
+            m for m in repeated.json()["messages"] if m["role"] == "assistant"
+        )
+        assert repeated_assistant["id"] == assistant["id"]
+        assert repeated_assistant["media"][0]["url"] == media[0]["url"]
+        assert len(list(websocket_media.iterdir())) == 1
+
         fetched = await _http_get(f"http://127.0.0.1:29914{media[0]['url']}")
         assert fetched.status_code == 200
         assert fetched.content == b"video"

nanobot/channels/websocket/tests/test_websocket_media_route.py

@@ -146,16 +146,41 @@ def test_local_markdown_image_is_staged_and_rewritten(
     channel = _ch(bus, workspace_path=workspace, port=0)
 
     with patch("nanobot.webui.media_gateway.get_media_dir", side_effect=_fake_media_dir(media)):
-        rewritten = channel.gateway.media.rewrite_local_markdown_images(
+        first = channel.gateway.media.rewrite_local_markdown_images(
+            "The result:\n![Cloud Architecture Diagram](demo_arch.png)"
+        )
+        second = channel.gateway.media.rewrite_local_markdown_images(
             "The result:\n![Cloud Architecture Diagram](demo_arch.png)"
         )
 
-    assert "![Cloud Architecture Diagram](/api/media/" in rewritten
+    assert "![Cloud Architecture Diagram](/api/media/" in first
+    assert second == first
     staged = list((media / "websocket").iterdir())
     assert len(staged) == 1
     assert staged[0].read_bytes() == _PNG_BYTES
 
 
+def test_modified_local_markdown_image_gets_a_new_immutable_url(
+    bus: MagicMock,
+    tmp_path: Path,
+) -> None:
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    source = workspace / "demo_arch.png"
+    source.write_bytes(_PNG_BYTES)
+    media = tmp_path / "media"
+    channel = _ch(bus, workspace_path=workspace, port=0)
+    markdown = "![Cloud Architecture Diagram](demo_arch.png)"
+
+    with patch("nanobot.webui.media_gateway.get_media_dir", side_effect=_fake_media_dir(media)):
+        first = channel.gateway.media.rewrite_local_markdown_images(markdown)
+        source.write_bytes(_PNG_BYTES + b"updated")
+        second = channel.gateway.media.rewrite_local_markdown_images(markdown)
+
+    assert second != first
+    assert len(list((media / "websocket").iterdir())) == 2
+
+
 def test_local_markdown_video_is_staged_and_rewritten(
     bus: MagicMock,
     tmp_path: Path,

nanobot/cli/agent.py

@@ -0,0 +1,352 @@
+"""Direct and interactive agent CLI command."""
+
+import asyncio
+import signal
+import sys
+from collections.abc import Awaitable, Callable
+from types import FrameType
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from nanobot import __logo__
+from nanobot.agent.hooks import create_file_edit_activity_hook
+from nanobot.agent.loop import AgentLoop
+from nanobot.bus.outbound_events import (
+    StreamDeltaEvent,
+    StreamedResponseEvent,
+    StreamEndEvent,
+    outbound_event_from_message,
+)
+from nanobot.cli import terminal as cli_terminal
+from nanobot.cli.log_control import _set_nanobot_logs
+from nanobot.cli.runtime_config import (
+    _load_runtime_config,
+    _migrate_cron_store,
+    _model_display,
+    _print_agent_start_error,
+)
+from nanobot.cli.stream import StreamRenderer, ThinkingSpinner
+from nanobot.config.paths import is_default_workspace
+from nanobot.utils.helpers import (
+    sanitize_surrogates as _sanitize_surrogates,
+)
+from nanobot.utils.helpers import (
+    sync_workspace_templates,
+)
+from nanobot.utils.restart import (
+    consume_restart_notice_from_env,
+    format_restart_completed_message,
+    should_show_cli_restart_notice,
+)
+
+console = Console()
+
+
+def agent(
+    message: str = typer.Option(None, "--message", "-m", help="Message to send to the agent"),
+    session_id: str = typer.Option("cli:direct", "--session", "-s", help="Session ID"),
+    workspace: str | None = typer.Option(None, "--workspace", "-w", help="Workspace directory"),
+    config: str | None = typer.Option(None, "--config", "-c", help="Path to config file"),
+    markdown: bool = typer.Option(
+        True,
+        "--markdown/--no-markdown",
+        help="Render assistant output as Markdown",
+    ),
+    logs: bool = typer.Option(
+        False,
+        "--logs/--no-logs",
+        help="Show nanobot runtime logs during chat",
+    ),
+):
+    """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
+
+    runtime_config = _load_runtime_config(config, workspace)
+    try:
+        provider = make_provider(runtime_config)
+    except ValueError as exc:
+        _print_agent_start_error(exc)
+        raise typer.Exit(1) from exc
+
+    sync_workspace_templates(runtime_config.workspace_path)
+
+    bus = MessageBus()
+
+    # Preserve existing single-workspace installs, but keep custom workspaces clean.
+    if is_default_workspace(runtime_config.workspace_path):
+        _migrate_cron_store(runtime_config)
+
+    # Create cron service with workspace-scoped store
+    cron_store_path = runtime_config.workspace_path / "cron" / "jobs.json"
+    cron = CronService(cron_store_path)
+
+    _set_nanobot_logs(logs)
+
+    try:
+        agent_loop = AgentLoop.from_config(
+            runtime_config,
+            bus,
+            provider=provider,
+            cron_service=cron,
+            image_generation_provider_configs=image_gen_provider_configs(runtime_config),
+            hook_factories=[create_file_edit_activity_hook],
+        )
+    except ValueError as exc:
+        _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):
+        cli_terminal._print_agent_response(
+            format_restart_completed_message(restart_notice.started_at_raw),
+            render_markdown=False,
+        )
+
+    # Shared reference for progress callbacks
+    _thinking: ThinkingSpinner | None = None
+
+    def _make_progress(
+        renderer: StreamRenderer | None = None,
+    ) -> Callable[..., Awaitable[None]]:
+        reasoning_buffer = cli_terminal._ReasoningBuffer()
+
+        async def _cli_progress(
+            content: str,
+            *,
+            tool_hint: bool = False,
+            reasoning: bool = False,
+            **_kwargs: Any,
+        ) -> None:
+            ch = agent_loop.channels_config
+
+            if _kwargs.get("reasoning_end"):
+                if ch and not ch.show_reasoning:
+                    reasoning_buffer.clear()
+                else:
+                    cli_terminal._flush_cli_reasoning(reasoning_buffer, _thinking, renderer)
+                return
+
+            if reasoning:
+                if ch and not ch.show_reasoning:
+                    reasoning_buffer.clear()
+                    return
+                text = reasoning_buffer.add(content)
+                if text:
+                    cli_terminal._print_cli_reasoning(text, _thinking, renderer)
+                return
+            if ch and tool_hint and not ch.send_tool_hints:
+                return
+            if ch and not tool_hint and not ch.send_progress:
+                return
+            cli_terminal._print_cli_progress_line(content, _thinking, renderer)
+
+        return _cli_progress
+
+    if message:
+        # Single message mode — direct call, no bus needed
+        async def run_once() -> None:
+            renderer = StreamRenderer(
+                render_markdown=markdown,
+                bot_name=runtime_config.agents.defaults.bot_name,
+                bot_icon=runtime_config.agents.defaults.bot_icon,
+            )
+            response = await agent_loop.process_direct(
+                message,
+                session_id,
+                on_progress=_make_progress(renderer),
+                on_stream=renderer.on_delta,
+                on_stream_end=renderer.on_end,
+            )
+            if not renderer.streamed:
+                await renderer.close()
+                print_kwargs: dict[str, Any] = {}
+                if renderer.header_printed:
+                    print_kwargs["show_header"] = False
+                cli_terminal._print_agent_response(
+                    response.content if response else "",
+                    render_markdown=markdown,
+                    metadata=response.metadata if response else None,
+                    **print_kwargs,
+                )
+            await agent_loop.close_mcp()
+
+        asyncio.run(run_once())
+    else:
+        # Interactive mode — route through bus like other channels
+        from nanobot.bus.events import InboundMessage
+
+        cli_terminal._init_prompt_session()
+        _model, _preset_tag = _model_display(runtime_config)
+        _icon = runtime_config.agents.defaults.bot_icon or __logo__
+        console.print(
+            f"{_icon} Interactive mode [bold blue]({_model})[/bold blue]{_preset_tag} "
+            "— type [bold]exit[/bold] or [bold]Ctrl+C[/bold] to quit\n"
+        )
+
+        if ":" in session_id:
+            cli_channel, cli_chat_id = session_id.split(":", 1)
+        else:
+            cli_channel, cli_chat_id = "cli", session_id
+
+        def _handle_signal(signum: int, _frame: FrameType | None) -> None:
+            sig_name = signal.Signals(signum).name
+            cli_terminal._restore_terminal()
+            console.print(f"\nReceived {sig_name}, goodbye!")
+            sys.exit(0)
+
+        signal.signal(signal.SIGINT, _handle_signal)
+        signal.signal(signal.SIGTERM, _handle_signal)
+        # SIGHUP is not available on Windows
+        if hasattr(signal, "SIGHUP"):
+            signal.signal(signal.SIGHUP, _handle_signal)
+        # Ignore SIGPIPE to prevent silent process termination when writing to closed pipes
+        # SIGPIPE is not available on Windows
+        if hasattr(signal, "SIGPIPE"):
+            signal.signal(signal.SIGPIPE, signal.SIG_IGN)
+
+        async def run_interactive() -> None:
+            bus_task = asyncio.create_task(agent_loop.run())
+            turn_done = asyncio.Event()
+            turn_done.set()
+            turn_response: list[Any] = []
+            renderer: StreamRenderer | None = None
+            reasoning_buffer = cli_terminal._ReasoningBuffer()
+
+            async def _consume_outbound() -> None:
+                while True:
+                    try:
+                        msg = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+                        event = outbound_event_from_message(msg)
+
+                        if isinstance(event, StreamDeltaEvent):
+                            if renderer:
+                                await renderer.on_delta(msg.content)
+                            continue
+                        if isinstance(event, StreamEndEvent):
+                            if renderer:
+                                await renderer.on_end(
+                                    resuming=event.resuming,
+                                )
+                            continue
+                        if isinstance(event, StreamedResponseEvent):
+                            if msg.content and renderer and not renderer.streamed:
+                                await renderer.close()
+                                print_kwargs: dict[str, Any] = {}
+                                if renderer.header_printed:
+                                    print_kwargs["show_header"] = False
+                                cli_terminal._print_agent_response(
+                                    msg.content,
+                                    render_markdown=markdown,
+                                    metadata=msg.metadata,
+                                    **print_kwargs,
+                                )
+                            turn_done.set()
+                            continue
+
+                        if await cli_terminal._maybe_print_interactive_progress(
+                            msg,
+                            None,
+                            agent_loop.channels_config,
+                            renderer,
+                            reasoning_buffer,
+                        ):
+                            continue
+
+                        if not turn_done.is_set():
+                            if msg.content:
+                                turn_response.append(msg)
+                            turn_done.set()
+                        elif msg.content:
+                            await cli_terminal._print_interactive_response(
+                                msg.content,
+                                render_markdown=markdown,
+                                metadata=msg.metadata,
+                            )
+
+                    except asyncio.TimeoutError:
+                        continue
+                    except asyncio.CancelledError:
+                        break
+
+            outbound_task = asyncio.create_task(_consume_outbound())
+
+            try:
+                while True:
+                    try:
+                        cli_terminal._flush_pending_tty_input()
+                        # Stop spinner before user input to avoid prompt_toolkit conflicts
+                        if renderer:
+                            renderer.stop_for_input()
+                        user_input = _sanitize_surrogates(
+                            await cli_terminal._read_interactive_input_async()
+                        )
+                        command = user_input.strip()
+                        if not command:
+                            continue
+
+                        if cli_terminal._is_exit_command(command):
+                            cli_terminal._restore_terminal()
+                            console.print("\nGoodbye!")
+                            break
+
+                        turn_done.clear()
+                        turn_response.clear()
+                        reasoning_buffer.clear()
+                        renderer = StreamRenderer(
+                            render_markdown=markdown,
+                            bot_name=runtime_config.agents.defaults.bot_name,
+                            bot_icon=runtime_config.agents.defaults.bot_icon,
+                        )
+
+                        await bus.publish_inbound(
+                            InboundMessage(
+                                channel=cli_channel,
+                                sender_id="user",
+                                chat_id=cli_chat_id,
+                                content=user_input,
+                                metadata={"_wants_stream": True},
+                            )
+                        )
+
+                        await turn_done.wait()
+
+                        if turn_response:
+                            response_msg = turn_response[0]
+                            content = response_msg.content
+                            meta = response_msg.metadata
+                            if content and not isinstance(
+                                response_msg.event,
+                                StreamedResponseEvent,
+                            ):
+                                if renderer:
+                                    await renderer.close()
+                                print_kwargs: dict[str, Any] = {}
+                                if renderer and renderer.header_printed:
+                                    print_kwargs["show_header"] = False
+                                cli_terminal._print_agent_response(
+                                    content,
+                                    render_markdown=markdown,
+                                    metadata=meta,
+                                    **print_kwargs,
+                                )
+                        elif renderer and not renderer.streamed:
+                            await renderer.close()
+                    except KeyboardInterrupt:
+                        cli_terminal._restore_terminal()
+                        console.print("\nGoodbye!")
+                        break
+                    except EOFError:
+                        cli_terminal._restore_terminal()
+                        console.print("\nGoodbye!")
+                        break
+            finally:
+                agent_loop.stop()
+                outbound_task.cancel()
+                await asyncio.gather(bus_task, outbound_task, return_exceptions=True)
+                await agent_loop.close_mcp()
+
+        asyncio.run(run_interactive())

nanobot/cli/gateway_runtime.py

@@ -0,0 +1,828 @@
+"""Foreground gateway runtime and lifecycle helpers."""
+
+import asyncio
+import signal
+from collections.abc import Awaitable, Callable, Coroutine, Iterable
+from contextlib import suppress
+from pathlib import Path
+from typing import Any, cast
+
+import typer
+from loguru import logger
+from rich.console import Console
+
+from nanobot import __logo__, __version__
+from nanobot.agent.hooks import create_file_edit_activity_hook
+from nanobot.agent.loop import AgentLoop
+from nanobot.cli import terminal as cli_terminal
+from nanobot.cli.runtime_config import _migrate_cron_store
+from nanobot.cli.webui_support import (
+    _gateway_health_bind_note,
+    _gateway_health_url,
+    _host_for_local_browser,
+    _prepare_webui_bundle_for_gateway,
+    _print_foreground_port_conflict,
+    _tcp_endpoint_reachable,
+    _webui_browser_url,
+    _webui_channel_enabled,
+    _webui_endpoint_reachable,
+)
+from nanobot.config.paths import is_default_workspace
+from nanobot.config.schema import Config
+from nanobot.security.network import is_loopback_host
+from nanobot.session.keys import UNIFIED_SESSION_KEY, last_channel_from_metadata
+from nanobot.utils.evaluator import evaluate_response, resolve_evaluator_prompt
+from nanobot.utils.helpers import sync_workspace_templates
+from nanobot.webui.build import BuildMode
+from nanobot.webui.sidebar_state import read_webui_sidebar_state
+
+__all__ = ["_run_gateway"]
+
+console = Console()
+
+
+def _signal_name(signum: int) -> str:
+    with suppress(ValueError):
+        return signal.Signals(signum).name
+    return f"signal {signum}"
+
+
+def _install_gateway_shutdown_handlers(
+    loop: asyncio.AbstractEventLoop,
+    shutdown_event: asyncio.Event,
+    tasks: list[asyncio.Task[Any]],
+    print_status: Callable[[str], None],
+) -> Callable[[], None]:
+    """Install foreground gateway signal handlers and return a restore callback."""
+    loop_signals: list[int] = []
+    previous_handlers: list[tuple[int, Any]] = []
+    shutdown_requested = False
+
+    def request_shutdown(signum: int) -> None:
+        nonlocal shutdown_requested
+        sig_name = _signal_name(signum)
+        if shutdown_requested:
+            logger.warning("Forcing gateway shutdown after repeated {}", sig_name)
+            for task in tasks:
+                if not task.done():
+                    task.cancel()
+            return
+        shutdown_requested = True
+        logger.info("Gateway shutdown requested by {}", sig_name)
+        print_status("\nShutting down... Press Ctrl+C again to force.")
+        shutdown_event.set()
+
+    for signum in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(signum, request_shutdown, signum)
+        except (NotImplementedError, RuntimeError, ValueError):
+            try:
+                previous = signal.getsignal(signum)
+                signal.signal(signum, lambda sig, _frame: request_shutdown(sig))
+            except (RuntimeError, ValueError):
+                logger.debug("Could not install gateway handler for {}", _signal_name(signum))
+                continue
+            previous_handlers.append((signum, previous))
+        else:
+            loop_signals.append(signum)
+
+    def restore() -> None:
+        for signum in loop_signals:
+            with suppress(NotImplementedError, RuntimeError, ValueError):
+                loop.remove_signal_handler(signum)
+        for signum, handler in previous_handlers:
+            with suppress(RuntimeError, ValueError):
+                signal.signal(signum, handler)
+
+    return restore
+
+
+def _advance_dream_cursor_if_behind(memory: Any) -> None:
+    latest = memory.get_latest_cursor()
+    if memory.get_last_dream_cursor() < latest:
+        memory.set_last_dream_cursor(latest)
+
+
+def _commit_dream_changes(memory: Any) -> str | None:
+    """Commit durable Dream edits, without entering the commit path for a no-op run."""
+    if not memory.git.is_initialized():
+        return None
+    diff_body = memory.dream_content_diff()
+    if not diff_body:
+        return None
+    message = memory.build_dream_commit_message(
+        "dream: periodic memory consolidation",
+        diff_body,
+    )
+    return memory.git.auto_commit(message)
+
+
+_HEARTBEAT_PREAMBLE = (
+    "[Your response will be delivered directly to the user's messaging app. "
+    "Output ONLY the final user-facing message. Never reference internal "
+    "files (HEARTBEAT.md, AWARENESS.md, etc.), your instructions, or your "
+    "decision process. If nothing needs reporting, respond with just "
+    "'All clear.' and nothing else.]\n\n"
+)
+
+
+def _heartbeat_has_active_tasks(content: str) -> bool:
+    """True if HEARTBEAT.md has task lines, ignoring headers, blanks and comments."""
+    in_comment = False
+    in_active_section: bool = False
+    for line in content.splitlines():
+        stripped = line.strip()
+        if in_comment:
+            if "-->" in stripped:
+                in_comment = False
+            continue
+        if not stripped or stripped.startswith("#"):
+            if stripped.startswith("##") and not stripped.startswith("###"):
+                heading = stripped.lstrip("#").strip().lower()
+                in_active_section = heading.startswith("active tasks")
+            continue
+        if stripped.startswith("<!--"):
+            if "-->" not in stripped[4:]:
+                in_comment = True
+            continue
+        if in_active_section is False:
+            continue
+        return True
+    return False
+
+
+def _pick_heartbeat_target_from_sessions(
+    *,
+    enabled_channels: Iterable[str],
+    sessions: Iterable[dict[str, Any]],
+    archived_keys: Iterable[str],
+    unified_session_metadata: dict[str, Any] | None = None,
+) -> tuple[str, str]:
+    enabled = set(enabled_channels)
+    archived = set(archived_keys)
+    for item in sessions:
+        key = item.get("key") or ""
+        if key in archived:
+            continue
+        if key == UNIFIED_SESSION_KEY:
+            route = last_channel_from_metadata(unified_session_metadata)
+            if route is not None:
+                channel, chat_id = route
+                if channel not in {"cli", "system"} and channel in enabled:
+                    return channel, chat_id
+            continue
+        if ":" not in key:
+            continue
+        channel, chat_id = key.split(":", 1)
+        if channel in {"cli", "system"}:
+            continue
+        if channel in enabled and chat_id:
+            return channel, chat_id
+    return "cli", "direct"
+
+
+_GATEWAY_HEALTH_MAX_CONNECTIONS = 64
+_GATEWAY_HEALTH_READ_TIMEOUT_SECONDS = 2.0
+
+
+def _print_gateway_health_endpoint(host: str, port: int) -> None:
+    """Print a usable health URL and make non-loopback binds explicit."""
+    console.print(
+        f"[green]✓[/green] Health endpoint: {_gateway_health_url(host, port)}"
+        f"{_gateway_health_bind_note(host)}"
+    )
+    if is_loopback_host(host):
+        return
+
+    console.print(
+        "[yellow]Warning: the unauthenticated health endpoint is listening beyond loopback "
+        "and may be reachable from other devices. "
+        f"Keep port {port} private or protect it with a firewall or reverse proxy.[/yellow]"
+    )
+
+
+def _run_gateway(
+    config: Config,
+    *,
+    port: int | None = None,
+    open_browser_url: str | None = None,
+    webui_static_dist: bool = True,
+    webui_bundle_mode: BuildMode = "warn",
+    webui_runtime_surface: str = "browser",
+    webui_runtime_capabilities: dict[str, Any] | None = None,
+    health_server_enabled: bool = True,
+    unconfigured_provider_error: str | None = None,
+) -> None:
+    """Shared gateway runtime; ``open_browser_url`` opens a tab once channels are up."""
+    from nanobot.agent.model_presets import load_model_preset_catalog
+    from nanobot.agent.tools.message import MessageTool
+    from nanobot.agent.turn_delivery import TurnDeliveryFactory
+    from nanobot.bus.queue import MessageBus
+    from nanobot.bus.runtime_events import RuntimeEventBus
+    from nanobot.channels.manager import ChannelManager
+    from nanobot.config.watcher import watch_config_file
+    from nanobot.cron.bound_runner import run_bound_cron_job
+    from nanobot.cron.service import CronJobSkippedError, CronService
+    from nanobot.cron.session_turns import is_bound_cron_job
+    from nanobot.cron.types import CronJob
+    from nanobot.providers.factory import (
+        ProviderSnapshot,
+        build_provider_snapshot,
+        build_unconfigured_provider_snapshot,
+        load_provider_snapshot,
+    )
+    from nanobot.providers.fallback_provider import FallbackProvider
+    from nanobot.providers.image_generation import image_gen_provider_configs
+    from nanobot.session.manager import SessionManager
+    from nanobot.session.webui_turns import (
+        WebuiTurnCoordinator,
+        WebuiTurnRoutePolicy,
+        build_webui_fallback_model_observer,
+    )
+    from nanobot.triggers.local_runner import run_local_trigger_queue
+    from nanobot.triggers.local_store import LocalTriggerStore
+    from nanobot.webui.token_usage import TokenUsageHook
+
+    port = port if port is not None else config.gateway.port
+    webui_url = _webui_browser_url(config)
+    gateway_host_for_browser = _host_for_local_browser(config.gateway.host)
+    if health_server_enabled and _tcp_endpoint_reachable(gateway_host_for_browser, port):
+        _print_foreground_port_conflict(
+            webui_url=webui_url,
+            gateway_host=config.gateway.host,
+            gateway_port=port,
+        )
+        raise typer.Exit(1)
+    if _webui_channel_enabled(config) and _webui_endpoint_reachable(webui_url):
+        _print_foreground_port_conflict(
+            webui_url=webui_url,
+            gateway_host=config.gateway.host,
+            gateway_port=port,
+        )
+        raise typer.Exit(1)
+
+    console.print(f"{__logo__} Starting nanobot gateway version {__version__} on port {port}...")
+    _prepare_webui_bundle_for_gateway(
+        config,
+        mode=webui_bundle_mode,
+        webui_static_dist=webui_static_dist,
+    )
+    sync_workspace_templates(config.workspace_path)
+    bus = MessageBus()
+    runtime_events = RuntimeEventBus()
+    fallback_model_observer = build_webui_fallback_model_observer(bus)
+
+    def _observe_fallback_models(snapshot: ProviderSnapshot) -> ProviderSnapshot:
+        if isinstance(snapshot.provider, FallbackProvider):
+            snapshot.provider.set_fallback_model_observer(fallback_model_observer)
+        return snapshot
+
+    def _load_gateway_provider_snapshot(
+        *args: Any,
+        **kwargs: Any,
+    ) -> ProviderSnapshot:
+        try:
+            return _observe_fallback_models(load_provider_snapshot(*args, **kwargs))
+        except ValueError as exc:
+            if unconfigured_provider_error is None:
+                raise
+            return build_unconfigured_provider_snapshot(config, str(exc))
+
+    if unconfigured_provider_error is not None:
+        provider_snapshot = build_unconfigured_provider_snapshot(
+            config,
+            unconfigured_provider_error,
+        )
+    else:
+        try:
+            provider_snapshot = _observe_fallback_models(build_provider_snapshot(config))
+        except ValueError as exc:
+            console.print(f"[red]Error: {exc}[/red]")
+            raise typer.Exit(1) from exc
+    session_manager = SessionManager(config.workspace_path)
+
+    # Self-heal the gateway state file with the current PID after any restart.
+    from nanobot.config.loader import get_config_path
+    from nanobot.gateway.runtime import GatewayRuntime, GatewayRuntimePaths
+
+    config_path = str(get_config_path().resolve(strict=False))
+    GatewayRuntime.refresh_state_pid(
+        paths=GatewayRuntimePaths.for_instance(
+            workspace=str(config.workspace_path)
+            if not is_default_workspace(config.workspace_path)
+            else None,
+            config_path=config_path,
+        )
+    )
+
+    # Preserve existing single-workspace installs, but keep custom workspaces clean.
+    if is_default_workspace(config.workspace_path):
+        _migrate_cron_store(config)
+
+    # Create cron service with workspace-scoped store
+    cron_store_path = config.workspace_path / "cron" / "jobs.json"
+    cron = CronService(cron_store_path)
+    trigger_store = LocalTriggerStore(config.workspace_path)
+
+    turn_delivery_factory = TurnDeliveryFactory(
+        bus,
+        runtime_events,
+        route_policy=WebuiTurnRoutePolicy(session_manager),
+    )
+
+    # Create agent with cron service
+    agent = AgentLoop.from_config(
+        config, bus,
+        provider=provider_snapshot.provider,
+        model=provider_snapshot.model,
+        context_window_tokens=provider_snapshot.context_window_tokens,
+        cron_service=cron,
+        session_manager=session_manager,
+        image_generation_provider_configs=image_gen_provider_configs(config),
+        provider_snapshot_loader=_load_gateway_provider_snapshot,
+        preset_catalog_loader=load_model_preset_catalog,
+        runtime_events=runtime_events,
+        turn_delivery_factory=turn_delivery_factory,
+        provider_signature=provider_snapshot.signature,
+        hooks=[TokenUsageHook(timezone_name=config.agents.defaults.timezone)],
+        local_trigger_store=trigger_store,
+        hook_factories=[create_file_edit_activity_hook],
+    )
+    def _schedule_webui_background(awaitable: Awaitable[None]) -> None:
+        agent.schedule_background(cast(Coroutine[Any, Any, None], awaitable))
+
+    webui_turn_coordinator = WebuiTurnCoordinator(
+        bus=bus,
+        sessions=session_manager,
+        schedule_background=_schedule_webui_background,
+    )
+    webui_turn_coordinator.subscribe(runtime_events)
+    from nanobot.bus.events import OutboundMessage
+    from nanobot.session.keys import session_key_for_channel
+
+    def _channel_session_key(channel: str, chat_id: str) -> str:
+        return session_key_for_channel(
+            channel,
+            chat_id,
+            unified_session=config.agents.defaults.unified_session,
+        )
+
+    async def _deliver_to_channel(
+        msg: OutboundMessage, *, record: bool = False, session_key: str | None = None,
+    ) -> None:
+        """Publish a user-visible message and mirror it into that channel's session."""
+        metadata = dict(msg.metadata or {})
+        record = record or bool(metadata.pop("_record_channel_delivery", False))
+        if metadata != (msg.metadata or {}):
+            msg = OutboundMessage(
+                channel=msg.channel,
+                chat_id=msg.chat_id,
+                content=msg.content,
+                reply_to=msg.reply_to,
+                media=msg.media,
+                metadata=metadata,
+                buttons=msg.buttons,
+            )
+        if (
+            record
+            and msg.channel != "cli"
+            and msg.content.strip()
+            and hasattr(session_manager, "get_or_create")
+            and hasattr(session_manager, "save")
+        ):
+            key = session_key or _channel_session_key(msg.channel, msg.chat_id)
+            session = session_manager.get_or_create(key)
+            extra: dict[str, Any] = {"_channel_delivery": True}
+            if msg.media:
+                extra["media"] = list(msg.media)
+            session.add_message("assistant", msg.content, **extra)
+            session_manager.save(session)
+        await bus.publish_outbound(msg)
+
+    message_tool = agent.tools.get("message")
+    if isinstance(message_tool, MessageTool):
+        message_tool.set_send_callback(_deliver_to_channel)
+
+    # Set cron callback (needs agent)
+    async def on_cron_job(job: CronJob) -> str | None:
+        """Execute a cron job through the agent."""
+        async def _silent(*_args: Any, **_kwargs: Any) -> None:
+            pass
+
+        # Dream is an internal job — run directly, not through the agent loop.
+        if job.name == "dream":
+            from nanobot.agent.memory import DreamRunProgress, MemoryStore
+
+            dream_session_key = MemoryStore.dream_session_key
+            prune_dream_sessions = MemoryStore.prune_dream_sessions
+
+            store = agent.context.memory
+            progress = DreamRunProgress()
+            resp = None
+            diff_body = ""
+            try:
+                result = store.build_dream_prompt()
+                if result is None:
+                    logger.info("Dream: nothing to process")
+                    return None
+                prompt, last_cursor = result
+                key = dream_session_key()
+                dream_runtime = agent.dream_runtime()
+                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.
+                diff_body = store.dream_content_diff()
+                completed = MemoryStore.dream_run_completed(
+                    resp,
+                    had_tool_errors=progress.had_tool_errors,
+                )
+                if completed:
+                    store.set_last_dream_cursor(last_cursor)
+                    if diff_body:
+                        logger.info(
+                            "Dream cron job completed, cursor advanced to {}",
+                            last_cursor,
+                        )
+                    else:
+                        logger.info(
+                            "Dream cron job completed with no memory changes; "
+                            "cursor advanced to {}",
+                            last_cursor,
+                        )
+                else:
+                    logger.warning(
+                        "Dream cron job did not complete; cursor remains at {}",
+                        store.get_last_dream_cursor(),
+                    )
+            except Exception:
+                logger.exception("Dream cron job failed")
+            finally:
+                from nanobot.webui.token_usage import record_response_token_usage
+
+                record_response_token_usage(
+                    resp,
+                    source="dream",
+                    timezone_name=config.agents.defaults.timezone,
+                )
+                sha = _commit_dream_changes(store)
+                if sha:
+                    logger.info("Dream commit: {}", sha)
+                store.compact_history()
+                prune_dream_sessions(agent.sessions.sessions_dir)
+            return None
+
+        # Heartbeat is a system job that checks HEARTBEAT.md for active tasks.
+        if job.name == "heartbeat":
+            heartbeat_file = config.workspace_path / "HEARTBEAT.md"
+            try:
+                content = heartbeat_file.read_text(encoding="utf-8")
+            except OSError:
+                logger.debug("Heartbeat: HEARTBEAT.md missing")
+                return None
+            if not _heartbeat_has_active_tasks(content):
+                logger.debug("Heartbeat: HEARTBEAT.md has no active tasks")
+                return None
+
+            channel, chat_id = _pick_heartbeat_target()
+            if channel == "cli":
+                return None
+
+            prompt = (
+                _HEARTBEAT_PREAMBLE
+                + f"You are executing periodic heartbeat tasks. Read the active tasks below, perform each one, and report what you did:\n\n{content}"
+            )
+
+            # Internal check: funnel all output through the post-run gate so the
+            # turn can't deliver directly via the message tool and skip it.
+            suppress_token = None
+            if isinstance(message_tool, MessageTool):
+                suppress_token = message_tool.set_suppress_delivery(True)
+            try:
+                resp = await agent.process_direct(
+                    prompt,
+                    session_key="heartbeat",
+                    channel=channel,
+                    chat_id=chat_id,
+                    on_progress=_silent,
+                )
+            finally:
+                if isinstance(message_tool, MessageTool) and suppress_token is not None:
+                    message_tool.reset_suppress_delivery(suppress_token)
+
+            # Keep a small tail of heartbeat history so the loop stays bounded.
+            session = agent.sessions.get_or_create("heartbeat")
+            session.retain_recent_legal_suffix(hb_cfg.keep_recent_messages)
+            agent.sessions.save(session)
+
+            if not resp or not resp.content:
+                return
+
+            response = resp.content
+
+            evaluator_prompt = resolve_evaluator_prompt(config.workspace_path)
+
+            # Fail closed: stay silent on evaluator failure instead of notifying.
+            should_notify = await evaluate_response(
+                response=response,
+                task_context=prompt,
+                provider=agent.provider,
+                model=agent.model,
+                evaluator_prompt=evaluator_prompt,
+                default_notify=False,
+            )
+
+            if should_notify:
+                logger.info("Heartbeat: completed, delivering response")
+                await _deliver_to_channel(
+                    OutboundMessage(channel=channel, chat_id=chat_id, content=response),
+                    record=True,
+                )
+            else:
+                logger.info("Heartbeat: silenced by post-run evaluation")
+            return response
+
+        if is_bound_cron_job(job):
+            return await run_bound_cron_job(job, agent=agent, cron=cron)
+
+        reason = "unbound agent cron job must be recreated from a chat session"
+        logger.warning(
+            "Cron: skipped unbound agent job '{}' ({}): {}",
+            job.name,
+            job.id,
+            reason,
+        )
+        raise CronJobSkippedError(reason)
+
+    cron.on_job = on_cron_job
+
+    def _webui_runtime_model_name() -> str | None:
+        return agent.model.strip() or None
+
+    def _webui_skill_state_action(disabled_skills: set[str]) -> None:
+        config.agents.defaults.disabled_skills = sorted(disabled_skills)
+        agent.context.skills.disabled_skills = set(disabled_skills)
+        agent.subagents.disabled_skills = set(disabled_skills)
+
+    # Create channel manager (forwards SessionManager so the WebSocket channel
+    # can serve the embedded webui's REST surface).
+    channels = ChannelManager(
+        config,
+        bus,
+        session_manager=session_manager,
+        cron_service=cron,
+        local_trigger_store=trigger_store,
+        webui_runtime_model_name=_webui_runtime_model_name,
+        webui_cron_pending_job_ids=agent.pending_cron_job_ids_for_session,
+        webui_local_trigger_pending_ids=agent.pending_local_trigger_ids_for_session,
+        webui_static_dist=webui_static_dist,
+        webui_runtime_surface=webui_runtime_surface,
+        webui_runtime_capabilities=webui_runtime_capabilities,
+        webui_skill_state_action=_webui_skill_state_action,
+    )
+
+    def _pick_heartbeat_target() -> tuple[str, str]:
+        """Pick a routable channel/chat target for heartbeat-triggered messages."""
+        sidebar_state = read_webui_sidebar_state()
+        unified_metadata = None
+        if config.agents.defaults.unified_session:
+            record = session_manager.read_session_metadata(UNIFIED_SESSION_KEY)
+            if isinstance(record, dict) and isinstance(record.get("metadata"), dict):
+                unified_metadata = record["metadata"]
+        return _pick_heartbeat_target_from_sessions(
+            enabled_channels=channels.enabled_channels,
+            sessions=session_manager.list_sessions(),
+            archived_keys=sidebar_state.get("archived_keys", []),
+            unified_session_metadata=unified_metadata,
+        )
+
+    if channels.enabled_channels:
+        console.print(f"[green]✓[/green] Channels enabled: {', '.join(channels.enabled_channels)}")
+    else:
+        console.print("[yellow]Warning: No channels enabled[/yellow]")
+
+    cron_status = cron.status()
+    cron_job_count = cast(int, cron_status["jobs"])
+    if cron_job_count > 0:
+        console.print(f"[green]✓[/green] Cron: {cron_job_count} scheduled jobs")
+
+    hb_cfg = config.gateway.heartbeat
+    if hb_cfg.enabled:
+        console.print(f"[green]✓[/green] Heartbeat: every {hb_cfg.interval_s}s")
+    else:
+        console.print("[yellow]✗[/yellow] Heartbeat: disabled")
+
+    async def _health_server(host: str, health_port: int) -> None:
+        """Lightweight HTTP health endpoint on the gateway port."""
+        import json as _json
+
+        connection_slots = asyncio.Semaphore(_GATEWAY_HEALTH_MAX_CONNECTIONS)
+
+        async def handle(
+            reader: asyncio.StreamReader,
+            writer: asyncio.StreamWriter,
+        ) -> None:
+            if connection_slots.locked():
+                writer.close()
+                return
+
+            async with connection_slots:
+                try:
+                    data = await asyncio.wait_for(
+                        reader.read(4096),
+                        timeout=_GATEWAY_HEALTH_READ_TIMEOUT_SECONDS,
+                    )
+                    request_line = data.split(b"\r\n", 1)[0].decode(
+                        "utf-8", errors="replace",
+                    )
+                    method, path = "", ""
+                    parts = request_line.split(" ")
+                    if len(parts) >= 2:
+                        method, path = parts[0], parts[1]
+
+                    if method == "GET" and path == "/health":
+                        body = _json.dumps({"status": "ok"})
+                        status = "200 OK"
+                        content_type = "application/json"
+                    else:
+                        body = "Not Found"
+                        status = "404 Not Found"
+                        content_type = "text/plain"
+
+                    resp = (
+                        f"HTTP/1.0 {status}\r\n"
+                        f"Content-Type: {content_type}\r\n"
+                        f"Content-Length: {len(body)}\r\n"
+                        "Connection: close\r\n"
+                        f"\r\n{body}"
+                    )
+                    writer.write(resp.encode())
+                    await writer.drain()
+                except (asyncio.TimeoutError, ConnectionError):
+                    pass
+                finally:
+                    writer.close()
+
+        server = await asyncio.start_server(handle, host, health_port)
+        _print_gateway_health_endpoint(host, health_port)
+        async with server:
+            await server.serve_forever()
+    # Register Dream system job (idempotent on restart)
+    from nanobot.cron.types import CronJob, CronPayload, CronSchedule
+    dream_cfg = config.agents.defaults.dream
+    if dream_cfg.enabled:
+        cron.register_system_job(CronJob(
+            id="dream",
+            name="dream",
+            schedule=dream_cfg.build_schedule(config.agents.defaults.timezone),
+            payload=CronPayload(kind="system_event"),
+        ))
+        console.print(f"[green]✓[/green] Dream: {dream_cfg.describe_schedule()}")
+    else:
+        console.print("[yellow]○[/yellow] Dream: disabled")
+        _advance_dream_cursor_if_behind(agent.context.memory)
+
+    # Register Heartbeat system job (idempotent on restart)
+    if hb_cfg.enabled:
+        cron.register_system_job(CronJob(
+            id="heartbeat",
+            name="heartbeat",
+            schedule=CronSchedule(
+                kind="every",
+                every_ms=hb_cfg.interval_s * 1000,
+                tz=config.agents.defaults.timezone,
+            ),
+            payload=CronPayload(kind="system_event"),
+        ))
+
+    async def _open_browser_when_ready() -> None:
+        """Wait for the gateway to bind, then point the user's browser at the webui."""
+        if not open_browser_url:
+            return
+        import webbrowser
+        from urllib.parse import urlparse
+
+        parsed = urlparse(open_browser_url)
+        target_host = parsed.hostname or config.gateway.host or "127.0.0.1"
+        target_port = parsed.port or port
+        # Channels start asynchronously; a short poll lets us avoid racing the bind.
+        for _ in range(40):  # ~4s max
+            try:
+                _reader, writer = await asyncio.open_connection(
+                    target_host,
+                    target_port,
+                )
+                writer.close()
+                with suppress(Exception):
+                    await writer.wait_closed()
+                break
+            except OSError:
+                await asyncio.sleep(0.1)
+        try:
+            webbrowser.open(open_browser_url)
+            console.print(f"[green]✓[/green] Opened browser at {open_browser_url}")
+        except Exception as e:
+            console.print(f"[yellow]Could not open browser ({e}); visit {open_browser_url}[/yellow]")
+
+    async def run() -> None:
+        tasks: list[asyncio.Task[Any]] = []
+        shutdown_task: asyncio.Task[Any] | None = None
+        runtime_tasks: asyncio.Future[list[Any]] | None = None
+        runtime_tasks_drained = False
+        shutdown_event = asyncio.Event()
+        cli_terminal._ensure_interactive_tty_mode()
+        restore_shutdown_handlers = _install_gateway_shutdown_handlers(
+            asyncio.get_running_loop(),
+            shutdown_event,
+            tasks,
+            console.print,
+        )
+        try:
+            await cron.start()
+            # Re-read once on first admission to close the watcher subscription window.
+            agent.runtime_resolver.invalidate()
+            tasks = [
+                asyncio.create_task(
+                    watch_config_file(
+                        Path(config_path),
+                        lambda: agent.invalidate_runtime_config(),
+                    ),
+                    name="nanobot-config-watcher",
+                ),
+                asyncio.create_task(agent.run(), name="nanobot-agent-loop"),
+                asyncio.create_task(channels.start_all(), name="nanobot-channels"),
+                asyncio.create_task(
+                    run_local_trigger_queue(
+                        store=trigger_store,
+                        submit_turn=agent.submit_local_trigger_turn,
+                        is_channel_enabled=lambda name: channels.get_channel(name) is not None,
+                    ),
+                    name="nanobot-local-triggers",
+                ),
+            ]
+            if health_server_enabled:
+                tasks.append(asyncio.create_task(
+                    _health_server(config.gateway.host, port),
+                    name="nanobot-health-server",
+                ))
+            if open_browser_url:
+                tasks.append(asyncio.create_task(
+                    _open_browser_when_ready(),
+                    name="nanobot-open-browser",
+                ))
+            runtime_tasks = asyncio.gather(*tasks)
+            shutdown_task = asyncio.create_task(
+                shutdown_event.wait(),
+                name="nanobot-gateway-shutdown",
+            )
+            done, _pending = await asyncio.wait(
+                {runtime_tasks, shutdown_task},
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            if runtime_tasks in done:
+                runtime_tasks_drained = True
+                await runtime_tasks
+            else:
+                runtime_tasks.cancel()
+        except KeyboardInterrupt:
+            console.print("\nShutting down...")
+        except Exception:
+            import traceback
+
+            console.print("\n[red]Error: Gateway crashed unexpectedly[/red]")
+            console.print(traceback.format_exc())
+        finally:
+            try:
+                if shutdown_task and not shutdown_task.done():
+                    shutdown_task.cancel()
+                    with suppress(asyncio.CancelledError):
+                        await shutdown_task
+                cron.stop()
+                agent.stop()
+                # Some SDKs swallow task cancellation while attempting to reconnect.
+                # Close channel transports before waiting for their runners to exit.
+                await channels.stop_all()
+                for task in tasks:
+                    if not task.done():
+                        task.cancel()
+                if tasks:
+                    await asyncio.gather(*tasks, return_exceptions=True)
+                if runtime_tasks is not None and not runtime_tasks_drained:
+                    with suppress(asyncio.CancelledError, Exception):
+                        await runtime_tasks
+                # Flush all cached sessions to durable storage before exit.
+                # This prevents data loss on filesystems with write-back
+                # caching (rclone VFS, NFS, FUSE mounts, etc.).
+                flushed = agent.sessions.flush_all()
+                if flushed:
+                    logger.info("Shutdown: flushed {} session(s) to disk", flushed)
+            finally:
+                restore_shutdown_handlers()
+
+    asyncio.run(run())

nanobot/cli/log_control.py

@@ -0,0 +1,12 @@
+"""Runtime log visibility controls shared by CLI commands."""
+
+from loguru import logger
+
+__all__ = ["_set_nanobot_logs"]
+
+
+def _set_nanobot_logs(enabled: bool) -> None:
+    if enabled:
+        logger.enable("nanobot")
+    else:
+        logger.disable("nanobot")

nanobot/cli/provider.py

@@ -0,0 +1,372 @@
+"""Typer commands for OAuth provider authentication."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import suppress
+from importlib import import_module
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, cast
+
+import typer
+from rich.console import Console
+
+from nanobot import __logo__
+
+if TYPE_CHECKING:
+    from nanobot.providers.registry import ProviderSpec
+
+
+console = Console()
+provider_app = typer.Typer(help="Manage providers")
+
+_PROVIDER_DISPLAY: dict[str, str] = {
+    "openai_codex": "OpenAI Codex",
+    "xai_grok": "xAI Grok",
+    "github_copilot": "GitHub Copilot",
+}
+
+_OAUTH_PROVIDER_DEFAULT_MODELS: dict[str, str] = {
+    "openai_codex": "openai-codex/gpt-5.6-sol",
+    "xai_grok": "xai-grok/grok-4.5",
+    "github_copilot": "github-copilot/gpt-5.4-mini",
+}
+
+
+class _OAuthToken(Protocol):
+    access: str | None
+    account_id: str | None
+
+
+class _GetOAuthToken(Protocol):
+    def __call__(self, *, proxy: str | None = None) -> _OAuthToken | None: ...
+
+
+class _LoginOAuthInteractive(Protocol):
+    def __call__(
+        self,
+        *,
+        print_fn: Callable[[str], None],
+        prompt_fn: Callable[[str], str],
+        proxy: str | None = None,
+    ) -> _OAuthToken | None: ...
+
+
+class _OAuthProviderConfig(Protocol):
+    token_filename: str
+
+
+class _TokenStorage(Protocol):
+    def get_token_path(self) -> Path: ...
+
+
+class _FileTokenStorageFactory(Protocol):
+    def __call__(self, *, token_filename: str) -> _TokenStorage: ...
+
+
+def _required_module_attribute(module_name: str, attribute: str) -> object:
+    """Load an optional dependency attribute with import-compatible errors."""
+    module = import_module(module_name)
+    try:
+        return getattr(module, attribute)
+    except AttributeError as exc:
+        raise ImportError(f"{module_name}.{attribute} is unavailable") from exc
+
+
+def _load_openai_oauth_client() -> tuple[_GetOAuthToken, _LoginOAuthInteractive]:
+    """Load the optional untyped OAuth client behind a typed boundary."""
+    return (
+        cast(_GetOAuthToken, _required_module_attribute("oauth_cli_kit", "get_token")),
+        cast(
+            _LoginOAuthInteractive,
+            _required_module_attribute("oauth_cli_kit", "login_oauth_interactive"),
+        ),
+    )
+
+
+def _load_openai_oauth_storage() -> tuple[_OAuthProviderConfig, _FileTokenStorageFactory]:
+    """Load the optional untyped OAuth storage API behind a typed boundary."""
+    return (
+        cast(
+            _OAuthProviderConfig,
+            _required_module_attribute(
+                "oauth_cli_kit.providers",
+                "OPENAI_CODEX_PROVIDER",
+            ),
+        ),
+        cast(
+            _FileTokenStorageFactory,
+            _required_module_attribute("oauth_cli_kit.storage", "FileTokenStorage"),
+        ),
+    )
+
+
+def _resolve_oauth_provider(provider: str) -> ProviderSpec:
+    """Resolve and validate an OAuth provider configuration."""
+    from nanobot.providers.registry import PROVIDERS
+
+    key = provider.replace("-", "_")
+    spec = next((s for s in PROVIDERS if s.name == key and s.is_oauth), None)
+    if not spec:
+        names = ", ".join(s.name.replace("_", "-") for s in PROVIDERS if s.is_oauth)
+        console.print(f"[red]Unknown OAuth provider: {provider}[/red]  Supported: {names}")
+        raise typer.Exit(1)
+    return spec
+
+
+def _set_oauth_provider_as_main(
+    provider_name: str,
+    *,
+    model: str | None = None,
+    config_path: str | None = None,
+) -> None:
+    """Persist an OAuth provider as the active agent provider."""
+    from nanobot.config.loader import get_config_path, load_config, save_config, set_config_path
+
+    resolved_config_path = Path(config_path).expanduser().resolve() if config_path else None
+    if resolved_config_path is not None and get_config_path() != resolved_config_path:
+        set_config_path(resolved_config_path)
+        console.print(f"[dim]Using config: {resolved_config_path}[/dim]")
+
+    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
+    if provider_name == "xai_grok" and selected_model == "xai-grok/grok-4.5":
+        config.agents.defaults.context_window_tokens = 500_000
+    save_config(config, resolved_config_path)
+
+    saved_path = resolved_config_path or get_config_path()
+    console.print(
+        f"[green]✓ Set {provider_name.replace('_', '-')} as the main provider[/green]  "
+        f"[dim]{selected_model}[/dim]"
+    )
+    console.print(f"[dim]Saved: {saved_path}[/dim]")
+
+
+@provider_app.command("login")
+def provider_login(
+    provider: str = typer.Argument(
+        ...,
+        help="OAuth provider (e.g. 'openai-codex', 'xai-grok', 'github-copilot')",
+    ),
+    set_main: bool = typer.Option(
+        False,
+        "--set-main",
+        "--main",
+        help="Set this OAuth provider as the active agent provider after login",
+    ),
+    model: str | None = typer.Option(
+        None,
+        "--model",
+        "-m",
+        help="Model to use when setting this provider as the active provider",
+    ),
+    config: str | None = typer.Option(None, "--config", "-c", help="Path to config file"),
+):
+    """Authenticate with an OAuth provider."""
+    spec = _resolve_oauth_provider(provider)
+
+    handler = _LOGIN_HANDLERS.get(spec.name)
+    if not handler:
+        console.print(f"[red]Login not implemented for {spec.label}[/red]")
+        raise typer.Exit(1)
+
+    if config:
+        from nanobot.config.loader import set_config_path
+
+        resolved_config_path = Path(config).expanduser().resolve()
+        set_config_path(resolved_config_path)
+        console.print(f"[dim]Using config: {resolved_config_path}[/dim]")
+
+    console.print(f"{__logo__} OAuth Login - {spec.label}\n")
+    handler()
+    if set_main or model:
+        _set_oauth_provider_as_main(spec.name, model=model, config_path=config)
+
+
+@provider_app.command("logout")
+def provider_logout(
+    provider: str = typer.Argument(
+        ...,
+        help="OAuth provider (e.g. 'openai-codex', 'xai-grok', 'github-copilot')",
+    ),
+    config: str | None = typer.Option(None, "--config", "-c", help="Path to config file"),
+):
+    """Log out from an OAuth provider."""
+    spec = _resolve_oauth_provider(provider)
+
+    handler = _LOGOUT_HANDLERS.get(spec.name)
+    if not handler:
+        console.print(f"[red]Logout not implemented for {spec.label}[/red]")
+        raise typer.Exit(1)
+
+    if config:
+        from nanobot.config.loader import set_config_path
+
+        resolved_config_path = Path(config).expanduser().resolve()
+        set_config_path(resolved_config_path)
+        console.print(f"[dim]Using config: {resolved_config_path}[/dim]")
+
+    console.print(f"{__logo__} OAuth Logout - {spec.label}\n")
+    handler()
+
+
+def _login_openai_codex() -> None:
+    try:
+        from nanobot.config.loader import load_config, resolve_config_env_vars
+
+        get_token, login_oauth_interactive = _load_openai_oauth_client()
+        proxy = None
+        try:
+            proxy = resolve_config_env_vars(load_config()).providers.openai_codex.proxy or None
+        except ValueError as e:
+            console.print(f"[red]{e}[/red]")
+            raise typer.Exit(1) from e
+        token = None
+        with suppress(Exception):
+            token = get_token(proxy=proxy)
+        if not (token and token.access):
+            console.print("[cyan]Starting interactive OAuth login...[/cyan]\n")
+            token = login_oauth_interactive(
+                print_fn=lambda s: console.print(s),
+                prompt_fn=lambda s: typer.prompt(s),
+                proxy=proxy,
+            )
+        if not (token and token.access):
+            console.print("[red]✗ Authentication failed[/red]")
+            raise typer.Exit(1)
+        console.print(
+            f"[green]✓ Authenticated with OpenAI Codex[/green]  [dim]{token.account_id}[/dim]"
+        )
+    except ImportError:
+        console.print("[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]")
+        raise typer.Exit(1)
+
+
+def _logout_openai_codex() -> None:
+    """Clear local OAuth credentials for OpenAI Codex."""
+    try:
+        provider_config, storage_factory = _load_openai_oauth_storage()
+    except ImportError:
+        console.print("[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]")
+        raise typer.Exit(1)
+
+    storage = storage_factory(token_filename=provider_config.token_filename)
+    _delete_oauth_files(storage.get_token_path(), _PROVIDER_DISPLAY["openai_codex"])
+
+
+def _login_xai_grok() -> None:
+    """Authenticate with xAI using the Grok subscription OAuth contract."""
+    from nanobot.config.loader import load_config, resolve_config_env_vars
+    from nanobot.providers.xai_oauth import get_xai_oauth_token, login_xai_oauth
+
+    try:
+        proxy = resolve_config_env_vars(load_config()).providers.xai_grok.proxy or None
+    except ValueError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    token = None
+    with suppress(Exception):
+        token = get_xai_oauth_token(proxy=proxy)
+    if not (token and token.access):
+        console.print(
+            "[cyan]Starting xAI browser sign-in for your X Premium / Grok subscription...[/cyan]\n"
+        )
+        try:
+            token = login_xai_oauth(
+                print_fn=lambda message: console.print(message),
+                prompt_fn=lambda prompt: typer.prompt(prompt),
+                proxy=proxy,
+            )
+        except Exception as exc:
+            console.print(f"[red]Authentication error: {exc}[/red]")
+            raise typer.Exit(1) from exc
+    account = token.account_id or "xAI account"
+    console.print(f"[green]✓ Authenticated with xAI[/green]  [dim]{account}[/dim]")
+    console.print(
+        "[dim]Hosted X Search is enabled automatically when the selected model supports it.[/dim]"
+    )
+
+
+def _logout_xai_grok() -> None:
+    """Clear local xAI OAuth credentials for this nanobot instance."""
+    from nanobot.providers.xai_oauth import get_xai_oauth_storage_path, logout_xai_oauth
+
+    token_path = get_xai_oauth_storage_path()
+    provider_label = _PROVIDER_DISPLAY["xai_grok"]
+    if logout_xai_oauth():
+        console.print(f"[green]✓ Logged out from {provider_label}[/green]")
+        console.print(f"[dim]Removed: {token_path}[/dim]")
+    else:
+        console.print(f"[yellow]! No local OAuth credentials found for {provider_label}[/yellow]")
+
+
+def _logout_github_copilot() -> None:
+    """Clear local OAuth credentials for GitHub Copilot."""
+    try:
+        from nanobot.providers.github_copilot_provider import get_storage
+    except ImportError:
+        console.print("[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]")
+        raise typer.Exit(1)
+
+    storage = get_storage()
+    _delete_oauth_files(storage.get_token_path(), _PROVIDER_DISPLAY["github_copilot"])
+
+
+def _delete_oauth_files(token_path: Path, provider_label: str) -> None:
+    """Delete OAuth token and lock files, reporting the result."""
+    removed_paths: list[Path] = []
+    skipped: list[tuple[Path, OSError]] = []
+    for path in (token_path, token_path.with_suffix(".lock")):
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            continue
+        except OSError as exc:
+            skipped.append((path, exc))
+            continue
+        removed_paths.append(path)
+
+    if not removed_paths and not skipped:
+        console.print(f"[yellow]! No local OAuth credentials found for {provider_label}[/yellow]")
+        return
+
+    if removed_paths:
+        console.print(f"[green]✓ Logged out from {provider_label}[/green]")
+        for path in removed_paths:
+            console.print(f"[dim]Removed: {path}[/dim]")
+    for path, exc in skipped:
+        console.print(f"[yellow]! Could not remove {path}: {exc}[/yellow]")
+
+
+def _login_github_copilot() -> None:
+    try:
+        from nanobot.providers.github_copilot_provider import login_github_copilot
+
+        console.print("[cyan]Starting GitHub Copilot device flow...[/cyan]\n")
+        token = login_github_copilot(
+            print_fn=lambda s: console.print(s),
+            prompt_fn=lambda s: typer.prompt(s),
+        )
+        account = token.account_id or "GitHub"
+        console.print(
+            f"[green]✓ Authenticated with GitHub Copilot[/green]  [dim]{account}[/dim]"
+        )
+    except Exception as e:
+        console.print(f"[red]Authentication error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+_LOGIN_HANDLERS: dict[str, Callable[[], None]] = {
+    "openai_codex": _login_openai_codex,
+    "xai_grok": _login_xai_grok,
+    "github_copilot": _login_github_copilot,
+}
+_LOGOUT_HANDLERS: dict[str, Callable[[], None]] = {
+    "openai_codex": _logout_openai_codex,
+    "xai_grok": _logout_xai_grok,
+    "github_copilot": _logout_github_copilot,
+}

nanobot/cli/runtime_config.py

@@ -0,0 +1,185 @@
+"""Configuration loading and diagnostics shared by CLI commands."""
+
+from pathlib import Path
+
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+from rich.markup import escape
+from rich.text import Text
+
+from nanobot.config.schema import Config
+
+__all__ = [
+    "_load_config_for_cli",
+    "_load_inspection_config",
+    "_load_runtime_config",
+    "_migrate_cron_store",
+    "_model_display",
+    "_print_agent_start_error",
+    "_print_config_error",
+    "_print_model_setup_steps",
+    "_print_runtime_config_validation_error",
+    "_provider_setup_error",
+]
+
+console = Console()
+
+
+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 ""
+    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 set_config_path
+
+    config_path = None
+    if config:
+        config_path = Path(config).expanduser().resolve()
+        if not config_path.exists():
+            console.print(f"[red]Error: Config file not found: {config_path}[/red]")
+            raise typer.Exit(1)
+        set_config_path(config_path)
+        console.print(f"[dim]Using config: {config_path}[/dim]")
+
+    loaded = _load_config_for_cli(config_path, resolve_env=True)
+    if workspace:
+        loaded.agents.defaults.workspace = workspace
+    return loaded
+
+
+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
+    if config:
+        config_path = Path(config).expanduser().resolve(strict=False)
+        set_config_path(config_path)
+        console.print(f"[dim]Using config: {config_path}[/dim]")
+
+    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
+    if workspace:
+        loaded.agents.defaults.workspace = workspace
+    return display_path, loaded
+
+
+def _migrate_cron_store(config: "Config") -> None:
+    """One-time migration: move legacy global cron store into the workspace."""
+    from nanobot.config.paths import get_cron_dir
+
+    legacy_path = get_cron_dir() / "jobs.json"
+    new_path = config.workspace_path / "cron" / "jobs.json"
+    if legacy_path.is_file() and not new_path.exists():
+        new_path.parent.mkdir(parents=True, exist_ok=True)
+        import shutil
+
+        shutil.move(str(legacy_path), str(new_path))
+
+
+def _provider_setup_error(config: Config) -> str | None:
+    """Return a local provider/model configuration error, or None."""
+    from nanobot.providers.factory import validate_provider_setup
+
+    try:
+        validate_provider_setup(config)
+    except ValueError as exc:
+        return str(exc)
+    return None

nanobot/cli/terminal.py

@@ -0,0 +1,428 @@
+"""Terminal input and rendering helpers for the interactive CLI."""
+
+from __future__ import annotations
+
+import os
+import select
+import sys
+from collections.abc import Callable
+from contextlib import nullcontext, suppress
+from typing import Any, Literal, cast
+
+from loguru import logger
+from prompt_toolkit import PromptSession, print_formatted_text
+from prompt_toolkit.application import run_in_terminal
+from prompt_toolkit.formatted_text import ANSI, HTML
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.key_binding.key_processor import KeyPressEvent
+from prompt_toolkit.keys import Keys
+from prompt_toolkit.patch_stdout import patch_stdout
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.text import Text
+
+from nanobot import __logo__
+from nanobot.bus.outbound_events import (
+    ProgressEvent,
+    RetryWaitEvent,
+    outbound_event_from_message,
+)
+from nanobot.cli.stream import StreamRenderer, ThinkingSpinner
+from nanobot.utils.helpers import sanitize_surrogates as _sanitize_surrogates
+
+__all__ = [
+    "_ReasoningBuffer",
+    "_ensure_interactive_tty_mode",
+    "_flush_cli_reasoning",
+    "_flush_pending_tty_input",
+    "_init_prompt_session",
+    "_is_exit_command",
+    "_maybe_print_interactive_progress",
+    "_print_agent_response",
+    "_print_cli_progress_line",
+    "_print_cli_reasoning",
+    "_print_interactive_response",
+    "_read_interactive_input_async",
+    "_restore_terminal",
+]
+
+console = Console()
+EXIT_COMMANDS = {"exit", "quit", "/exit", "/quit", ":q"}
+_REASONING_SENTENCE_ENDINGS = (".", "!", "?", "。", "！", "？")
+_REASONING_FLUSH_CHARS = 60
+_prompt_session: PromptSession[str] | None = None
+_saved_term_attrs: list[Any] | None = None
+
+
+def _ensure_interactive_tty_mode() -> None:
+    """Restore interactive line input after a raw-mode TTY leak."""
+    try:
+        fd = sys.stdin.fileno()
+        if not os.isatty(fd):
+            return
+    except Exception:
+        return
+
+    with suppress(Exception):
+        import termios
+
+        attrs = termios.tcgetattr(fd)
+        required_lflag = termios.ISIG | termios.ICANON | termios.ECHO
+        blocked_input_flags = getattr(termios, "IGNCR", 0) | getattr(termios, "INLCR", 0)
+        if (
+            (attrs[3] & required_lflag) == required_lflag
+            and attrs[0] & termios.ICRNL
+            and not attrs[0] & blocked_input_flags
+        ):
+            return
+        attrs[0] = (attrs[0] | termios.ICRNL) & ~blocked_input_flags
+        attrs[3] |= required_lflag
+        termios.tcsetattr(fd, termios.TCSANOW, attrs)
+        termios.tcflush(fd, termios.TCIFLUSH)
+        logger.debug("Restored foreground gateway TTY mode")
+
+
+class SafeFileHistory(FileHistory):
+    """FileHistory subclass that sanitizes surrogate characters on write.
+
+    On Windows, special Unicode input (emoji, mixed-script) can produce
+    surrogate characters that crash prompt_toolkit's file write.
+    See issue #2846.
+    """
+
+    def store_string(self, string: str) -> None:
+        super().store_string(_sanitize_surrogates(string))
+
+
+def _flush_pending_tty_input() -> None:
+    """Drop unread keypresses typed while the model was generating output."""
+    try:
+        fd = sys.stdin.fileno()
+        if not os.isatty(fd):
+            return
+    except Exception:
+        return
+
+    with suppress(Exception):
+        import termios
+
+        termios.tcflush(fd, termios.TCIFLUSH)
+        return
+
+    with suppress(Exception):
+        while True:
+            ready, _, _ = select.select([fd], [], [], 0)
+            if not ready:
+                break
+            if not os.read(fd, 4096):
+                break
+
+
+def _restore_terminal() -> None:
+    """Restore terminal to its original state (echo, line buffering, etc.)."""
+    if _saved_term_attrs is None:
+        return
+    with suppress(Exception):
+        import termios
+
+        termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, _saved_term_attrs)
+
+
+def _build_cli_key_bindings() -> KeyBindings:
+    """Key bindings for the interactive prompt.
+
+    Behaviour:
+      * Enter       -> submit the current input (keeps the familiar
+                       single-line Enter-to-send feel even though the buffer
+                       is multiline-capable).
+      * Alt+Enter   -> insert a newline for multi-line input.
+      * Shift+Enter -> insert a newline on terminals that emit the CSI-u
+                       (kitty / fixterms) keyboard-protocol encoding for it.
+    """
+    # prompt_toolkit does not recognize CSI-u, so register its Shift+Enter
+    # sequence as a best-effort addition without overriding existing mappings.
+    with suppress(Exception):
+        from prompt_toolkit.input import ansi_escape_sequences as _aes
+
+        _aes.ANSI_SEQUENCES.setdefault("\x1b[13;2u", Keys.ControlF3)
+
+    kb = KeyBindings()
+
+    @kb.add("enter")
+    def _(event: KeyPressEvent) -> None:
+        event.current_buffer.validate_and_handle()
+
+    @kb.add("escape", "enter")  # Alt+Enter / Meta+Enter (ESC + CR, "\x1b\r")
+    def _(event: KeyPressEvent) -> None:
+        event.current_buffer.insert_text("\n")
+
+    # LF-as-Enter terminals send Alt+Enter as ESC + LF rather than ESC + CR.
+    @kb.add("escape", Keys.ControlJ)  # Alt+Enter on LF-as-Enter terminals
+    def _(event: KeyPressEvent) -> None:
+        event.current_buffer.insert_text("\n")
+
+    @kb.add(Keys.ControlF3)  # Shift+Enter on CSI-u capable terminals
+    def _(event: KeyPressEvent) -> None:
+        event.current_buffer.insert_text("\n")
+
+    return kb
+
+
+def _init_prompt_session() -> None:
+    """Create the prompt_toolkit session with persistent file history."""
+    global _prompt_session, _saved_term_attrs
+
+    # Save terminal state so we can restore it on exit
+    with suppress(Exception):
+        import termios
+
+        _saved_term_attrs = termios.tcgetattr(sys.stdin.fileno())
+
+    from nanobot.config.paths import get_cli_history_path
+
+    history_file = get_cli_history_path()
+    history_file.parent.mkdir(parents=True, exist_ok=True)
+
+    _prompt_session = PromptSession(
+        history=SafeFileHistory(str(history_file)),
+        enable_open_in_editor=False,
+        # Multiline-capable buffer; Enter still submits via the custom key
+        # bindings, while Alt+Enter adds a newline.
+        multiline=True,
+        key_bindings=_build_cli_key_bindings(),
+    )
+
+
+def _make_console() -> Console:
+    return Console(file=sys.stdout)
+
+
+def _render_interactive_ansi(render_fn: Callable[[Console], None]) -> str:
+    """Render Rich output to ANSI so prompt_toolkit can print it safely."""
+    ansi_console = Console(
+        force_terminal=sys.stdout.isatty(),
+        color_system=cast(
+            Literal["auto", "standard", "256", "truecolor", "windows"],
+            console.color_system or "standard",
+        ),
+        width=console.width,
+    )
+    with ansi_console.capture() as capture:
+        render_fn(ansi_console)
+    return capture.get()
+
+
+def _print_agent_response(
+    response: str,
+    render_markdown: bool,
+    metadata: dict[str, Any] | None = None,
+    show_header: bool = True,
+) -> None:
+    """Render assistant response with consistent terminal styling."""
+    console = _make_console()
+    content = response or ""
+    body = _response_renderable(content, render_markdown, metadata)
+    if show_header:
+        console.print()
+        console.print(f"[cyan]{__logo__} nanobot[/cyan]")
+    console.print(body)
+    console.print()
+
+
+def _response_renderable(
+    content: str, render_markdown: bool, metadata: dict[str, Any] | None = None
+) -> Text | Markdown:
+    """Render plain-text command output without markdown collapsing newlines."""
+    if not render_markdown:
+        return Text(content)
+    if (metadata or {}).get("render_as") == "text":
+        return Text(content)
+    return Markdown(content)
+
+
+async def _print_interactive_line(text: str) -> None:
+    """Print async interactive updates with prompt_toolkit-safe Rich styling."""
+
+    def _write() -> None:
+        ansi = _render_interactive_ansi(lambda c: c.print(f"  [dim]↳ {text}[/dim]"))
+        print_formatted_text(ANSI(ansi), end="")
+
+    await run_in_terminal(_write)
+
+
+async def _print_interactive_response(
+    response: str,
+    render_markdown: bool,
+    metadata: dict[str, Any] | None = None,
+) -> None:
+    """Print async interactive replies with prompt_toolkit-safe Rich styling."""
+
+    def _write() -> None:
+        content = response or ""
+
+        def _render(target: Console) -> None:
+            target.print()
+            target.print(f"[cyan]{__logo__} nanobot[/cyan]")
+            target.print(_response_renderable(content, render_markdown, metadata))
+            target.print()
+
+        ansi = _render_interactive_ansi(_render)
+        print_formatted_text(ANSI(ansi), end="")
+
+    await run_in_terminal(_write)
+
+
+def _print_cli_progress_line(
+    text: str,
+    thinking: ThinkingSpinner | None,
+    renderer: StreamRenderer | None = None,
+) -> None:
+    """Print a CLI progress line, pausing the spinner if needed."""
+    if not text.strip():
+        return
+    target = renderer.console if renderer else console
+    pause = renderer.pause_spinner() if renderer else (thinking.pause() if thinking else nullcontext())
+    with pause:
+        if renderer:
+            renderer.ensure_header()
+        target.print(f"  [dim]↳ {text}[/dim]")
+
+
+class _ReasoningBuffer:
+    def __init__(self) -> None:
+        self._text = ""
+
+    def add(self, text: str) -> str | None:
+        if not text:
+            return None
+        self._text += text
+        if self._should_flush(text):
+            return self.flush()
+        return None
+
+    def flush(self) -> str | None:
+        text = self._text.strip()
+        self._text = ""
+        return text or None
+
+    def clear(self) -> None:
+        self._text = ""
+
+    def _should_flush(self, text: str) -> bool:
+        stripped = text.rstrip()
+        return (
+            "\n" in text
+            or stripped.endswith(_REASONING_SENTENCE_ENDINGS)
+            or len(self._text) >= _REASONING_FLUSH_CHARS
+        )
+
+
+def _print_cli_reasoning(
+    text: str,
+    thinking: ThinkingSpinner | None,
+    renderer: StreamRenderer | None = None,
+) -> None:
+    """Print reasoning/thinking content in a distinct style."""
+    if not text.strip():
+        return
+    target = renderer.console if renderer else console
+    pause = renderer.pause_spinner() if renderer else (thinking.pause() if thinking else nullcontext())
+    with pause:
+        if renderer:
+            renderer.ensure_header()
+        target.print(f"[dim italic]✻ {text}[/dim italic]")
+
+
+def _flush_cli_reasoning(
+    reasoning_buffer: _ReasoningBuffer,
+    thinking: ThinkingSpinner | None,
+    renderer: StreamRenderer | None = None,
+) -> None:
+    text = reasoning_buffer.flush()
+    if text:
+        _print_cli_reasoning(text, thinking, renderer)
+
+
+async def _print_interactive_progress_line(
+    text: str,
+    thinking: ThinkingSpinner | None,
+    renderer: StreamRenderer | None = None,
+) -> None:
+    """Print an interactive progress line, pausing the spinner if needed."""
+    if not text.strip():
+        return
+    if renderer:
+        with renderer.pause_spinner():
+            renderer.ensure_header()
+            renderer.console.print(f"  [dim]↳ {text}[/dim]")
+    else:
+        with thinking.pause() if thinking else nullcontext():
+            await _print_interactive_line(text)
+
+
+async def _maybe_print_interactive_progress(
+    msg: Any,
+    thinking: ThinkingSpinner | None,
+    channels_config: Any,
+    renderer: StreamRenderer | None = None,
+    reasoning_buffer: _ReasoningBuffer | None = None,
+) -> bool:
+    event = outbound_event_from_message(msg)
+    if isinstance(event, RetryWaitEvent):
+        await _print_interactive_progress_line(msg.content, thinking, renderer)
+        return True
+
+    if not isinstance(event, ProgressEvent):
+        return False
+
+    reasoning_buffer = reasoning_buffer or _ReasoningBuffer()
+
+    if event.reasoning_end:
+        if channels_config and not channels_config.show_reasoning:
+            reasoning_buffer.clear()
+        else:
+            _flush_cli_reasoning(reasoning_buffer, thinking, renderer)
+        return True
+
+    is_tool_hint = event.tool_hint
+    is_reasoning = event.reasoning or event.reasoning_delta
+    if is_reasoning:
+        if channels_config and not channels_config.show_reasoning:
+            reasoning_buffer.clear()
+            return True
+        text = reasoning_buffer.add(msg.content)
+        if text:
+            _print_cli_reasoning(text, thinking, renderer)
+        return True
+    if channels_config and is_tool_hint and not channels_config.send_tool_hints:
+        return True
+    if channels_config and not is_tool_hint and not channels_config.send_progress:
+        return True
+
+    await _print_interactive_progress_line(msg.content, thinking, renderer)
+    return True
+
+
+def _is_exit_command(command: str) -> bool:
+    """Return True when input should end interactive chat."""
+    return command.lower() in EXIT_COMMANDS
+
+
+async def _read_interactive_input_async() -> str:
+    """Read user input using prompt_toolkit (handles paste, history, display).
+
+    prompt_toolkit natively handles:
+    - Multiline paste (bracketed paste mode)
+    - History navigation (up/down arrows)
+    - Clean display (no ghost characters or artifacts)
+    """
+    if _prompt_session is None:
+        raise RuntimeError("Call _init_prompt_session() first")
+    try:
+        with patch_stdout():
+            return await _prompt_session.prompt_async(
+                HTML("<b fg='ansiblue'>You:</b> "),
+            )
+    except EOFError as exc:
+        raise KeyboardInterrupt from exc

nanobot/cli/webui.py

@@ -0,0 +1,261 @@
+"""WebUI CLI command."""
+
+from pathlib import Path
+
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+
+from nanobot.cli import terminal as cli_terminal
+from nanobot.cli.gateway_runtime import _run_gateway
+from nanobot.cli.runtime_config import (
+    _load_runtime_config,
+    _print_config_error,
+    _print_runtime_config_validation_error,
+    _provider_setup_error,
+)
+from nanobot.cli.webui_support import (
+    _attach_to_background_gateway,
+    _confirm_webui_action,
+    _ensure_local_webui_channel,
+    _gateway_health_bind_note,
+    _gateway_health_ready,
+    _gateway_health_url,
+    _gateway_instance_command,
+    _host_for_local_browser,
+    _load_webui_setup_config,
+    _open_webui_browser,
+    _prepare_webui_bundle_for_gateway,
+    _print_foreground_port_conflict,
+    _print_webui_foreground_lifecycle,
+    _resolve_webui_config_path,
+    _run_quick_start_for_webui,
+    _tcp_endpoint_reachable,
+    _warn_webui_bind_scope,
+    _webui_browser_url,
+    _webui_build_mode_for_interactive,
+    _webui_display_url,
+    _webui_endpoint_reachable,
+)
+from nanobot.config.paths import get_workspace_path
+from nanobot.utils.helpers import sync_workspace_templates
+
+console = Console()
+
+
+def webui(
+    port: int | None = typer.Option(None, "--port", "-p", help="WebUI port"),
+    gateway_port: int | None = typer.Option(
+        None,
+        "--gateway-port",
+        help="Gateway health port",
+    ),
+    workspace: str | None = typer.Option(None, "--workspace", "-w", help="Workspace directory"),
+    config: str | None = typer.Option(None, "--config", "-c", help="Path to config file"),
+    background: bool = typer.Option(
+        False,
+        "--background",
+        help="Keep the gateway running after this command exits",
+    ),
+    no_open: bool = typer.Option(False, "--no-open", help="Do not open a browser"),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Apply safe local WebUI defaults without prompting",
+    ),
+) -> None:
+    """Prepare the local WebUI, start the gateway, and open the browser workbench."""
+    from nanobot.config.loader import resolve_config_env_vars, save_config
+    from nanobot.gateway import GatewayRuntime, GatewayRuntimePaths, GatewayStartOptions
+
+    cli_terminal._ensure_interactive_tty_mode()
+    config_path = _resolve_webui_config_path(config)
+    created_config = not config_path.exists()
+    if created_config:
+        console.print(f"[yellow]No config found at {config_path}.[/yellow]")
+        _confirm_webui_action("Create a nanobot config and workspace now?", yes=yes)
+
+    setup_config = _load_webui_setup_config(config_path)
+    if workspace:
+        setup_config.agents.defaults.workspace = workspace
+
+    try:
+        resolved_setup_config = resolve_config_env_vars(
+            setup_config.model_copy(deep=True),
+            config_path=config_path,
+        )
+    except ValueError as exc:
+        _print_config_error(exc)
+        raise typer.Exit(1) from exc
+
+    provider_error = _provider_setup_error(resolved_setup_config)
+    settings_setup_error = provider_error if provider_error and created_config else None
+    if settings_setup_error:
+        console.print(f"[yellow]Model setup is incomplete: {provider_error}[/yellow]")
+        console.print("Configure a provider and model in WebUI Settings → Models.")
+        if background:
+            console.print(
+                "[red]First-time WebUI setup must run in the foreground. "
+                "Run `nanobot webui` without --background.[/red]"
+            )
+            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,
+            config_path=config_path,
+        )
+        if workspace:
+            setup_config.agents.defaults.workspace = workspace
+
+    try:
+        changed_webui, generated_bootstrap_secret = _ensure_local_webui_channel(
+            setup_config,
+            port=port,
+            yes=yes,
+        )
+        _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
+
+    if created_config or provider_error or changed_webui or workspace:
+        save_config(setup_config, config_path)
+        console.print(f"[green]✓[/green] Saved config: {config_path}")
+
+    workspace_path = get_workspace_path(setup_config.workspace_path)
+    workspace_path.mkdir(parents=True, exist_ok=True)
+    sync_workspace_templates(workspace_path)
+
+    runtime_config = _load_runtime_config(str(config_path), workspace)
+    effective_gateway_port = gateway_port if gateway_port is not None else runtime_config.gateway.port
+
+    console.print()
+    console.print(f"WebUI: [cyan]{_webui_display_url(webui_url)}[/cyan]")
+    gateway_health_url = _gateway_health_url(
+        runtime_config.gateway.host,
+        effective_gateway_port,
+    )
+    console.print(
+        f"Gateway health: [cyan]{gateway_health_url}[/cyan]"
+        f"{_gateway_health_bind_note(runtime_config.gateway.host)}"
+    )
+    if no_open:
+        console.print("[dim]Browser opening disabled by --no-open.[/dim]")
+        if generated_bootstrap_secret:
+            console.print(
+                "[yellow]A WebUI bootstrap secret was generated and saved in this config.[/yellow]"
+            )
+            console.print(
+                "[dim]Open the WebUI and enter channels.websocket.tokenIssueSecret from "
+                f"{config_path}, or rerun without --no-open to open the authenticated URL.[/dim]"
+            )
+
+    webui_bundle_mode = _webui_build_mode_for_interactive(yes=yes)
+
+    config_arg = str(config_path)
+    workspace_arg = str(Path(workspace).expanduser().resolve(strict=False)) if workspace else None
+    runtime = GatewayRuntime(
+        paths=GatewayRuntimePaths.for_instance(
+            data_dir=config_path.parent,
+            workspace=workspace_arg,
+            config_path=config_arg,
+        )
+    )
+    start_options = GatewayStartOptions(
+        port=effective_gateway_port,
+        workspace=workspace_arg,
+        config_path=config_arg,
+    )
+
+    if background:
+        _prepare_webui_bundle_for_gateway(runtime_config, mode=webui_bundle_mode)
+        result = runtime.start_background(start_options)
+        restarted = False
+        restart_attempted = False
+        if not result.ok and result.message == "gateway_already_running" and changed_webui:
+            restart_attempted = True
+            console.print("[yellow]WebUI config changed; restarting the background gateway.[/yellow]")
+            result = runtime.restart(start_options, timeout_s=20)
+            restarted = result.ok
+        if not result.ok and (restart_attempted or result.message != "gateway_already_running"):
+            action = "restarted" if restart_attempted else "started"
+            console.print(f"[yellow]Gateway was not {action}: {result.message}[/yellow]")
+            console.print(f"Logs: {result.status.log_path}")
+            raise typer.Exit(1)
+        if restarted:
+            console.print("[green]Gateway restarted in the background.[/green]")
+        elif result.ok:
+            console.print("[green]Gateway started in the background.[/green]")
+        else:
+            console.print("[yellow]Gateway is already running in the background.[/yellow]")
+        console.print(
+            "Manage this instance: "
+            f"[cyan]{_gateway_instance_command('status', config_path=config_path, workspace=workspace)}[/cyan]"
+        )
+        console.print(
+            "View logs: "
+            f"[cyan]{_gateway_instance_command('logs', config_path=config_path, workspace=workspace)}[/cyan]"
+        )
+        console.print("[dim]Closing the browser does not stop channels or automations.[/dim]")
+        console.print(
+            "Stop nanobot: "
+            f"[cyan]{_gateway_instance_command('stop', config_path=config_path, workspace=workspace)}[/cyan]"
+        )
+        if not no_open:
+            _open_webui_browser(webui_url)
+        return
+
+    gateway_ready = _gateway_health_ready(runtime_config.gateway.host, effective_gateway_port)
+    webui_ready = _webui_endpoint_reachable(webui_url)
+    if gateway_ready and webui_ready:
+        console.print("[yellow]Gateway is already running; attaching to the existing WebUI.[/yellow]")
+        console.print(
+            "Restart the gateway if you need it to pick up local source changes: "
+            f"[cyan]{_gateway_instance_command('restart', config_path=config_path, workspace=workspace)}[/cyan]"
+        )
+        if not no_open:
+            _open_webui_browser(webui_url, wait=False)
+        if runtime.status().running:
+            _attach_to_background_gateway(runtime)
+        else:
+            console.print(
+                "[yellow]This gateway is controlled by another foreground command. "
+                "Stop it from that terminal.[/yellow]"
+            )
+        return
+
+    gateway_port_taken = gateway_ready or _tcp_endpoint_reachable(
+        _host_for_local_browser(runtime_config.gateway.host),
+        effective_gateway_port,
+    )
+    webui_port_taken = webui_ready
+    if gateway_port_taken or webui_port_taken:
+        _print_foreground_port_conflict(
+            webui_url=webui_url,
+            gateway_host=runtime_config.gateway.host,
+            gateway_port=effective_gateway_port,
+        )
+        raise typer.Exit(1)
+
+    _print_webui_foreground_lifecycle(attached=False)
+    _run_gateway(
+        runtime_config,
+        port=effective_gateway_port,
+        open_browser_url=None if no_open else webui_url,
+        webui_bundle_mode=webui_bundle_mode,
+        unconfigured_provider_error=settings_setup_error,
+    )

nanobot/cli/webui_support.py

@@ -0,0 +1,498 @@
+"""Shared WebUI setup, URL, health, and browser helpers."""
+
+import sys
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+from rich.markup import escape
+from rich.text import Text
+
+from nanobot.cli.runtime_config import (
+    _load_config_for_cli,
+    _print_model_setup_steps,
+    _print_runtime_config_validation_error,
+    _provider_setup_error,
+)
+from nanobot.config.schema import Config
+from nanobot.security.network import is_loopback_host
+from nanobot.webui.build import (
+    BuildMode,
+    WebUIBuildError,
+    ensure_webui_bundle,
+)
+
+if TYPE_CHECKING:
+    from nanobot.gateway.runtime import GatewayRuntime
+
+__all__ = [
+    "_attach_to_background_gateway",
+    "_confirm_webui_action",
+    "_ensure_local_webui_channel",
+    "_gateway_health_bind_note",
+    "_gateway_health_ready",
+    "_gateway_health_url",
+    "_gateway_instance_command",
+    "_host_for_local_browser",
+    "_load_webui_setup_config",
+    "_open_webui_browser",
+    "_prepare_webui_bundle_for_gateway",
+    "_print_foreground_port_conflict",
+    "_print_webui_foreground_lifecycle",
+    "_resolve_webui_config_path",
+    "_run_quick_start_for_webui",
+    "_tcp_endpoint_reachable",
+    "_validate_gateway_startup",
+    "_warn_webui_bind_scope",
+    "_webui_browser_url",
+    "_webui_build_mode_for_interactive",
+    "_webui_channel_enabled",
+    "_webui_display_url",
+    "_webui_endpoint_reachable",
+]
+
+console = Console()
+
+
+def _confirm_webui_action(message: str, *, yes: bool) -> None:
+    """Confirm a WebUI first-run mutation or fail clearly in non-interactive shells."""
+    if yes:
+        return
+    if not _cli_can_prompt():
+        console.print(
+            "[red]Error: WebUI setup needs confirmation. Re-run with --yes or use "
+            "`nanobot onboard --wizard`.[/red]"
+        )
+        raise typer.Exit(1)
+    if not typer.confirm(message, default=True):
+        console.print("[yellow]WebUI setup cancelled.[/yellow]")
+        raise typer.Exit(1)
+
+
+def _cli_can_prompt() -> bool:
+    try:
+        return sys.stdin.isatty()
+    except Exception:
+        return False
+
+
+def _webui_build_mode_for_interactive(*, yes: bool = False) -> BuildMode:
+    if yes:
+        return "auto"
+    return "prompt" if _cli_can_prompt() else "warn"
+
+
+def _resolve_webui_config_path(config: str | None) -> Path:
+    """Resolve the config path used by ``nanobot webui`` and bind loader state."""
+    from nanobot.config.loader import get_config_path, set_config_path
+
+    if not config:
+        return get_config_path()
+    config_path = Path(config).expanduser().resolve(strict=False)
+    set_config_path(config_path)
+    console.print(f"[dim]Using config: {config_path}[/dim]")
+    return config_path
+
+
+def _load_webui_setup_config(config_path: Path) -> Config:
+    """Load config for first-run mutation without resolving env-var placeholders."""
+    return _load_config_for_cli(config_path)
+
+
+def _webui_config_dict(config: Config) -> dict[str, Any]:
+    """Return the current WebSocket config as a mutable alias-key dictionary."""
+    from nanobot.channels.websocket.runtime import WebSocketConfig
+
+    current: Any = getattr(config.channels, "websocket", None) or {}
+    model = WebSocketConfig.model_validate(current)
+    return model.model_dump(by_alias=True, exclude_none=True)
+
+
+def _webui_channel_enabled(config: Config) -> bool:
+    from nanobot.channels.websocket.runtime import WebSocketConfig
+
+    current: Any = getattr(config.channels, "websocket", None) or {}
+    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,
+    *,
+    mode: BuildMode,
+    webui_static_dist: bool = True,
+) -> None:
+    """Refresh or warn about stale bundled WebUI assets before gateway startup."""
+    if not webui_static_dist or not _webui_channel_enabled(config):
+        return
+
+    def _print(message: str) -> None:
+        console.print(f"[yellow]{escape(message)}[/yellow]")
+
+    def _confirm(message: str) -> bool:
+        return typer.confirm(message, default=True)
+
+    try:
+        ensure_webui_bundle(
+            mode=mode,
+            confirm=_confirm if mode == "prompt" else None,
+            output=_print,
+        )
+    except WebUIBuildError as exc:
+        if mode == "warn":
+            console.print(f"[yellow]Warning: {escape(str(exc))}[/yellow]")
+            return
+        console.print(f"[red]Error: {escape(str(exc))}[/red]")
+        raise typer.Exit(1) from exc
+
+
+def _host_for_local_browser(host: str) -> str:
+    """Map bind hosts to a browser-openable local host."""
+    if host in {"0.0.0.0", ""}:
+        return "127.0.0.1"
+    if host == "::":
+        return "[::1]"
+    if ":" in host and not host.startswith("["):
+        return f"[{host}]"
+    return host
+
+
+def _gateway_health_url(host: str, port: int) -> str:
+    """Return a health URL that can be opened from this device."""
+    return f"http://{_host_for_local_browser(host)}:{port}/health"
+
+
+def _gateway_health_bind_note(host: str) -> str:
+    """Describe a non-local bind without presenting it as a usable URL."""
+    return "" if is_loopback_host(host) else f" [dim](listening on {host})[/dim]"
+
+
+def _webui_bootstrap_secret(config: Config) -> str:
+    ws_cfg = _webui_config_dict(config)
+    return str(ws_cfg.get("tokenIssueSecret") or ws_cfg.get("token") or "").strip()
+
+
+def _webui_browser_url(config: Config) -> str:
+    from urllib.parse import quote
+
+    ws_cfg = _webui_config_dict(config)
+    host = _host_for_local_browser(str(ws_cfg.get("host") or "127.0.0.1"))
+    port = int(ws_cfg.get("port") or 8765)
+    base_url = f"http://{host}:{port}"
+    secret = _webui_bootstrap_secret(config)
+    if not secret:
+        return base_url
+    return f"{base_url}/#/?bootstrapSecret={quote(secret, safe='')}"
+
+
+def _webui_display_url(url: str) -> str:
+    marker = "bootstrapSecret="
+    if marker not in url:
+        return url
+    prefix, _ = url.split(marker, 1)
+    return f"{prefix}{marker}<redacted>"
+
+
+def _ensure_local_webui_channel(
+    config: Config,
+    *,
+    port: int | None,
+    yes: bool,
+) -> tuple[bool, bool]:
+    """Enable the local WebUI channel with safe localhost defaults."""
+    from nanobot.channels.websocket.runtime import WebSocketConfig
+
+    current: Any = getattr(config.channels, "websocket", None) or {}
+    model = WebSocketConfig.model_validate(current)
+    changed = False
+    generated_secret = False
+
+    needs_enable = not model.enabled
+    needs_port = port is not None and model.port != port
+    needs_secret = not model.token_issue_secret.strip() and not model.token.strip()
+    if not needs_enable and not needs_port and not needs_secret:
+        return False, False
+
+    target_port = port if port is not None else model.port
+    console.print()
+    console.print("[bold]Local WebUI setup[/bold]")
+    console.print(f"  URL: [cyan]http://127.0.0.1:{target_port}[/cyan]")
+    console.print("  Bind: [cyan]127.0.0.1 only[/cyan] (not exposed to your LAN)")
+    console.print("  Auth: generated WebUI bootstrap secret stored in config")
+    console.print(
+        "  LAN access requires an explicit host change plus a WebUI password in config."
+    )
+    _confirm_webui_action("Update the local WebUI channel in this config?", yes=yes)
+
+    if not model.enabled:
+        model.enabled = True
+        changed = True
+    if model.host != "127.0.0.1":
+        model.host = "127.0.0.1"
+        changed = True
+    if port is not None and model.port != port:
+        model.port = port
+        changed = True
+    if not model.websocket_requires_token:
+        model.websocket_requires_token = True
+        changed = True
+    if needs_secret:
+        import secrets
+
+        model.token_issue_secret = secrets.token_urlsafe(32)
+        changed = True
+        generated_secret = True
+
+    setattr(config.channels, "websocket", model.model_dump(by_alias=True, exclude_none=True))
+    return changed, generated_secret
+
+
+def _warn_webui_bind_scope(config: Config) -> None:
+    ws_cfg = _webui_config_dict(config)
+    host = str(ws_cfg.get("host") or "127.0.0.1")
+    if host in {"127.0.0.1", "localhost", "::1"}:
+        return
+    console.print(
+        "[yellow]Warning: WebUI is configured to bind outside localhost. "
+        "Keep tokenIssueSecret set and use this only on trusted networks.[/yellow]"
+    )
+
+
+def _wait_for_webui(url: str, *, timeout_s: float = 5.0) -> None:
+    """Best-effort wait for the WebUI listener before opening a browser."""
+    import time
+    from urllib.parse import urlparse
+
+    parsed = urlparse(url)
+    host = parsed.hostname or "127.0.0.1"
+    port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    deadline = time.monotonic() + timeout_s
+    while time.monotonic() < deadline:
+        if _tcp_endpoint_reachable(host, port, timeout_s=0.2):
+            return
+        time.sleep(0.1)
+
+
+def _tcp_endpoint_reachable(host: str, port: int, *, timeout_s: float = 0.25) -> bool:
+    """Return whether a local TCP endpoint accepts connections."""
+    import socket
+
+    try:
+        with socket.create_connection((host, port), timeout=timeout_s):
+            return True
+    except OSError:
+        return False
+
+
+def _gateway_health_ready(host: str, port: int, *, timeout_s: float = 0.4) -> bool:
+    """Return whether the nanobot gateway health endpoint responds OK."""
+    import json
+    import urllib.error
+    import urllib.request
+
+    browser_host = _host_for_local_browser(host)
+    try:
+        with urllib.request.urlopen(
+            f"http://{browser_host}:{port}/health",
+            timeout=timeout_s,
+        ) as response:
+            if response.status != 200:
+                return False
+            body = response.read(1024)
+    except (OSError, urllib.error.URLError, TimeoutError, ValueError):
+        return False
+
+    try:
+        payload = json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return False
+    return payload.get("status") == "ok"
+
+
+def _webui_endpoint_reachable(url: str, *, timeout_s: float = 0.25) -> bool:
+    """Return whether the WebUI URL's TCP endpoint is already listening."""
+    from urllib.parse import urlparse
+
+    parsed = urlparse(url)
+    host = parsed.hostname or "127.0.0.1"
+    port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    return _tcp_endpoint_reachable(host, port, timeout_s=timeout_s)
+
+
+def _print_foreground_port_conflict(
+    *,
+    webui_url: str,
+    gateway_host: str,
+    gateway_port: int,
+) -> None:
+    console.print(
+        "[red]Error: nanobot cannot start because one of its local ports is already in use.[/red]"
+    )
+    console.print(f"  WebUI: [cyan]{webui_url}[/cyan]")
+    console.print(
+        f"  Gateway health: "
+        f"[cyan]http://{_host_for_local_browser(gateway_host)}:{gateway_port}/health[/cyan]"
+    )
+    console.print()
+    console.print("If this is an existing nanobot instance, use it or stop it first:")
+    console.print("  [cyan]nanobot gateway status[/cyan]")
+    console.print("  [cyan]nanobot gateway stop[/cyan]")
+    console.print(
+        "Or choose different ports with [cyan]--port[/cyan] "
+        "and [cyan]--gateway-port[/cyan]."
+    )
+
+
+def _open_webui_browser(url: str, *, wait: bool = True) -> None:
+    """Open the WebUI in the user's default browser, with a copyable fallback."""
+    import webbrowser
+
+    if wait:
+        _wait_for_webui(url)
+    display_url = _webui_display_url(url)
+    try:
+        webbrowser.open(url)
+        console.print(f"[green]✓[/green] Opened WebUI: [cyan]{display_url}[/cyan]")
+    except Exception as exc:
+        console.print(f"[yellow]Could not open browser ({exc}); visit {display_url}[/yellow]")
+
+
+def _print_webui_foreground_lifecycle(*, attached: bool) -> None:
+    """Explain how the browser and gateway lifecycles differ."""
+    console.print()
+    if attached:
+        console.print("[green]nanobot is attached to the existing gateway.[/green]")
+    else:
+        console.print("[green]nanobot is running in this terminal.[/green]")
+    console.print("[dim]Closing the browser does not stop channels or automations.[/dim]")
+    console.print("[dim]Press Ctrl+C here to stop nanobot.[/dim]")
+
+
+def _attach_to_background_gateway(runtime: "GatewayRuntime") -> None:
+    """Keep a foreground WebUI command attached to a managed gateway."""
+    _print_webui_foreground_lifecycle(attached=True)
+    try:
+        while runtime.status().running:
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Stopping nanobot...[/yellow]")
+        result = runtime.stop()
+        if result.ok or result.message == "gateway_not_running":
+            console.print("[green]Gateway stopped.[/green]")
+            return
+        console.print(f"[red]Gateway could not be stopped: {result.message}[/red]")
+        raise typer.Exit(1)
+
+    console.print("[yellow]Gateway stopped.[/yellow]")
+
+
+def _gateway_instance_command(
+    subcommand: str,
+    *,
+    config_path: Path,
+    workspace: str | None,
+) -> str:
+    """Return a copyable gateway command for the same config/workspace instance."""
+    import shlex
+
+    parts = ["nanobot", "gateway", subcommand, "--config", str(config_path)]
+    if workspace:
+        workspace_path = str(Path(workspace).expanduser().resolve(strict=False))
+        parts.extend(["--workspace", workspace_path])
+    return " ".join(shlex.quote(part) for part in parts)
+
+
+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.[/red]"
+        )
+        console.print("Complete provider/model setup:")
+        _print_model_setup_steps(config_path)
+        raise typer.Exit(1)
+
+    console.print()
+    console.print("[yellow]Model provider setup is not ready.[/yellow]")
+    console.print(
+        "Quick Start will ask for provider, API key/base URL, model, and WebUI password."
+    )
+    _confirm_webui_action("Run Quick Start now?", yes=False)
+
+    from nanobot.cli.onboard import run_quick_start_onboard
+
+    try:
+        result = run_quick_start_onboard(config)
+    except RuntimeError as exc:
+        console.print(f"[red]Error: {exc}[/red]")
+        console.print(
+            "[yellow]Run `nanobot onboard --wizard` "
+            "after installing wizard dependencies.[/yellow]"
+        )
+        raise typer.Exit(1) from exc
+    if not result.should_save:
+        console.print("[yellow]Quick Start cancelled. No changes were saved.[/yellow]")
+        raise typer.Exit(1)
+    return result.config

nanobot/command/builtin.py

@@ -311,7 +311,7 @@ async def cmd_new(ctx: CommandContext) -> OutboundMessage:
     loop.sessions.save(session)
     loop.sessions.invalidate(session.key)
     if snapshot and runtime is not None:
-        loop._schedule_background(  # pyright: ignore[reportPrivateUsage]
+        loop.schedule_background(
             loop.consolidator.archive(  # pyright: ignore[reportUnknownMemberType]
                 snapshot,
                 runtime=runtime,

nanobot/nanobot.py

@@ -5,9 +5,7 @@ from __future__ import annotations
 import asyncio
 from collections.abc import AsyncIterator, Mapping
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-from loguru import logger
+from typing import Any
 
 from nanobot.agent.hook import AgentHook, SDKCaptureHook
 from nanobot.agent.hooks import create_file_edit_activity_hook
@@ -41,9 +39,6 @@ from nanobot.sdk.types import (
 )
 from nanobot.utils.llm_runtime import LLMRuntime
 
-if TYPE_CHECKING:
-    from nanobot.resource_links import ResourceView
-
 __all__ = [
     "Nanobot",
     "RunResult",
@@ -66,28 +61,6 @@ __all__ = [
 ]
 
 
-def _prepare_resource_view(config: Config, config_path: Path) -> ResourceView | None:
-    """Best-effort resource aliases scoped to this SDK instance's config."""
-    from nanobot.resource_links import ensure_resource_view
-
-    try:
-        # CLI entry points synchronize workspace templates before this step.
-        # The SDK has no equivalent bootstrap phase, so ensure the link target
-        # exists before preparing its alias.
-        config.workspace_path.mkdir(parents=True, exist_ok=True)
-        view = ensure_resource_view(
-            data_dir=config_path.parent,
-            config_path=config_path,
-            agent_workspace=config.workspace_path,
-        )
-    except Exception as exc:
-        logger.warning("Could not prepare the nanobot resource view: {}", exc)
-        return None
-    for warning in view.warnings:
-        logger.warning("Resource view: {}", warning)
-    return view
-
-
 class Nanobot:
     """Programmatic facade for running the nanobot agent.
 
@@ -123,7 +96,7 @@ class Nanobot:
             model: Override the instance default model.
             model_preset: Override the instance default model preset.
         """
-        from nanobot.config.loader import get_config_path, load_config, resolve_config_env_vars
+        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
@@ -132,14 +105,9 @@ class Nanobot:
             if not resolved.exists():
                 raise FileNotFoundError(f"Config not found: {resolved}")
 
-        effective_config_path = (
-            resolved
-            if resolved is not None
-            else get_config_path().expanduser().resolve(strict=False)
-        )
         config: Config = resolve_config_env_vars(
             load_config(resolved),
-            config_path=effective_config_path,
+            config_path=resolved,
         )
         if workspace is not None:
             config.agents.defaults.workspace = str(
@@ -152,12 +120,10 @@ class Nanobot:
         elif model_preset is not None:
             config.agents.defaults.model_preset = model_preset
 
-        resource_view = _prepare_resource_view(config, effective_config_path)
         loop = AgentLoop.from_config(
             config,
             image_generation_provider_configs=image_gen_provider_configs(config),
             hook_factories=[create_file_edit_activity_hook],
-            resource_view=resource_view,
         )
         return cls(loop, config=config)
 

nanobot/pairing/store.py

@@ -40,9 +40,15 @@ def _load() -> dict[str, Any]:
             data = json.load(f)
     except FileNotFoundError:
         return {"approved": {}, "pending": {}}
-    except (json.JSONDecodeError, OSError):
+    except json.JSONDecodeError:
         logger.warning("Corrupted pairing store, resetting")
         return {"approved": {}, "pending": {}}
+    except OSError:
+        # A transiently locked or busy file is not corruption. Propagate so
+        # mutating callers fail loudly instead of persisting an empty view
+        # that would erase every approved sender.
+        logger.warning("Pairing store temporarily unreadable: {}", path)
+        raise
     if not isinstance(data, dict):
         logger.warning("Corrupted pairing store, resetting")
         return {"approved": {}, "pending": {}}
@@ -171,7 +177,11 @@ def deny_code(code: str) -> bool:
 def is_approved(channel: str, sender_id: str) -> bool:
     """Check whether *sender_id* has been approved on *channel*."""
     with _LOCK:
-        data = _load()
+        try:
+            data = _load()
+        except OSError:
+            # Fail closed for this check; the store itself stays untouched.
+            return False
         approved: dict[str, set[str]] = data.get("approved", {})
         return str(sender_id) in approved.get(channel, set())
 
@@ -179,7 +189,10 @@ def is_approved(channel: str, sender_id: str) -> bool:
 def list_pending() -> list[dict[str, Any]]:
     """Return all non-expired pending pairing requests."""
     with _LOCK:
-        data = _load()
+        try:
+            data = _load()
+        except OSError:
+            return []
         _gc_pending(data)
         return [
             {"code": code, **info}
@@ -257,7 +270,10 @@ def clear_channel(channel: str) -> dict[str, int]:
 def get_approved(channel: str) -> list[str]:
     """Return all approved sender IDs for *channel*."""
     with _LOCK:
-        data = _load()
+        try:
+            data = _load()
+        except OSError:
+            return []
         return sorted(data.get("approved", {}).get(channel, set()))
 
 
@@ -283,6 +299,15 @@ def handle_pairing_command(channel: str, subcommand_text: str) -> str:
     This is a pure function (no side effects other than store mutations)
     so it can be used from both the CLI and the agent CommandRouter.
     """
+    try:
+        return _handle_pairing_subcommand(channel, subcommand_text)
+    except OSError:
+        # Mutations fail loudly on a transient I/O error instead of lying
+        # ("invalid code") or silently rewriting the store from an empty view.
+        return "The pairing store is temporarily unavailable. Please try again."
+
+
+def _handle_pairing_subcommand(channel: str, subcommand_text: str) -> str:
     parts = subcommand_text.split()
     sub = parts[0] if parts else "list"
     arg = parts[1] if len(parts) > 1 else None

nanobot/providers/azure_openai_provider.py

@@ -23,14 +23,26 @@ import uuid
 from collections.abc import Awaitable, Callable
 from typing import Any, cast
 
+from loguru import logger
 from openai import AsyncOpenAI
 
-from nanobot.providers.base import LLMProvider, LLMResponse
+from nanobot.providers.base import (
+    LLMProvider,
+    LLMResponse,
+    ProviderCallContext,
+    ProviderConversationState,
+)
 from nanobot.providers.openai_responses import (
+    ResponsesStreamCapture,
+    build_responses_state,
     consume_sdk_stream,
-    convert_messages,
     convert_tools,
+    is_compaction_compatibility_error,
+    is_replayable_finish_reason,
     parse_response_output,
+    prepare_responses_input,
+    resolve_compact_threshold,
+    responses_state_matches,
 )
 
 _AZURE_OPENAI_SCOPE = "https://cognitiveservices.azure.com/.default"
@@ -97,6 +109,7 @@ class AzureOpenAIProvider(LLMProvider):
     ):
         super().__init__(api_key, api_base)
         self.default_model = default_model
+        self._native_compaction_available = True
 
         if not api_base:
             raise ValueError("Azure OpenAI api_base is required")
@@ -142,6 +155,25 @@ class AzureOpenAIProvider(LLMProvider):
         name = deployment_name.lower()
         return not any(token in name for token in ("gpt-5", "o1", "o3", "o4"))
 
+    def _responses_state_provider(self) -> str:
+        return f"azure_openai:{str(self.api_base).rstrip('/')}"
+
+    def can_resume_conversation_state(
+        self,
+        state: ProviderConversationState,
+        model: str | None = None,
+    ) -> bool:
+        return responses_state_matches(
+            state,
+            provider=self._responses_state_provider(),
+            model=model or self.default_model,
+        )
+
+    def supports_native_compaction(self, model: str | None = None) -> bool:
+        """Azure's native Responses endpoint accepts context management."""
+        _ = model
+        return self._native_compaction_available
+
     def _build_body(
         self,
         messages: list[dict[str, Any]],
@@ -151,10 +183,26 @@ class AzureOpenAIProvider(LLMProvider):
         temperature: float,
         reasoning_effort: str | None,
         tool_choice: str | dict[str, Any] | None,
+        provider_context: ProviderCallContext | None = None,
     ) -> dict[str, Any]:
         """Build the Responses API request body from Chat-Completions-style args."""
         deployment = model or self.default_model
-        instructions, input_items = convert_messages(self._sanitize_empty_content(messages))
+        sanitized_messages = self._sanitize_empty_content(messages)
+        sanitized_state = (
+            provider_context.conversation_state
+            if provider_context is not None
+            else None
+        )
+        if sanitized_state is not None:
+            sanitized_state = sanitized_state.with_pending_messages(
+                self._sanitize_empty_content(sanitized_state.pending_messages)
+            )
+        instructions, input_items, replayed = prepare_responses_input(
+            sanitized_messages,
+            state=sanitized_state,
+            provider=self._responses_state_provider(),
+            model=deployment,
+        )
 
         body: dict[str, Any] = {
             "model": deployment,
@@ -164,13 +212,29 @@ class AzureOpenAIProvider(LLMProvider):
             "store": False,
             "stream": False,
         }
+        compact_threshold = resolve_compact_threshold(
+            (
+                provider_context.context_window_tokens
+                if provider_context is not None
+                else None
+            ),
+            max_tokens,
+        )
+        if self.supports_native_compaction(deployment) and compact_threshold is not None:
+            body["context_management"] = [{
+                "type": "compaction",
+                "compact_threshold": compact_threshold,
+            }]
 
         if self._supports_temperature(deployment, reasoning_effort):
             body["temperature"] = temperature
 
+        if not self._supports_temperature(deployment, reasoning_effort):
+            body["include"] = ["reasoning.encrypted_content"]
         if reasoning_effort and reasoning_effort.lower() != "none":
             body["reasoning"] = {"effort": reasoning_effort}
-            body["include"] = ["reasoning.encrypted_content"]
+        if replayed and "gpt-5.6" in deployment.lower():
+            body.setdefault("reasoning", {})["context"] = "all_turns"
 
         if tools:
             body["tools"] = convert_tools(tools)
@@ -178,21 +242,97 @@ class AzureOpenAIProvider(LLMProvider):
 
         return body
 
+    async def _create_response_with_compaction_fallback(
+        self,
+        body: dict[str, Any],
+    ) -> Any:
+        """Retry once without server compaction when Azure rejects the option."""
+        try:
+            return cast(Any, await self._client.responses.create(**body))
+        except Exception as exc:
+            if (
+                "context_management" not in body
+                or not is_compaction_compatibility_error(exc)
+            ):
+                raise
+            self._native_compaction_available = False
+            body.pop("context_management", None)
+            logger.warning(
+                "Azure Responses server compaction unsupported; disabled for this provider "
+                "instance (status={})",
+                getattr(exc, "status_code", None),
+            )
+            return cast(Any, await self._client.responses.create(**body))
+
     @staticmethod
     def _handle_error(e: Exception) -> LLMResponse:
         response = getattr(e, "response", None)
         body = getattr(e, "body", None) or getattr(response, "text", None)
         body_text = str(body).strip() if body is not None else ""
         msg = f"Error: {body_text[:500]}" if body_text else f"Error calling Azure OpenAI: {e}"
-        retry_after = LLMProvider._extract_retry_after_from_headers(getattr(response, "headers", None))
+        headers = getattr(response, "headers", None)
+        retry_after = LLMProvider._extract_retry_after_from_headers(headers)
         if retry_after is None:
             retry_after = LLMProvider._extract_retry_after(msg)
-        return LLMResponse(content=msg, finish_reason="error", retry_after=retry_after)
+        status_code = getattr(e, "status_code", None)
+        if status_code is None and response is not None:
+            status_code = getattr(response, "status_code", None)
+        error_type, error_code = LLMProvider._extract_error_type_code(body)
+        should_retry: bool | None = None
+        if headers is not None:
+            raw_should_retry = headers.get("x-should-retry")
+            if isinstance(raw_should_retry, str):
+                lowered = raw_should_retry.strip().lower()
+                if lowered == "true":
+                    should_retry = True
+                elif lowered == "false":
+                    should_retry = False
+        error_name = type(e).__name__.lower()
+        error_kind = (
+            "timeout"
+            if "timeout" in error_name
+            else "connection"
+            if "connection" in error_name
+            else None
+        )
+        return LLMResponse(
+            content=msg,
+            finish_reason="error",
+            retry_after=retry_after,
+            error_status_code=int(status_code) if status_code is not None else None,
+            error_kind=error_kind,
+            error_type=error_type,
+            error_code=error_code,
+            error_retry_after_s=retry_after,
+            error_should_retry=should_retry,
+        )
 
     # ------------------------------------------------------------------
     # Public API
     # ------------------------------------------------------------------
 
+    async def chat_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        return await self.chat(
+            **kwargs,
+            provider_context=provider_context,
+        )
+
+    async def chat_stream_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        return await self.chat_stream(
+            **kwargs,
+            provider_context=provider_context,
+        )
+
     async def chat(
         self,
         messages: list[dict[str, Any]],
@@ -202,14 +342,21 @@ class AzureOpenAIProvider(LLMProvider):
         temperature: float = 0.7,
         reasoning_effort: str | None = None,
         tool_choice: str | dict[str, Any] | None = None,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         body = self._build_body(
             messages, tools, model, max_tokens, temperature,
             reasoning_effort, tool_choice,
+            provider_context,
         )
         try:
-            response = cast(Any, await self._client.responses.create(**body))
-            return parse_response_output(response)
+            response = await self._create_response_with_compaction_fallback(body)
+            return parse_response_output(
+                response,
+                state_provider=self._responses_state_provider(),
+                state_model=str(body["model"]),
+                state_input_items=cast(list[dict[str, Any]], body["input"]),
+            )
         except Exception as e:
             return self._handle_error(e)
 
@@ -225,26 +372,43 @@ class AzureOpenAIProvider(LLMProvider):
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
         on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         _ = on_thinking_delta
         body = self._build_body(
             messages, tools, model, max_tokens, temperature,
             reasoning_effort, tool_choice,
+            provider_context,
         )
         body["stream"] = True
 
         try:
-            stream = cast(Any, await self._client.responses.create(**body))
+            stream = await self._create_response_with_compaction_fallback(body)
+            capture = ResponsesStreamCapture()
             content, tool_calls, finish_reason, usage, reasoning_content = (
-                await consume_sdk_stream(stream, on_content_delta, on_tool_call_delta)
+                await consume_sdk_stream(
+                    stream,
+                    on_content_delta,
+                    on_tool_call_delta,
+                    capture=capture,
+                )
             )
-            return LLMResponse(
+            result = LLMResponse(
                 content=content or None,
                 tool_calls=tool_calls,
                 finish_reason=finish_reason,
                 usage=usage,
                 reasoning_content=reasoning_content,
             )
+            if capture.completed and is_replayable_finish_reason(finish_reason):
+                result.provider_state = build_responses_state(
+                    provider=self._responses_state_provider(),
+                    model=str(body["model"]),
+                    input_items=cast(list[dict[str, Any]], body["input"]),
+                    output_items=capture.output_items,
+                    usage=usage,
+                )
+            return result
         except Exception as e:
             return self._handle_error(e)
 

nanobot/providers/base.py

@@ -1,5 +1,7 @@
 """Base LLM provider interface."""
 
+from __future__ import annotations
+
 import asyncio
 import json
 import os
@@ -7,6 +9,7 @@ import re
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable
 from contextlib import suppress
+from copy import deepcopy
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from email.utils import parsedate_to_datetime
@@ -150,6 +153,104 @@ def tool_arguments_json_for_replay(arguments: Any) -> str:
     return json.dumps(tool_arguments_object_for_replay(arguments), ensure_ascii=False)
 
 
+@dataclass
+class ProviderConversationState:
+    """Opaque provider-owned continuation state.
+
+    ``payload`` may contain encrypted reasoning or other provider-private
+    protocol items. Keep it out of normal logs and public chat history.
+    ``pending_messages`` are Chat-style messages produced after the most
+    recent provider response and are materialized by the owning provider on
+    the next request.
+    """
+
+    kind: str
+    provider: str
+    model: str
+    version: int
+    payload: dict[str, Any] = field(default_factory=dict, repr=False)
+    pending_messages: list[dict[str, Any]] = field(default_factory=list, repr=False)
+
+    def with_pending_messages(
+        self,
+        messages: list[dict[str, Any]],
+    ) -> ProviderConversationState:
+        """Return a state copy with an isolated pending-message list."""
+        return ProviderConversationState(
+            kind=self.kind,
+            provider=self.provider,
+            model=self.model,
+            version=self.version,
+            payload=self.payload,
+            pending_messages=deepcopy(messages),
+        )
+
+    def to_private_record(self) -> dict[str, Any]:
+        """Serialize for the private session sidecar, never for public history."""
+        return {
+            "kind": self.kind,
+            "provider": self.provider,
+            "model": self.model,
+            "version": self.version,
+            "payload": deepcopy(self.payload),
+            "pending_messages": deepcopy(self.pending_messages),
+        }
+
+    @classmethod
+    def from_private_record(
+        cls,
+        value: object,
+    ) -> ProviderConversationState | None:
+        """Validate and deserialize a private session-sidecar value."""
+        if not isinstance(value, dict):
+            return None
+        data = cast(dict[str, Any], value)
+        kind = data.get("kind")
+        provider = data.get("provider")
+        model = data.get("model")
+        version = data.get("version")
+        payload = data.get("payload")
+        pending = data.get("pending_messages", [])
+        if (
+            not isinstance(kind, str)
+            or not kind
+            or not isinstance(provider, str)
+            or not provider
+            or not isinstance(model, str)
+            or not model
+            or isinstance(version, bool)
+            or not isinstance(version, int)
+            or not isinstance(payload, dict)
+            or not isinstance(pending, list)
+            or any(
+                not isinstance(message, dict)
+                for message in cast(list[object], pending)
+            )
+        ):
+            return None
+        return cls(
+            kind=kind,
+            provider=provider,
+            model=model,
+            version=version,
+            payload=deepcopy(cast(dict[str, Any], payload)),
+            pending_messages=deepcopy(cast(list[dict[str, Any]], pending)),
+        )
+
+
+@dataclass(frozen=True)
+class ProviderCallContext:
+    """Optional provider-owned continuation data for one model request.
+
+    The regular ``chat`` contract stays provider-agnostic. Responses-capable
+    providers consume this context through the opt-in ``chat_with_context``
+    hooks, while every other provider inherits the context-free delegation.
+    """
+
+    conversation_state: ProviderConversationState | None = field(default=None, repr=False)
+    context_window_tokens: int | None = None
+
+
 @dataclass
 class LLMResponse:
     """Response from an LLM provider."""
@@ -160,6 +261,10 @@ class LLMResponse:
     retry_after: float | None = None  # Provider supplied retry wait in seconds.
     reasoning_content: str | None = None  # Kimi, DeepSeek-R1, MiMo etc.
     thinking_blocks: list[dict[str, Any]] | None = None  # Anthropic extended thinking
+    provider_state: ProviderConversationState | None = field(default=None, repr=False)
+    # Routing wrappers may preserve or discard an incoming provider-owned
+    # continuation independently of the final fallback error's retry policy.
+    preserve_provider_state_on_error: bool | None = field(default=None, repr=False)
     # Structured error metadata used by retry policy when finish_reason == "error".
     error_status_code: int | None = None
     error_kind: str | None = None  # e.g. "timeout", "connection"
@@ -274,6 +379,18 @@ class LLMProvider(ABC):
         self.api_base = api_base
         self.generation: GenerationSettings = GenerationSettings()
 
+    def can_resume_conversation_state(
+        self,
+        state: ProviderConversationState,
+        model: str | None = None,
+    ) -> bool:
+        """Whether this provider can safely consume an opaque saved state."""
+        return False
+
+    def supports_native_compaction(self, model: str | None = None) -> bool:
+        """Whether requests may include provider-native context compaction."""
+        return False
+
     @staticmethod
     def _sanitize_empty_content(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
         """Sanitize message content: fix empty blocks, strip internal _meta fields.
@@ -416,7 +533,7 @@ class LLMProvider(ABC):
         return any(marker in err for marker in cls._TRANSIENT_ERROR_MARKERS)
 
     @classmethod
-    def _is_transient_response(cls, response: LLMResponse) -> bool:
+    def is_transient_response(cls, response: LLMResponse) -> bool:
         """Prefer structured error metadata, fallback to text markers for legacy providers."""
         if response.error_should_retry is not None:
             return bool(response.error_should_retry)
@@ -607,6 +724,21 @@ class LLMProvider(ABC):
                 result.append(msg)
         return result if found else None
 
+    @staticmethod
+    def _contains_image_content(value: object) -> bool:
+        """Return whether a JSON-like provider payload contains an input image."""
+        if isinstance(value, dict):
+            mapping = cast(dict[str, object], value)
+            if mapping.get("type") in {"image_url", "input_image"}:
+                return True
+            return any(LLMProvider._contains_image_content(item) for item in mapping.values())
+        if isinstance(value, list):
+            return any(
+                LLMProvider._contains_image_content(item)
+                for item in cast(list[object], value)
+            )
+        return False
+
     @staticmethod
     def _strip_image_content_inplace(messages: list[dict[str, Any]]) -> bool:
         """Replace image_url blocks with text placeholder *in-place*.
@@ -633,6 +765,12 @@ class LLMProvider(ABC):
     async def _safe_chat(self, **kwargs: Any) -> LLMResponse:
         """Call chat() and convert unexpected exceptions to error responses."""
         try:
+            provider_context = kwargs.pop("provider_context", None)
+            if isinstance(provider_context, ProviderCallContext):
+                return await self.chat_with_context(
+                    provider_context=provider_context,
+                    **kwargs,
+                )
             return await self.chat(**kwargs)
         except asyncio.CancelledError:
             raise
@@ -666,17 +804,47 @@ class LLMProvider(ABC):
         """
         _ = on_thinking_delta, on_tool_call_delta
         response = await self.chat(
-            messages=messages, tools=tools, model=model,
-            max_tokens=max_tokens, temperature=temperature,
-            reasoning_effort=reasoning_effort, tool_choice=tool_choice,
+            messages=messages,
+            tools=tools,
+            model=model,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            reasoning_effort=reasoning_effort,
+            tool_choice=tool_choice,
         )
         if on_content_delta and response.content:
             await on_content_delta(response.content)
         return response
 
+    async def chat_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        """Opt-in continuation hook; ordinary providers delegate to ``chat``."""
+        _ = provider_context
+        return await self.chat(**kwargs)
+
+    async def chat_stream_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        """Streaming continuation hook with a context-free default."""
+        _ = provider_context
+        return await self.chat_stream(**kwargs)
+
     async def _safe_chat_stream(self, **kwargs: Any) -> LLMResponse:
         """Call chat_stream() and convert unexpected exceptions to error responses."""
         try:
+            provider_context = kwargs.pop("provider_context", None)
+            if isinstance(provider_context, ProviderCallContext):
+                return await self.chat_stream_with_context(
+                    provider_context=provider_context,
+                    **kwargs,
+                )
             return await self.chat_stream(**kwargs)
         except asyncio.CancelledError:
             raise
@@ -698,6 +866,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,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         """Call chat_stream() with retry on transient provider failures."""
         if max_tokens is self._SENTINEL or max_tokens is None:
@@ -730,6 +899,8 @@ class LLMProvider(ABC):
             on_thinking_delta=on_thinking_delta,
             on_tool_call_delta=on_tool_call_delta,
         )
+        if provider_context is not None:
+            kw["provider_context"] = provider_context
         if on_stream_recover and getattr(self, "supports_stream_recover_callback", False):
             kw["on_stream_recover"] = _recover_stream
         return await self._run_with_retry(
@@ -753,6 +924,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,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         """Call chat() with retry on transient provider failures.
 
@@ -775,6 +947,8 @@ class LLMProvider(ABC):
             max_tokens=max_tokens, temperature=temperature,
             reasoning_effort=reasoning_effort, tool_choice=tool_choice,
         )
+        if provider_context is not None:
+            kw["provider_context"] = provider_context
         return await self._run_with_retry(
             self._safe_chat,
             kw,
@@ -932,14 +1106,33 @@ class LLMProvider(ABC):
                 last_error_key = error_key
                 identical_error_count = 1 if error_key else 0
 
-            if not self._is_transient_response(response):
-                stripped = self._strip_image_content(original_messages)
-                if stripped is not None and stripped != kw["messages"]:
+            if not self.is_transient_response(response):
+                stripped = self._strip_image_content(kw["messages"])
+                provider_context = kw.get("provider_context")
+                stripped_context: ProviderCallContext | None = None
+                if isinstance(provider_context, ProviderCallContext):
+                    state = provider_context.conversation_state
+                    if state is not None and (
+                        stripped is not None
+                        or self._strip_image_content(state.pending_messages) is not None
+                        or self._contains_image_content(state.payload)
+                    ):
+                        # Provider-owned payloads may retain earlier input_image items.
+                        # Rebuild from the stripped public transcript for this retry.
+                        stripped_context = ProviderCallContext(
+                            context_window_tokens=(
+                                provider_context.context_window_tokens
+                            ),
+                        )
+                if stripped is not None or stripped_context is not None:
                     logger.warning(
                         "Non-transient LLM error with image content, retrying without images"
                     )
                     retry_kw = dict(kw)
-                    retry_kw["messages"] = stripped
+                    if stripped is not None:
+                        retry_kw["messages"] = stripped
+                    if stripped_context is not None:
+                        retry_kw["provider_context"] = stripped_context
                     result = await call(**retry_kw)
                     # Permanently strip images from the original messages so
                     # subsequent iterations do not repeat the error-retry cycle.

nanobot/providers/conversation_state.py

@@ -0,0 +1,262 @@
+"""Provider-owned conversation-state lifecycle coordination."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, cast
+
+from nanobot.providers.base import (
+    LLMProvider,
+    LLMResponse,
+    ProviderCallContext,
+    ProviderConversationState,
+)
+
+_PROVIDER_STATE_OUTPUT_META = "provider_state_output"
+_PROVIDER_STATE_BOUNDARY_META = "provider_state_boundary"
+
+
+def allows_conversation_message_merge(message: dict[str, Any]) -> bool:
+    """Return whether new same-role input may merge into *message*."""
+    internal_meta = cast(object, message.get("_meta"))
+    return not (
+        isinstance(internal_meta, dict)
+        and cast(dict[str, Any], internal_meta).get(
+            _PROVIDER_STATE_BOUNDARY_META
+        ) is True
+    )
+
+
+class ProviderConversationStateController:
+    """Keep provider conversation-state semantics outside the agent runner.
+
+    The runner owns the tool loop and reports lifecycle events here. This
+    controller owns capability checks, transcript deltas, response projections,
+    retry transitions, and durable snapshots for provider-private state.
+    """
+
+    def __init__(
+        self,
+        *,
+        provider: LLMProvider,
+        model: str | None,
+        messages: list[dict[str, Any]],
+        state: ProviderConversationState | None = None,
+    ) -> None:
+        self._provider = provider
+        self._model = model
+        self._state = (
+            state
+            if state is not None
+            and provider.can_resume_conversation_state(state, model)
+            else None
+        )
+        self._boundary = len(messages)
+        self._request_messages: list[dict[str, Any]] = []
+
+    def independent_request_context(
+        self,
+        *,
+        context_window_tokens: int | None,
+    ) -> ProviderCallContext | None:
+        """Return typed provider context for a request that does not resume state."""
+        if context_window_tokens is None:
+            return None
+        return ProviderCallContext(context_window_tokens=context_window_tokens)
+
+    def prepare_request(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        context_window_tokens: int | None,
+        model_messages: list[dict[str, Any]] | None = None,
+        supplemental_messages: list[dict[str, Any]] | None = None,
+    ) -> ProviderCallContext | None:
+        """Build typed context for the next request and remember its durable delta."""
+        independent_context = self.independent_request_context(
+            context_window_tokens=context_window_tokens,
+        )
+        if self._state is None:
+            self._request_messages = []
+            return independent_context
+        if not self._provider.can_resume_conversation_state(
+            self._state,
+            self._model,
+        ):
+            self._state = None
+            self._request_messages = []
+            return independent_context
+
+        durable_messages = self._messages_after_boundary(messages)
+        governed_messages = (
+            self._model_messages_after_boundary(model_messages)
+            if model_messages is not None and durable_messages
+            else None
+        )
+        request_messages = (
+            governed_messages
+            if governed_messages is not None
+            else durable_messages
+        )
+        supplemental = deepcopy(supplemental_messages or [])
+        self._request_messages = deepcopy(request_messages)
+        request_state = self._state.with_pending_messages([
+            *self._state.pending_messages,
+            *request_messages,
+            *supplemental,
+        ])
+        return ProviderCallContext(
+            conversation_state=request_state,
+            context_window_tokens=(
+                independent_context.context_window_tokens
+                if independent_context is not None
+                else None
+            ),
+        )
+
+    def observe_response(
+        self,
+        response: LLMResponse,
+        messages: list[dict[str, Any]],
+        *,
+        adopt_candidate_state: bool = True,
+    ) -> None:
+        """Advance, preserve, or discard state after one provider response."""
+        candidate = response.provider_state if adopt_candidate_state else None
+        candidate_is_replayable = response.finish_reason in {
+            "stop",
+            "tool_calls",
+            "function_call",
+        }
+        if (
+            candidate is not None
+            and candidate_is_replayable
+            and self._provider.can_resume_conversation_state(
+                candidate,
+                self._model,
+            )
+        ):
+            self._state = candidate
+            self._boundary = len(messages)
+            self._seal_boundary(messages)
+        elif response.finish_reason == "error" and (
+            response.preserve_provider_state_on_error is True
+            or (
+                response.preserve_provider_state_on_error is None
+                and LLMProvider.is_transient_response(response)
+            )
+        ):
+            if self._state is not None and self._request_messages:
+                self._state = self._state.with_pending_messages([
+                    *self._state.pending_messages,
+                    *self._request_messages,
+                ])
+            self._boundary = len(messages)
+        else:
+            self._state = None
+            self._boundary = len(messages)
+        self._request_messages = []
+
+    @staticmethod
+    def project_response_message(
+        message: dict[str, Any],
+        response: LLMResponse,
+    ) -> dict[str, Any]:
+        """Mark a Chat projection already represented by provider output."""
+        if response.provider_state is None:
+            return message
+        internal_meta = dict(message.get("_meta") or {})
+        internal_meta[_PROVIDER_STATE_OUTPUT_META] = True
+        message["_meta"] = internal_meta
+        return message
+
+    def checkpoint(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        model_messages: list[dict[str, Any]] | None = None,
+    ) -> ProviderConversationState | None:
+        """Return a durable state snapshot without changing live state."""
+        if self._state is None:
+            return None
+        durable_messages = self._messages_after_boundary(messages)
+        governed_messages = (
+            self._model_messages_after_boundary(model_messages)
+            if model_messages is not None and durable_messages
+            else None
+        )
+        pending_messages = (
+            governed_messages
+            if governed_messages is not None
+            else durable_messages
+        )
+        return self._state.with_pending_messages([
+            *self._state.pending_messages,
+            *pending_messages,
+        ])
+
+    def finish(
+        self,
+        messages: list[dict[str, Any]],
+    ) -> ProviderConversationState | None:
+        """Return the final durable state after all runner messages are known."""
+        self._state = self.checkpoint(messages)
+        return self._state
+
+    def _messages_after_boundary(
+        self,
+        messages: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        pending: list[dict[str, Any]] = []
+        for message in messages[self._boundary:]:
+            internal_meta = cast(object, message.get("_meta"))
+            if (
+                isinstance(internal_meta, dict)
+                and cast(dict[str, Any], internal_meta).get(
+                    _PROVIDER_STATE_OUTPUT_META
+                ) is True
+            ):
+                continue
+            pending.append(deepcopy(message))
+        return pending
+
+    @staticmethod
+    def _model_messages_after_boundary(
+        messages: list[dict[str, Any]],
+    ) -> list[dict[str, Any]] | None:
+        """Return the governed delta after the latest provider-owned boundary."""
+        boundary = None
+        for idx in range(len(messages) - 1, -1, -1):
+            internal_meta = cast(object, messages[idx].get("_meta"))
+            if (
+                isinstance(internal_meta, dict)
+                and cast(dict[str, Any], internal_meta).get(
+                    _PROVIDER_STATE_BOUNDARY_META
+                ) is True
+            ):
+                boundary = idx
+                break
+        if boundary is None:
+            return None
+
+        pending: list[dict[str, Any]] = []
+        for message in messages[boundary + 1:]:
+            internal_meta = cast(object, message.get("_meta"))
+            if (
+                isinstance(internal_meta, dict)
+                and cast(dict[str, Any], internal_meta).get(
+                    _PROVIDER_STATE_OUTPUT_META
+                ) is True
+            ):
+                continue
+            pending.append(deepcopy(message))
+        return pending
+
+    @staticmethod
+    def _seal_boundary(messages: list[dict[str, Any]]) -> None:
+        """Prevent later same-role injection merging across a state boundary."""
+        if not messages:
+            return
+        internal_meta = dict(messages[-1].get("_meta") or {})
+        internal_meta[_PROVIDER_STATE_BOUNDARY_META] = True
+        messages[-1]["_meta"] = internal_meta

nanobot/providers/factory.py

@@ -261,6 +261,7 @@ def make_provider(
             primary=provider,
             fallback_presets=fallback_presets,
             provider_factory=lambda fb: _make_provider_core(config, preset=fb),
+            primary_context_window_tokens=resolved.context_window_tokens,
         )
 
     return provider

nanobot/providers/fallback_provider.py

@@ -6,11 +6,18 @@ from __future__ import annotations
 
 import time
 from collections.abc import Awaitable, Callable
+from dataclasses import replace
 from typing import Any
 
 from loguru import logger
 
-from nanobot.providers.base import GenerationSettings, LLMProvider, LLMResponse
+from nanobot.providers.base import (
+    GenerationSettings,
+    LLMProvider,
+    LLMResponse,
+    ProviderCallContext,
+    ProviderConversationState,
+)
 
 # Circuit breaker tuned to match OpenAICompatProvider's Responses API breaker.
 _PRIMARY_FAILURE_THRESHOLD = 3
@@ -113,11 +120,13 @@ class FallbackProvider(LLMProvider):
         fallback_presets: list[Any],
         provider_factory: Callable[[Any], LLMProvider],
         fallback_model_observer: FallbackModelObserver | None = None,
+        primary_context_window_tokens: int | None = None,
     ):
         self._primary = primary
         self._fallback_presets = list(fallback_presets)
         self._provider_factory = provider_factory
         self._fallback_model_observer = fallback_model_observer
+        self._primary_context_window_tokens = primary_context_window_tokens
         self._has_fallbacks = bool(fallback_presets)
         self._primary_failures = 0
         self._primary_tripped_at: float | None = None
@@ -141,6 +150,33 @@ class FallbackProvider(LLMProvider):
     def supports_progress_deltas(self) -> bool:
         return bool(getattr(self._primary, "supports_progress_deltas", False))
 
+    def can_resume_conversation_state(
+        self,
+        state: ProviderConversationState,
+        model: str | None = None,
+    ) -> bool:
+        return self._primary.can_resume_conversation_state(state, model)
+
+    def supports_native_compaction(self, model: str | None = None) -> bool:
+        return self._primary.supports_native_compaction(model)
+
+    def _primary_call_context(
+        self,
+        provider_context: ProviderCallContext,
+        model: str | None,
+    ) -> ProviderCallContext:
+        context_window_tokens = (
+            self._primary_context_window_tokens
+            if self._primary_context_window_tokens is not None
+            else provider_context.context_window_tokens
+        )
+        if not self._primary.supports_native_compaction(model):
+            context_window_tokens = None
+        return ProviderCallContext(
+            conversation_state=provider_context.conversation_state,
+            context_window_tokens=context_window_tokens,
+        )
+
     def _primary_available(self) -> bool:
         """Return True if the primary provider is not currently tripped."""
         if self._primary_tripped_at is None:
@@ -157,6 +193,25 @@ class FallbackProvider(LLMProvider):
             lambda p, kw: p.chat(**kw), kwargs, has_streamed=None
         )
 
+    async def chat_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        call_kwargs: dict[str, Any] = dict(kwargs)
+        call_kwargs["provider_context"] = self._primary_call_context(
+            provider_context,
+            kwargs.get("model"),
+        )
+        if not self._has_fallbacks:
+            return await self._primary.chat_with_context(**call_kwargs)
+        return await self._try_with_fallback(
+            lambda p, kw: p.chat_with_context(**kw),
+            call_kwargs,
+            has_streamed=None,
+        )
+
     async def chat_stream(self, **kwargs: Any) -> LLMResponse:
         on_stream_recover = kwargs.pop("on_stream_recover", None)
         if not self._has_fallbacks:
@@ -179,6 +234,38 @@ class FallbackProvider(LLMProvider):
             on_stream_recover=on_stream_recover,
         )
 
+    async def chat_stream_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        on_stream_recover = kwargs.pop("on_stream_recover", None)
+        call_kwargs: dict[str, Any] = dict(kwargs)
+        call_kwargs["provider_context"] = self._primary_call_context(
+            provider_context,
+            kwargs.get("model"),
+        )
+        if not self._has_fallbacks:
+            return await self._primary.chat_stream_with_context(**call_kwargs)
+
+        has_streamed: list[bool] = [False]
+        original_delta = call_kwargs.get("on_content_delta")
+
+        async def _tracking_delta(text: str) -> None:
+            if text:
+                has_streamed[0] = True
+            if original_delta:
+                await original_delta(text)
+
+        call_kwargs["on_content_delta"] = _tracking_delta
+        return await self._try_with_fallback(
+            lambda p, kw: p.chat_stream_with_context(**kw),
+            call_kwargs,
+            has_streamed=has_streamed,
+            on_stream_recover=on_stream_recover,
+        )
+
     async def _try_with_fallback(
         self,
         call: Callable[[LLMProvider, dict[str, Any]], Awaitable[LLMResponse]],
@@ -189,6 +276,9 @@ class FallbackProvider(LLMProvider):
         primary_model = kwargs.get("model") or self._primary.get_default_model()
         primary_was_attempted = False
         primary_error = "unknown error"
+        # A primary error eligible for failover did not return a replacement
+        # continuation, so the incoming primary state remains reusable.
+        preserve_primary_state = True
 
         if self._primary_available():
             primary_was_attempted = True
@@ -286,6 +376,23 @@ class FallbackProvider(LLMProvider):
                 "max_tokens": fallback.max_tokens,
                 "temperature": fallback.temperature,
             }
+            provider_context = fallback_kwargs.get("provider_context")
+            if isinstance(provider_context, ProviderCallContext):
+                state = provider_context.conversation_state
+                if state is not None and not fallback_provider.can_resume_conversation_state(
+                    state,
+                    fallback_model,
+                ):
+                    state = None
+                context_window_tokens = (
+                    fallback.context_window_tokens
+                    if fallback_provider.supports_native_compaction(fallback_model)
+                    else None
+                )
+                fallback_kwargs["provider_context"] = ProviderCallContext(
+                    conversation_state=state,
+                    context_window_tokens=context_window_tokens,
+                )
             if fallback.reasoning_effort is None:
                 fallback_kwargs.pop("reasoning_effort", None)
             else:
@@ -312,11 +419,15 @@ class FallbackProvider(LLMProvider):
         )
         # Return the last error response we saw (primary or last fallback).
         if last_response is not None:
-            return last_response
+            return replace(
+                last_response,
+                preserve_provider_state_on_error=preserve_primary_state,
+            )
         # Primary was tripped and we have no fallbacks — synthesize an error.
         return LLMResponse(
             content=f"Primary model '{primary_model}' circuit open and no fallbacks available",
             finish_reason="error",
+            preserve_provider_state_on_error=preserve_primary_state,
         )
 
     async def _notify_fallback_model(self, model: str) -> None:

nanobot/providers/github_copilot_provider.py

@@ -16,7 +16,7 @@ import httpx
 from oauth_cli_kit.models import OAuthToken
 from oauth_cli_kit.storage import FileTokenStorage
 
-from nanobot.providers.base import LLMResponse
+from nanobot.providers.base import LLMResponse, ProviderCallContext
 from nanobot.providers.openai_compat_provider import OpenAICompatProvider
 
 DEFAULT_GITHUB_DEVICE_CODE_URL = "https://github.com/login/device/code"
@@ -248,6 +248,7 @@ class GitHubCopilotProvider(OpenAICompatProvider):
         temperature: float = 0.7,
         reasoning_effort: str | None = None,
         tool_choice: str | dict[str, Any] | None = None,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         await self._refresh_client_api_key()
         return await super().chat(
@@ -258,6 +259,7 @@ class GitHubCopilotProvider(OpenAICompatProvider):
             temperature=temperature,
             reasoning_effort=reasoning_effort,
             tool_choice=tool_choice,
+            provider_context=provider_context,
         )
 
     async def chat_stream(
@@ -272,6 +274,7 @@ class GitHubCopilotProvider(OpenAICompatProvider):
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
         on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         await self._refresh_client_api_key()
         return await super().chat_stream(
@@ -285,4 +288,5 @@ class GitHubCopilotProvider(OpenAICompatProvider):
             on_content_delta=on_content_delta,
             on_thinking_delta=on_thinking_delta,
             on_tool_call_delta=on_tool_call_delta,
+            provider_context=provider_context,
         )

nanobot/providers/openai_codex_oauth.py

@@ -0,0 +1,272 @@
+"""WebUI adapter around oauth-cli-kit's interactive Codex login."""
+
+# oauth-cli-kit does not publish type stubs.
+# pyright: reportMissingTypeStubs=false
+
+from __future__ import annotations
+
+import hmac
+import queue
+import re
+import threading
+import time
+from concurrent.futures import Future
+from contextlib import suppress
+from urllib.parse import parse_qs, urlsplit
+
+from oauth_cli_kit import login_oauth_interactive
+from oauth_cli_kit.models import OAuthToken
+from oauth_cli_kit.providers import OPENAI_CODEX_PROVIDER
+
+_AUTHORIZATION_URL_TIMEOUT_S = 5.0
+_CALLBACK = urlsplit(OPENAI_CODEX_PROVIDER.redirect_uri)
+_CALLBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
+_TOKEN_EXCHANGE_STATUS = re.compile(r"Token exchange failed:\s*(\d{3})\b")
+
+
+class OpenAICodexOAuthError(RuntimeError):
+    """An actionable Codex OAuth failure that contains no credential material."""
+
+
+class OpenAICodexOAuthInputError(OpenAICodexOAuthError):
+    """A recoverable error in a callback URL pasted by the user."""
+
+
+class OpenAICodexOAuthLoginFlow:
+    """Expose oauth-cli-kit's blocking prompt as a two-stage WebUI flow."""
+
+    def __init__(
+        self,
+        *,
+        proxy: str | None,
+        timeout_s: float,
+        open_browser: bool,
+    ) -> None:
+        self.authorization_url = ""
+        self._expected_state = ""
+        self._proxy = proxy
+        self._open_browser = open_browser
+        self._expires_at = time.monotonic() + timeout_s
+        self._callback_input: queue.Queue[str] = queue.Queue(maxsize=1)
+        self._result: Future[OAuthToken] = Future()
+        self._ready = threading.Event()
+        self._submission_lock = threading.Lock()
+        self._submitted = False
+        self._thread = threading.Thread(
+            target=self._run,
+            name="nanobot-openai-codex-oauth",
+            daemon=True,
+        )
+
+    @property
+    def expired(self) -> bool:
+        return time.monotonic() >= self._expires_at
+
+    @property
+    def remaining_seconds(self) -> int:
+        return max(0, int(self._expires_at - time.monotonic()))
+
+    def start(self) -> OpenAICodexOAuthLoginFlow:
+        self._thread.start()
+        wait_s = min(
+            _AUTHORIZATION_URL_TIMEOUT_S,
+            max(0.0, self._expires_at - time.monotonic()),
+        )
+        if not self._ready.wait(wait_s):
+            error = OpenAICodexOAuthError(
+                "OpenAI Codex sign-in could not create an authorization URL."
+            )
+            self._fail(error)
+            raise error
+        if self._result.done():
+            self._result.result()
+        if self.authorization_url:
+            return self
+        error = OpenAICodexOAuthError(
+            "OpenAI Codex sign-in returned no authorization URL."
+        )
+        self._fail(error)
+        raise error
+
+    def complete(self, callback_url: str | None = None) -> OAuthToken | None:
+        """Submit a full callback URL, or return ``None`` while waiting for one."""
+        if self._result.done():
+            return self._result.result()
+        if self.expired:
+            error = OpenAICodexOAuthError(
+                "OpenAI Codex sign-in expired. Start a new sign-in flow."
+            )
+            self._fail(error)
+            raise error
+        if callback_url is None:
+            return None
+
+        callback_state, authorization_failed = _validate_callback_url(callback_url)
+        if not hmac.compare_digest(callback_state, self._expected_state):
+            raise OpenAICodexOAuthInputError(
+                "The callback URL does not belong to this sign-in flow. Copy the latest URL."
+            )
+        if authorization_failed:
+            error = OpenAICodexOAuthError(
+                "OpenAI Codex sign-in was not completed by the authorization server."
+            )
+            self._fail(error)
+            raise error
+
+        with self._submission_lock:
+            if self._submitted:
+                return None
+            self._submitted = True
+            try:
+                self._callback_input.put_nowait(callback_url.strip())
+            except queue.Full:
+                return None
+        return self._result.result() if self._result.done() else None
+
+    def cancel(self) -> None:
+        """Unblock an abandoned interactive login."""
+        self._fail(OpenAICodexOAuthError("OpenAI Codex sign-in was cancelled."))
+        if threading.current_thread() is not self._thread:
+            self._thread.join(timeout=0.5)
+
+    def _run(self) -> None:
+        try:
+            token = login_oauth_interactive(
+                print_fn=self._capture_output,
+                prompt_fn=self._prompt_for_callback,
+                provider=OPENAI_CODEX_PROVIDER,
+                proxy=self._proxy,
+                open_browser=self._open_browser,
+            )
+        except Exception as exc:
+            with suppress(Exception):
+                self._result.set_exception(_safe_login_error(exc))
+        else:
+            with suppress(Exception):
+                self._result.set_result(token)
+        finally:
+            self._ready.set()
+
+    def _capture_output(self, message: str) -> None:
+        raw = str(message)
+        start = raw.find(OPENAI_CODEX_PROVIDER.authorize_url)
+        if start < 0:
+            return
+        candidate = raw[start:].split(maxsplit=1)[0]
+        state = _first(parse_qs(urlsplit(candidate).query), "state")
+        if not state:
+            return
+        self.authorization_url = candidate
+        self._expected_state = state
+        self._ready.set()
+
+    def _prompt_for_callback(self, _prompt: str) -> str:
+        remaining = max(0.0, self._expires_at - time.monotonic())
+        try:
+            value = self._callback_input.get(timeout=remaining)
+        except queue.Empty as exc:
+            raise OpenAICodexOAuthError(
+                "OpenAI Codex sign-in expired. Start a new sign-in flow."
+            ) from exc
+        if not value:
+            error = self._result.exception() if self._result.done() else None
+            if error is not None:
+                raise error
+            raise OpenAICodexOAuthError("OpenAI Codex sign-in was cancelled.")
+        return value
+
+    def _fail(self, error: OpenAICodexOAuthError) -> None:
+        try:
+            self._result.set_exception(error)
+        except Exception:
+            pass
+        else:
+            with suppress(queue.Full):
+                self._callback_input.put_nowait("")
+        self._ready.set()
+
+
+def start_openai_codex_oauth_login(
+    *,
+    proxy: str | None = None,
+    timeout_s: float = 600,
+    open_browser: bool = True,
+) -> OpenAICodexOAuthLoginFlow:
+    """Start a non-blocking wrapper around oauth-cli-kit's Codex login."""
+    return OpenAICodexOAuthLoginFlow(
+        proxy=proxy,
+        timeout_s=timeout_s,
+        open_browser=open_browser,
+    ).start()
+
+
+def complete_openai_codex_oauth_login(
+    flow: OpenAICodexOAuthLoginFlow,
+    callback_url: str | None = None,
+) -> OAuthToken | None:
+    """Complete a pending Codex login from a full callback URL."""
+    return flow.complete(callback_url)
+
+
+def _validate_callback_url(raw: str) -> tuple[str, bool]:
+    value = raw.strip()
+    if not value:
+        raise OpenAICodexOAuthInputError("Paste the full callback URL from your browser.")
+    try:
+        parsed = urlsplit(value)
+        port = parsed.port
+    except ValueError as exc:
+        raise OpenAICodexOAuthInputError(
+            "The callback URL is invalid. Copy the full URL from your browser's address bar."
+        ) from exc
+    if (
+        parsed.scheme != _CALLBACK.scheme
+        or parsed.hostname not in _CALLBACK_HOSTS
+        or port != _CALLBACK.port
+        or parsed.path != _CALLBACK.path
+        or parsed.username is not None
+        or parsed.password is not None
+    ):
+        raise OpenAICodexOAuthInputError(
+            f"Paste the full callback URL from your browser ({OPENAI_CODEX_PROVIDER.redirect_uri}?...)."
+        )
+    params = parse_qs(parsed.query)
+    code = _first(params, "code")
+    state = _first(params, "state")
+    error = _first(params, "error")
+    if not state:
+        raise OpenAICodexOAuthInputError(
+            "The callback URL is missing OAuth state. Copy the entire browser address."
+        )
+    if not code and not error:
+        raise OpenAICodexOAuthInputError(
+            "The callback URL has no authorization result. Finish signing in, then copy it again."
+        )
+    return state, error is not None
+
+
+def _safe_login_error(exc: Exception) -> OpenAICodexOAuthError:
+    if isinstance(exc, OpenAICodexOAuthError):
+        return exc
+    message = str(exc).strip()
+    if message == "State validation failed.":
+        return OpenAICodexOAuthError(
+            "OpenAI Codex sign-in failed because the OAuth state did not match."
+        )
+    if message == "Authorization code not found.":
+        return OpenAICodexOAuthError(
+            "OpenAI Codex sign-in returned no authorization code."
+        )
+    status = _TOKEN_EXCHANGE_STATUS.search(message)
+    if status:
+        return OpenAICodexOAuthError(
+            f"OpenAI Codex OAuth token exchange failed with HTTP {status.group(1)}."
+        )
+    return OpenAICodexOAuthError(
+        f"OpenAI Codex sign-in failed ({type(exc).__name__})."
+    )
+
+
+def _first(params: dict[str, list[str]], key: str) -> str | None:
+    values = params.get(key)
+    return values[0] if values else None

nanobot/providers/openai_codex_provider.py

@@ -17,17 +17,27 @@ from oauth_cli_kit import get_token as get_codex_token
 from nanobot.providers.base import (
     LLMProvider,
     LLMResponse,
-    ToolCallRequest,
+    ProviderCallContext,
+    ProviderConversationState,
     resolve_stream_idle_timeout_s,
 )
 from nanobot.providers.openai_responses import (
+    ResponsesStreamCapture,
+    build_responses_state,
     consume_sse_with_reasoning,
-    convert_messages,
     convert_tools,
+    is_compaction_compatibility_error,
+    is_replayable_finish_reason,
+    prepare_responses_input,
+    resolve_compact_threshold,
+    responses_state_context_tokens,
+    responses_state_items,
+    responses_state_matches,
 )
 
 DEFAULT_CODEX_URL = "https://chatgpt.com/backend-api/codex/responses"
 DEFAULT_ORIGINATOR = "nanobot"
+_COMPACTION_RETAINED_CHAR_BUDGET = 256_000
 
 
 class OpenAICodexProvider(LLMProvider):
@@ -45,21 +55,39 @@ class OpenAICodexProvider(LLMProvider):
         self.default_model = default_model
         self.proxy = proxy or None
         self._extra_body = dict(extra_body or {})
+        self._native_compaction_available = True
 
     async def _call_codex(
         self,
         messages: list[dict[str, Any]],
         tools: list[dict[str, Any]] | None,
         model: str | None,
+        max_tokens: int,
         reasoning_effort: str | None,
         tool_choice: str | dict[str, Any] | None,
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
         on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         """Shared request logic for both chat() and chat_stream()."""
         model = model or self.default_model
-        system_prompt, input_items = convert_messages(messages)
+        sanitized_messages = self._sanitize_empty_content(messages)
+        sanitized_state = (
+            provider_context.conversation_state
+            if provider_context is not None
+            else None
+        )
+        if sanitized_state is not None:
+            sanitized_state = sanitized_state.with_pending_messages(
+                self._sanitize_empty_content(sanitized_state.pending_messages)
+            )
+        system_prompt, input_items, replayed = prepare_responses_input(
+            sanitized_messages,
+            state=sanitized_state,
+            provider=self._responses_state_provider(),
+            model=_strip_model_prefix(model),
+        )
 
         body: dict[str, Any] = {
             "model": _strip_model_prefix(model),
@@ -68,12 +96,15 @@ class OpenAICodexProvider(LLMProvider):
             "instructions": system_prompt,
             "input": input_items,
             "text": {"verbosity": "medium"},
-            "include": ["reasoning.encrypted_content"],
             "prompt_cache_key": _prompt_cache_key(messages[:2]),
             "tool_choice": tool_choice or "auto",
             "parallel_tool_calls": True,
         }
+        body["include"] = ["reasoning.encrypted_content"]
         reasoning_options = _build_reasoning_options(reasoning_effort)
+        if replayed and "gpt-5.6" in _strip_model_prefix(model).lower():
+            reasoning_options = dict(reasoning_options or {})
+            reasoning_options["context"] = "all_turns"
         if reasoning_options:
             body["reasoning"] = reasoning_options
         if tools:
@@ -87,33 +118,90 @@ class OpenAICodexProvider(LLMProvider):
             token = await asyncio.to_thread(get_codex_token, proxy=self.proxy)
             headers = _build_headers(cast(str, token.account_id), token.access)
 
-            stage = "codex_request"
-            try:
-                content, tool_calls, finish_reason, usage, reasoning_content = await _request_codex(
-                    DEFAULT_CODEX_URL, headers, body, verify=True,
-                    proxy=self.proxy,
-                    on_content_delta=on_content_delta,
-                    on_thinking_delta=on_thinking_delta,
-                    on_tool_call_delta=on_tool_call_delta,
-                )
-            except Exception as e:
-                if "CERTIFICATE_VERIFY_FAILED" not in str(e):
-                    raise
-                logger.warning("SSL verification failed for Codex API; retrying with verify=False")
-                content, tool_calls, finish_reason, usage, reasoning_content = await _request_codex(
-                    DEFAULT_CODEX_URL, headers, body, verify=False,
-                    proxy=self.proxy,
-                    on_content_delta=on_content_delta,
-                    on_thinking_delta=on_thinking_delta,
-                    on_tool_call_delta=on_tool_call_delta,
-                )
-            return LLMResponse(
-                content=content,
-                tool_calls=tool_calls,
-                finish_reason=finish_reason,
-                usage=usage,
-                reasoning_content=reasoning_content,
+            async def _send(
+                request_body: dict[str, Any],
+                *,
+                emit_deltas: bool,
+            ) -> LLMResponse:
+                wire_body = _without_response_item_ids(request_body)
+                try:
+                    return await _request_codex(
+                        DEFAULT_CODEX_URL,
+                        headers,
+                        wire_body,
+                        verify=True,
+                        proxy=self.proxy,
+                        on_content_delta=on_content_delta if emit_deltas else None,
+                        on_thinking_delta=on_thinking_delta if emit_deltas else None,
+                        on_tool_call_delta=on_tool_call_delta if emit_deltas else None,
+                    )
+                except Exception as exc:
+                    if "CERTIFICATE_VERIFY_FAILED" not in str(exc):
+                        raise
+                    logger.warning(
+                        "SSL verification failed for Codex API; retrying with verify=False"
+                    )
+                    return await _request_codex(
+                        DEFAULT_CODEX_URL,
+                        headers,
+                        wire_body,
+                        verify=False,
+                        proxy=self.proxy,
+                        on_content_delta=on_content_delta if emit_deltas else None,
+                        on_thinking_delta=on_thinking_delta if emit_deltas else None,
+                        on_tool_call_delta=on_tool_call_delta if emit_deltas else None,
+                    )
+
+            compact_threshold = resolve_compact_threshold(
+                (
+                    provider_context.context_window_tokens
+                    if provider_context is not None
+                    else None
+                ),
+                max_tokens,
             )
+            if (
+                self.supports_native_compaction(model)
+                and replayed
+                and sanitized_state is not None
+                and compact_threshold is not None
+                and responses_state_context_tokens(sanitized_state) >= compact_threshold
+            ):
+                stage = "codex_compaction"
+                compact_body = {
+                    **body,
+                    "input": [*input_items, {"type": "compaction_trigger"}],
+                }
+                try:
+                    compact_result = await _send(compact_body, emit_deltas=False)
+                    compact_items = (
+                        responses_state_items(compact_result.provider_state)
+                        if compact_result.provider_state is not None
+                        else None
+                    )
+                    if not compact_items or compact_items[-1].get("type") not in {
+                        "compaction",
+                        "compaction_summary",
+                        "context_compaction",
+                    }:
+                        raise RuntimeError("Codex compaction returned no compaction item")
+                    body["input"] = [
+                        *_retained_compaction_messages(input_items),
+                        *compact_items,
+                    ]
+                except Exception as compact_error:
+                    if is_compaction_compatibility_error(compact_error):
+                        self._native_compaction_available = False
+                    logger.warning(
+                        "Codex native compaction unavailable; continuing without it "
+                        "(type={} status={} disabled={})",
+                        type(compact_error).__name__,
+                        getattr(compact_error, "status_code", None),
+                        not self._native_compaction_available,
+                    )
+
+            stage = "codex_request"
+            return await _send(body, emit_deltas=True)
         except Exception as e:
             response = _codex_error_response(e)
             exc_type = "CodexHTTPError" if isinstance(e, _CodexHTTPError) else type(e).__name__
@@ -137,8 +225,28 @@ class OpenAICodexProvider(LLMProvider):
         model: str | None = None, max_tokens: int = 4096, temperature: float = 0.7,
         reasoning_effort: str | None = None,
         tool_choice: str | dict[str, Any] | None = None,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
-        return await self._call_codex(messages, tools, model, reasoning_effort, tool_choice)
+        return await self._call_codex(
+            messages,
+            tools,
+            model,
+            max_tokens,
+            reasoning_effort,
+            tool_choice,
+            provider_context=provider_context,
+        )
+
+    async def chat_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        return await self.chat(
+            **kwargs,
+            provider_context=provider_context,
+        )
 
     async def chat_stream(
         self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None = None,
@@ -148,21 +256,55 @@ class OpenAICodexProvider(LLMProvider):
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
         on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         return await self._call_codex(
-            messages,
-            tools,
-            model,
-            reasoning_effort,
-            tool_choice,
-            on_content_delta,
-            on_thinking_delta,
-            on_tool_call_delta,
+            messages=messages,
+            tools=tools,
+            model=model,
+            max_tokens=max_tokens,
+            reasoning_effort=reasoning_effort,
+            tool_choice=tool_choice,
+            on_content_delta=on_content_delta,
+            on_thinking_delta=on_thinking_delta,
+            on_tool_call_delta=on_tool_call_delta,
+            provider_context=provider_context,
+        )
+
+    async def chat_stream_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        return await self.chat_stream(
+            **kwargs,
+            provider_context=provider_context,
         )
 
     def get_default_model(self) -> str:
         return self.default_model
 
+    @staticmethod
+    def _responses_state_provider() -> str:
+        return f"openai_codex:{DEFAULT_CODEX_URL.rstrip('/')}"
+
+    def can_resume_conversation_state(
+        self,
+        state: ProviderConversationState,
+        model: str | None = None,
+    ) -> bool:
+        return responses_state_matches(
+            state,
+            provider=self._responses_state_provider(),
+            model=_strip_model_prefix(model or self.default_model),
+        )
+
+    def supports_native_compaction(self, model: str | None = None) -> bool:
+        """Use the Codex backend's inline compaction trigger when needed."""
+        _ = model
+        return self._native_compaction_available
+
 
 def _strip_model_prefix(model: str) -> str:
     if model.startswith("openai-codex/") or model.startswith("openai_codex/"):
@@ -170,6 +312,58 @@ def _strip_model_prefix(model: str) -> str:
     return model
 
 
+def _without_response_item_ids(
+    request_body: dict[str, Any],
+) -> dict[str, Any]:
+    """Match Codex's default ``store=false`` request-item contract."""
+    if request_body.get("store") is True:
+        return request_body
+    raw_input = request_body.get("input")
+    if not isinstance(raw_input, list):
+        return request_body
+
+    input_items: list[object] = cast(list[object], raw_input)
+    sanitized_input: list[object] = []
+    for raw_item in input_items:
+        if not isinstance(raw_item, dict):
+            sanitized_input.append(raw_item)
+            continue
+        item = cast(dict[str, Any], raw_item)
+        sanitized_input.append({
+            key: value
+            for key, value in item.items()
+            if key != "id"
+        })
+
+    body = dict(request_body)
+    body["input"] = sanitized_input
+    return body
+
+
+def _retained_compaction_messages(
+    input_items: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Mirror Codex's bounded retention of user/developer/system messages."""
+    retained_reversed: list[dict[str, Any]] = []
+    remaining = _COMPACTION_RETAINED_CHAR_BUDGET
+    for item in reversed(input_items):
+        if item.get("type") not in {None, "message"} or item.get("role") not in {
+            "user",
+            "developer",
+            "system",
+        }:
+            continue
+        size = len(json.dumps(item, ensure_ascii=False))
+        if size > remaining and retained_reversed:
+            continue
+        retained_reversed.append(item)
+        remaining = max(0, remaining - size)
+        if remaining == 0:
+            break
+    retained_reversed.reverse()
+    return retained_reversed
+
+
 def _build_reasoning_options(reasoning_effort: str | None) -> dict[str, str] | None:
     """Opt in to visible summaries without changing provider-default effort."""
     if reasoning_effort and reasoning_effort.lower() == "none":
@@ -202,6 +396,7 @@ class _CodexHTTPError(RuntimeError):
         error_type: str | None = None,
         error_code: str | None = None,
         should_retry: bool | None = None,
+        compaction_unsupported: bool = False,
     ):
         super().__init__(message)
         self.status_code = status_code
@@ -209,6 +404,7 @@ class _CodexHTTPError(RuntimeError):
         self.error_type = error_type
         self.error_code = error_code
         self.should_retry = should_retry
+        self.compaction_unsupported = compaction_unsupported
 
 
 async def _request_codex(
@@ -220,7 +416,7 @@ async def _request_codex(
     on_content_delta: Callable[[str], Awaitable[None]] | None = None,
     on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
     on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
-) -> tuple[str, list[ToolCallRequest], str, dict[str, int], str | None]:
+) -> LLMResponse:
     idle_timeout_s = resolve_stream_idle_timeout_s()
     client_kwargs: dict[str, Any] = {"timeout": idle_timeout_s, "verify": verify}
     if proxy:
@@ -233,6 +429,17 @@ async def _request_codex(
                 raw = text.decode("utf-8", "ignore")
                 retry_after = LLMProvider._extract_retry_after_from_headers(response.headers)
                 error_type, error_code = LLMProvider._extract_error_type_code(raw)
+                compaction_unsupported = (
+                    response.status_code in {400, 404, 422}
+                    and any(
+                        marker in raw.lower()
+                        for marker in (
+                            "context_management",
+                            "compact_threshold",
+                            "compaction_trigger",
+                        )
+                    )
+                )
                 raise _CodexHTTPError(
                     _friendly_error(response.status_code, raw),
                     status_code=response.status_code,
@@ -240,13 +447,38 @@ async def _request_codex(
                     error_type=error_type,
                     error_code=error_code,
                     should_retry=_should_retry_status(response.status_code, error_type, error_code, raw),
+                    compaction_unsupported=compaction_unsupported,
                 )
-            return await consume_sse_with_reasoning(
+            capture = ResponsesStreamCapture()
+            (
+                content,
+                tool_calls,
+                finish_reason,
+                usage,
+                reasoning_content,
+            ) = await consume_sse_with_reasoning(
                 response,
                 on_content_delta=on_content_delta,
                 on_tool_call_delta=on_tool_call_delta,
                 on_reasoning_delta=on_thinking_delta,
+                capture=capture,
             )
+            result = LLMResponse(
+                content=content,
+                tool_calls=tool_calls,
+                finish_reason=finish_reason,
+                usage=usage,
+                reasoning_content=reasoning_content,
+            )
+            if capture.completed and is_replayable_finish_reason(finish_reason):
+                result.provider_state = build_responses_state(
+                    provider=f"openai_codex:{url.rstrip('/')}",
+                    model=str(body.get("model") or ""),
+                    input_items=cast(list[dict[str, Any]], body.get("input") or []),
+                    output_items=capture.output_items,
+                    usage=usage,
+                )
+            return result
 
 
 def _prompt_cache_key(messages: list[dict[str, Any]]) -> str:

nanobot/providers/openai_compat_provider.py

@@ -26,16 +26,24 @@ from pydantic.alias_generators import to_snake
 from nanobot.providers.base import (
     LLMProvider,
     LLMResponse,
+    ProviderCallContext,
+    ProviderConversationState,
     ToolCallRequest,
     parse_tool_arguments,
     resolve_stream_idle_timeout_s,
     tool_arguments_json_for_replay,
 )
 from nanobot.providers.openai_responses import (
+    ResponsesStreamCapture,
+    build_responses_state,
     consume_sdk_stream,
-    convert_messages,
     convert_tools,
+    is_compaction_compatibility_error,
+    is_replayable_finish_reason,
     parse_response_output,
+    prepare_responses_input,
+    resolve_compact_threshold,
+    responses_state_matches,
 )
 
 if TYPE_CHECKING:
@@ -443,6 +451,8 @@ class OpenAICompatProvider(LLMProvider):
     registry lookups needed.
     """
 
+    _native_compaction_available = True
+
     def __init__(
         self,
         api_key: str | None = None,
@@ -463,6 +473,7 @@ class OpenAICompatProvider(LLMProvider):
         self._api_type = api_type if spec and spec.name == "openai" else "auto"
         self._extra_query = extra_query or {}
         self._proxy = proxy or None
+        self._native_compaction_available = True
 
         if api_key and spec and spec.env_key:
             self._setup_env(api_key, api_base)
@@ -971,6 +982,37 @@ class OpenAICompatProvider(LLMProvider):
 
         return self._responses_circuit_allows_probe(model, reasoning_effort)
 
+    def _responses_state_provider(self) -> str:
+        spec_name = self._spec.name if self._spec is not None else "custom"
+        effective_base = self._effective_base or "https://api.openai.com/v1"
+        return f"openai_compat:{spec_name}:{effective_base.rstrip('/')}"
+
+    def _responses_state_model(self, model: str | None) -> str:
+        return self._request_model_name(model or self.default_model)
+
+    def can_resume_conversation_state(
+        self,
+        state: ProviderConversationState,
+        model: str | None = None,
+    ) -> bool:
+        return responses_state_matches(
+            state,
+            provider=self._responses_state_provider(),
+            model=self._responses_state_model(model),
+        )
+
+    def supports_native_compaction(self, model: str | None = None) -> bool:
+        """Enable server compaction only on direct OpenAI Responses endpoints."""
+        _ = model
+        if (
+            not self._native_compaction_available
+            or self._api_type == "chat_completions"
+        ):
+            return False
+        if self._spec is not None and self._spec.name != "openai":
+            return False
+        return _is_direct_openai_base(self._effective_base)
+
     def _responses_circuit_allows_probe(
         self,
         model: str | None,
@@ -1040,12 +1082,29 @@ class OpenAICompatProvider(LLMProvider):
         temperature: float,
         reasoning_effort: str | None,
         tool_choice: str | dict[str, Any] | None,
+        provider_context: ProviderCallContext | None = None,
     ) -> dict[str, Any]:
         """Build a Responses API body for direct OpenAI requests."""
         model_name = model or self.default_model
         model_name = self._request_model_name(model_name)
         sanitized_messages = self._sanitize_messages(self._sanitize_empty_content(messages))
-        instructions, input_items = convert_messages(sanitized_messages)
+        sanitized_state = (
+            provider_context.conversation_state
+            if provider_context is not None
+            else None
+        )
+        if sanitized_state is not None:
+            sanitized_state = sanitized_state.with_pending_messages(
+                self._sanitize_messages(
+                    self._sanitize_empty_content(sanitized_state.pending_messages)
+                )
+            )
+        instructions, input_items, replayed = prepare_responses_input(
+            sanitized_messages,
+            state=sanitized_state,
+            provider=self._responses_state_provider(),
+            model=model_name,
+        )
 
         body: dict[str, Any] = {
             "model": model_name,
@@ -1055,13 +1114,29 @@ class OpenAICompatProvider(LLMProvider):
             "store": False,
             "stream": False,
         }
+        compact_threshold = resolve_compact_threshold(
+            (
+                provider_context.context_window_tokens
+                if provider_context is not None
+                else None
+            ),
+            max_tokens,
+        )
+        if self.supports_native_compaction(model_name) and compact_threshold is not None:
+            body["context_management"] = [{
+                "type": "compaction",
+                "compact_threshold": compact_threshold,
+            }]
 
         if self._supports_temperature(model_name, reasoning_effort):
             body["temperature"] = temperature
 
+        if not self._supports_temperature(model_name, reasoning_effort):
+            body["include"] = ["reasoning.encrypted_content"]
         if reasoning_effort and reasoning_effort.lower() != "none":
             body["reasoning"] = {"effort": reasoning_effort}
-            body["include"] = ["reasoning.encrypted_content"]
+        if replayed and "gpt-5.6" in model_name.lower():
+            body.setdefault("reasoning", {})["context"] = "all_turns"
 
         if tools:
             body["tools"] = convert_tools(tools)
@@ -1073,6 +1148,29 @@ class OpenAICompatProvider(LLMProvider):
 
         return body
 
+    async def _create_response_with_compaction_fallback(
+        self,
+        client: Any,
+        body: dict[str, Any],
+    ) -> Any:
+        """Retry Responses once without server compaction on compatibility errors."""
+        try:
+            return await client.responses.create(**body)
+        except Exception as exc:
+            if (
+                "context_management" not in body
+                or not is_compaction_compatibility_error(exc)
+            ):
+                raise
+            self._native_compaction_available = False
+            body.pop("context_management", None)
+            logger.warning(
+                "Responses server compaction unsupported; disabled for this provider instance "
+                "(status={})",
+                getattr(exc, "status_code", None),
+            )
+            return await client.responses.create(**body)
+
     # ------------------------------------------------------------------
     # Response parsing
     # ------------------------------------------------------------------
@@ -1599,6 +1697,28 @@ class OpenAICompatProvider(LLMProvider):
     # Public API
     # ------------------------------------------------------------------
 
+    async def chat_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        return await self.chat(
+            **kwargs,
+            provider_context=provider_context,
+        )
+
+    async def chat_stream_with_context(
+        self,
+        *,
+        provider_context: ProviderCallContext,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        return await self.chat_stream(
+            **kwargs,
+            provider_context=provider_context,
+        )
+
     async def chat(
         self,
         messages: list[dict[str, Any]],
@@ -1608,6 +1728,7 @@ class OpenAICompatProvider(LLMProvider):
         temperature: float = 0.7,
         reasoning_effort: str | None = None,
         tool_choice: str | dict[str, Any] | None = None,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         client = await self._ensure_client()
         try:
@@ -1616,12 +1737,18 @@ class OpenAICompatProvider(LLMProvider):
                     body = self._build_responses_body(
                         messages, tools, model, max_tokens, temperature,
                         reasoning_effort, tool_choice,
+                        provider_context,
                     )
-                    responses_raw = cast(
-                        Any,
-                        await client.responses.create(**body),
+                    responses_raw = await self._create_response_with_compaction_fallback(
+                        client,
+                        body,
+                    )
+                    result = parse_response_output(
+                        responses_raw,
+                        state_provider=self._responses_state_provider(),
+                        state_model=str(body["model"]),
+                        state_input_items=cast(list[dict[str, Any]], body["input"]),
                     )
-                    result = parse_response_output(responses_raw)
                     self._record_responses_success(model, reasoning_effort)
                     return result
                 except Exception as responses_error:
@@ -1660,6 +1787,7 @@ class OpenAICompatProvider(LLMProvider):
         on_content_delta: Callable[[str], Awaitable[None]] | None = None,
         on_thinking_delta: Callable[[str], Awaitable[None]] | None = None,
         on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+        provider_context: ProviderCallContext | None = None,
     ) -> LLMResponse:
         client = await self._ensure_client()
         idle_timeout_s = resolve_stream_idle_timeout_s()
@@ -1669,11 +1797,12 @@ class OpenAICompatProvider(LLMProvider):
                     body = self._build_responses_body(
                         messages, tools, model, max_tokens, temperature,
                         reasoning_effort, tool_choice,
+                        provider_context,
                     )
                     body["stream"] = True
-                    responses_stream = cast(
-                        Any,
-                        await client.responses.create(**body),
+                    responses_stream = await self._create_response_with_compaction_fallback(
+                        client,
+                        body,
                     )
 
                     async def _timed_stream() -> AsyncIterator[Any]:
@@ -1687,6 +1816,7 @@ class OpenAICompatProvider(LLMProvider):
                             except StopAsyncIteration:
                                 break
 
+                    capture = ResponsesStreamCapture()
                     (
                         content,
                         tool_calls,
@@ -1697,15 +1827,25 @@ class OpenAICompatProvider(LLMProvider):
                         _timed_stream(),
                         on_content_delta,
                         on_tool_call_delta=on_tool_call_delta,
+                        capture=capture,
                     )
                     self._record_responses_success(model, reasoning_effort)
-                    return LLMResponse(
+                    result = LLMResponse(
                         content=content or None,
                         tool_calls=tool_calls,
                         finish_reason=finish_reason,
                         usage=usage,
                         reasoning_content=reasoning_content,
                     )
+                    if capture.completed and is_replayable_finish_reason(finish_reason):
+                        result.provider_state = build_responses_state(
+                            provider=self._responses_state_provider(),
+                            model=str(body["model"]),
+                            input_items=cast(list[dict[str, Any]], body["input"]),
+                            output_items=capture.output_items,
+                            usage=usage,
+                        )
+                    return result
                 except Exception as responses_error:
                     if self._spec and self._spec.name == "github_copilot":
                         # Copilot gateway exposes GPT-5/o-series only via /responses;

nanobot/providers/openai_responses/__init__.py

@@ -1,4 +1,4 @@
-"""Shared helpers for OpenAI Responses API providers (Codex, Azure OpenAI)."""
+"""Shared helpers for provider backends that implement the OpenAI Responses protocol."""
 
 from nanobot.providers.openai_responses.converters import (
     convert_messages,
@@ -8,13 +8,24 @@ from nanobot.providers.openai_responses.converters import (
 )
 from nanobot.providers.openai_responses.parsing import (
     FINISH_REASON_MAP,
+    ResponsesStreamCapture,
     consume_sdk_stream,
     consume_sse,
     consume_sse_with_reasoning,
+    is_replayable_finish_reason,
     iter_sse,
     map_finish_reason,
     parse_response_output,
 )
+from nanobot.providers.openai_responses.state import (
+    build_responses_state,
+    is_compaction_compatibility_error,
+    prepare_responses_input,
+    resolve_compact_threshold,
+    responses_state_context_tokens,
+    responses_state_items,
+    responses_state_matches,
+)
 
 __all__ = [
     "convert_messages",
@@ -25,7 +36,16 @@ __all__ = [
     "consume_sse",
     "consume_sse_with_reasoning",
     "consume_sdk_stream",
+    "ResponsesStreamCapture",
+    "is_replayable_finish_reason",
     "map_finish_reason",
     "parse_response_output",
+    "build_responses_state",
+    "is_compaction_compatibility_error",
+    "prepare_responses_input",
+    "resolve_compact_threshold",
+    "responses_state_context_tokens",
+    "responses_state_items",
+    "responses_state_matches",
     "FINISH_REASON_MAP",
 ]

nanobot/providers/openai_responses/parsing.py

@@ -4,12 +4,14 @@ from __future__ import annotations
 
 import json
 from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
 from typing import Any, AsyncGenerator, cast
 
 import httpx
 from loguru import logger
 
 from nanobot.providers.base import LLMResponse, ToolCallRequest, parse_tool_arguments
+from nanobot.providers.openai_responses.state import build_responses_state
 
 FINISH_REASON_MAP = {
     "completed": "stop",
@@ -17,6 +19,42 @@ FINISH_REASON_MAP = {
     "failed": "error",
     "cancelled": "error",
 }
+REPLAYABLE_FINISH_REASONS = frozenset({"stop", "tool_calls", "function_call"})
+
+
+@dataclass(slots=True)
+class ResponsesStreamCapture:
+    """Losslessly capture terminal output items without changing stream results."""
+
+    completed: bool = False
+    response: dict[str, Any] | None = field(default=None, repr=False)
+    _items_by_index: dict[int, dict[str, Any]] = field(default_factory=dict, repr=False)
+
+    def record_output_item(self, index: object, item: object) -> None:
+        item_object = _response_object(item)
+        if item_object is None:
+            return
+        output_index = (
+            index
+            if isinstance(index, int) and not isinstance(index, bool)
+            else len(self._items_by_index)
+        )
+        self._items_by_index[output_index] = item_object
+
+    def record_completed(self, response: object) -> None:
+        response_object = _response_object(response)
+        if response_object is None:
+            return
+        self.completed = True
+        self.response = response_object
+
+    @property
+    def output_items(self) -> list[dict[str, Any]]:
+        if self.response is not None:
+            output = _response_object_list(self.response.get("output"))
+            if output:
+                return output
+        return [self._items_by_index[index] for index in sorted(self._items_by_index)]
 
 
 def _as_json_object(value: object) -> dict[str, Any] | None:
@@ -54,6 +92,27 @@ def map_finish_reason(status: str | None) -> str:
     return FINISH_REASON_MAP.get(status or "completed", "stop")
 
 
+def is_replayable_finish_reason(finish_reason: str) -> bool:
+    """Return whether a response can safely advance opaque conversation state."""
+    return finish_reason in REPLAYABLE_FINISH_REASONS
+
+
+def _response_finish_reason(
+    response: object,
+    *,
+    fallback_status: str | None = None,
+) -> str:
+    """Map terminal response details without treating content filtering as truncation."""
+    response_object = _response_object(response) or {}
+    status = response_object.get("status")
+    terminal_status = status if isinstance(status, str) else fallback_status
+    if terminal_status == "incomplete":
+        details = _response_object(response_object.get("incomplete_details"))
+        if details is not None and details.get("reason") == "content_filter":
+            return "content_filter"
+    return map_finish_reason(terminal_status)
+
+
 def _usage_from_response_obj(response: object) -> dict[str, int]:
     response_object = _response_object(response)
     usage_raw: object = (
@@ -99,6 +158,47 @@ def _tool_arguments_source(*values: Any) -> Any:
     return "{}"
 
 
+def _refusal_event_key(
+    item_id: object,
+    content_index: object,
+) -> tuple[str | None, int | None]:
+    """Identify one streamed refusal content part across delta/done events."""
+    return (
+        item_id if isinstance(item_id, str) else None,
+        (
+            content_index
+            if isinstance(content_index, int) and not isinstance(content_index, bool)
+            else None
+        ),
+    )
+
+
+def _remaining_refusal_text(streamed_text: str, refusal_text: str) -> str:
+    """Return only text not already surfaced by refusal deltas."""
+    if not streamed_text:
+        return refusal_text
+    if refusal_text.startswith(streamed_text):
+        return refusal_text[len(streamed_text):]
+    return ""
+
+
+def _extract_refusal_text_from_output(output: object) -> tuple[bool, str]:
+    """Extract refusal content from terminal Responses output items."""
+    refusal_seen = False
+    parts: list[str] = []
+    for item in _response_object_list(output):
+        if item.get("type") != "message":
+            continue
+        for block in _response_object_list(item.get("content")):
+            if block.get("type") != "refusal":
+                continue
+            refusal_seen = True
+            refusal_text = block.get("refusal")
+            if isinstance(refusal_text, str):
+                parts.append(refusal_text)
+    return refusal_seen, "".join(parts)
+
+
 async def iter_sse(response: httpx.Response) -> AsyncGenerator[dict[str, Any], None]:
     """Yield parsed JSON events from a Responses API SSE stream."""
     buffer: list[str] = []
@@ -153,6 +253,7 @@ async def consume_sse_with_reasoning(
     on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
     on_reasoning_delta: Callable[[str], Awaitable[None]] | None = None,
     on_response_event: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+    capture: ResponsesStreamCapture | None = None,
 ) -> tuple[str, list[ToolCallRequest], str, dict[str, int], str | None]:
     """Consume a Responses API SSE stream, including visible reasoning summaries."""
     content = ""
@@ -163,6 +264,9 @@ async def consume_sse_with_reasoning(
     usage: dict[str, int] = {}
     reasoning_content: str | None = None
     streamed_reasoning = False
+    refusal_seen = False
+    refusal_deltas: dict[tuple[str | None, int | None], str] = {}
+    emitted_refusal_text = ""
 
     async for event in iter_sse(response):
         if on_response_event:
@@ -191,6 +295,33 @@ async def consume_sse_with_reasoning(
             content += delta_text
             if on_content_delta and delta_text:
                 await on_content_delta(delta_text)
+        elif event_type == "response.refusal.delta":
+            refusal_seen = True
+            delta_text = event.get("delta")
+            if isinstance(delta_text, str) and delta_text:
+                key = _refusal_event_key(
+                    event.get("item_id"),
+                    event.get("content_index"),
+                )
+                refusal_deltas[key] = refusal_deltas.get(key, "") + delta_text
+                content += delta_text
+                emitted_refusal_text += delta_text
+                if on_content_delta:
+                    await on_content_delta(delta_text)
+        elif event_type == "response.refusal.done":
+            refusal_seen = True
+            refusal_text = event.get("refusal")
+            key = _refusal_event_key(
+                event.get("item_id"),
+                event.get("content_index"),
+            )
+            streamed_text = refusal_deltas.pop(key, "")
+            if isinstance(refusal_text, str) and refusal_text:
+                remaining_text = _remaining_refusal_text(streamed_text, refusal_text)
+                content += remaining_text
+                emitted_refusal_text += remaining_text
+                if on_content_delta and remaining_text:
+                    await on_content_delta(remaining_text)
         elif event_type == "response.reasoning_summary_text.delta":
             delta_text = event.get("delta") or ""
             if delta_text:
@@ -239,6 +370,8 @@ async def consume_sse_with_reasoning(
                     })
         elif event_type == "response.output_item.done":
             item = _as_json_object(event.get("item")) or {}
+            if capture is not None:
+                capture.record_output_item(event.get("output_index"), item)
             if item.get("type") == "function_call":
                 call_id = item.get("call_id")
                 if not call_id:
@@ -269,11 +402,28 @@ async def consume_sse_with_reasoning(
                     reasoning_content = summary
                     if on_reasoning_delta:
                         await on_reasoning_delta(summary)
-        elif event_type == "response.completed":
+        elif event_type in {"response.completed", "response.incomplete"}:
             response_obj = _response_object(event.get("response")) or {}
-            status = response_obj.get("status")
-            finish_reason = map_finish_reason(status)
+            if capture is not None:
+                capture.record_completed(response_obj)
+            finish_reason = _response_finish_reason(
+                response_obj,
+                fallback_status=event_type.removeprefix("response."),
+            )
             usage = _usage_from_response_obj(response_obj) or usage
+            terminal_refusal, terminal_refusal_text = _extract_refusal_text_from_output(
+                response_obj.get("output")
+            )
+            if terminal_refusal:
+                refusal_seen = True
+                remaining_text = _remaining_refusal_text(
+                    emitted_refusal_text,
+                    terminal_refusal_text,
+                )
+                content += remaining_text
+                emitted_refusal_text += remaining_text
+                if on_content_delta and remaining_text:
+                    await on_content_delta(remaining_text)
             if not reasoning_content:
                 summary = _extract_reasoning_summary_from_output(response_obj.get("output"))
                 if summary:
@@ -284,6 +434,8 @@ async def consume_sse_with_reasoning(
             detail = event.get("error") or event.get("message") or event
             raise RuntimeError(f"Response failed: {str(detail)[:500]}")
 
+    if refusal_seen:
+        finish_reason = "refusal"
     return content, tool_calls, finish_reason, usage, reasoning_content
 
 
@@ -300,7 +452,13 @@ def _extract_reasoning_summary_from_output(output: object) -> str | None:
     return "".join(parts) or None
 
 
-def parse_response_output(response: object) -> LLMResponse:
+def parse_response_output(
+    response: object,
+    *,
+    state_provider: str | None = None,
+    state_model: str | None = None,
+    state_input_items: list[dict[str, Any]] | None = None,
+) -> LLMResponse:
     """Parse an SDK ``Response`` object into an ``LLMResponse``."""
     response_object = _response_object(response) or {}
 
@@ -308,15 +466,22 @@ def parse_response_output(response: object) -> LLMResponse:
     content_parts: list[str] = []
     tool_calls: list[ToolCallRequest] = []
     reasoning_content: str | None = None
+    refusal_seen = False
 
     for item in output:
         item_type = item.get("type")
         if item_type == "message":
             for block in _response_object_list(item.get("content")):
-                if block.get("type") == "output_text":
+                block_type = block.get("type")
+                if block_type == "output_text":
                     text = block.get("text")
                     if isinstance(text, str):
                         content_parts.append(text)
+                elif block_type == "refusal":
+                    refusal_seen = True
+                    refusal = block.get("refusal")
+                    if isinstance(refusal, str):
+                        content_parts.append(refusal)
         elif item_type == "reasoning":
             for s in _response_object_list(item.get("summary")):
                 if s.get("type") == "summary_text" and s.get("text"):
@@ -337,21 +502,37 @@ def parse_response_output(response: object) -> LLMResponse:
     usage = _usage_from_response_obj(response_object)
 
     status = response_object.get("status")
-    finish_reason = map_finish_reason(status if isinstance(status, str) else None)
+    finish_reason = "refusal" if refusal_seen else _response_finish_reason(response_object)
 
-    return LLMResponse(
+    result = LLMResponse(
         content="".join(content_parts) or None,
         tool_calls=tool_calls,
         finish_reason=finish_reason,
         usage=usage,
         reasoning_content=reasoning_content if isinstance(reasoning_content, str) else None,
     )
+    if (
+        state_provider is not None
+        and state_model is not None
+        and state_input_items is not None
+        and (status is None or status == "completed")
+        and is_replayable_finish_reason(finish_reason)
+    ):
+        result.provider_state = build_responses_state(
+            provider=state_provider,
+            model=state_model,
+            input_items=state_input_items,
+            output_items=output,
+            usage=usage,
+        )
+    return result
 
 
 async def consume_sdk_stream(
     stream: Any,
     on_content_delta: Callable[[str], Awaitable[None]] | None = None,
     on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+    capture: ResponsesStreamCapture | None = None,
 ) -> tuple[str, list[ToolCallRequest], str, dict[str, int], str | None]:
     """Consume an SDK async stream from ``client.responses.create(stream=True)``."""
     content = ""
@@ -361,6 +542,9 @@ async def consume_sdk_stream(
     finish_reason = "stop"
     usage: dict[str, int] = {}
     reasoning_content: str | None = None
+    refusal_seen = False
+    refusal_deltas: dict[tuple[str | None, int | None], str] = {}
+    emitted_refusal_text = ""
 
     async for raw_event in stream:
         event: Any = raw_event
@@ -388,6 +572,33 @@ async def consume_sdk_stream(
             content += delta_text
             if on_content_delta and delta_text:
                 await on_content_delta(delta_text)
+        elif event_type == "response.refusal.delta":
+            refusal_seen = True
+            delta_text = getattr(event, "delta", None)
+            if isinstance(delta_text, str) and delta_text:
+                key = _refusal_event_key(
+                    getattr(event, "item_id", None),
+                    getattr(event, "content_index", None),
+                )
+                refusal_deltas[key] = refusal_deltas.get(key, "") + delta_text
+                content += delta_text
+                emitted_refusal_text += delta_text
+                if on_content_delta:
+                    await on_content_delta(delta_text)
+        elif event_type == "response.refusal.done":
+            refusal_seen = True
+            refusal_text = getattr(event, "refusal", None)
+            key = _refusal_event_key(
+                getattr(event, "item_id", None),
+                getattr(event, "content_index", None),
+            )
+            streamed_text = refusal_deltas.pop(key, "")
+            if isinstance(refusal_text, str) and refusal_text:
+                remaining_text = _remaining_refusal_text(streamed_text, refusal_text)
+                content += remaining_text
+                emitted_refusal_text += remaining_text
+                if on_content_delta and remaining_text:
+                    await on_content_delta(remaining_text)
         elif event_type == "response.function_call_arguments.delta":
             call_id = getattr(event, "call_id", None)
             if call_id and call_id in tool_call_buffers:
@@ -416,6 +627,8 @@ async def consume_sdk_stream(
                     })
         elif event_type == "response.output_item.done":
             item = getattr(event, "item", None)
+            if capture is not None:
+                capture.record_output_item(getattr(event, "output_index", None), item)
             if item and getattr(item, "type", None) == "function_call":
                 call_id = getattr(item, "call_id", None)
                 if not call_id:
@@ -443,10 +656,31 @@ async def consume_sdk_stream(
                         arguments=args,
                     )
                 )
-        elif event_type == "response.completed":
+        elif event_type in {"response.completed", "response.incomplete"}:
             resp = getattr(event, "response", None)
-            status = getattr(resp, "status", None) if resp else None
-            finish_reason = map_finish_reason(status)
+            response_obj = _response_object(resp) or {}
+            if capture is not None:
+                capture.record_completed(resp)
+            finish_reason = _response_finish_reason(
+                resp,
+                fallback_status=event_type.removeprefix("response."),
+            )
+            terminal_output = response_obj.get("output")
+            if terminal_output is None:
+                terminal_output = getattr(resp, "output", None)
+            terminal_refusal, terminal_refusal_text = _extract_refusal_text_from_output(
+                terminal_output
+            )
+            if terminal_refusal:
+                refusal_seen = True
+                remaining_text = _remaining_refusal_text(
+                    emitted_refusal_text,
+                    terminal_refusal_text,
+                )
+                content += remaining_text
+                emitted_refusal_text += remaining_text
+                if on_content_delta and remaining_text:
+                    await on_content_delta(remaining_text)
             if resp:
                 usage_obj = getattr(resp, "usage", None)
                 if usage_obj:
@@ -466,4 +700,6 @@ async def consume_sdk_stream(
             detail = getattr(event, "error", None) or getattr(event, "message", None) or event
             raise RuntimeError(f"Response failed: {str(detail)[:500]}")
 
+    if refusal_seen:
+        finish_reason = "refusal"
     return content, tool_calls, finish_reason, usage, reasoning_content

nanobot/providers/openai_responses/state.py

@@ -0,0 +1,197 @@
+"""Opaque conversation state for Responses API item replay."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, cast
+
+from loguru import logger
+
+from nanobot.providers.base import ProviderConversationState
+from nanobot.providers.openai_responses.converters import convert_messages
+
+RESPONSES_STATE_KIND = "openai_responses"
+RESPONSES_STATE_VERSION = 1
+_ITEMS_KEY = "items"
+_CONTEXT_TOKENS_KEY = "context_tokens"
+_COMPACTION_ITEM_TYPES = frozenset({
+    "compaction",
+    "compaction_summary",
+    "context_compaction",
+})
+
+
+def responses_state_matches(
+    state: ProviderConversationState,
+    *,
+    provider: str,
+    model: str,
+) -> bool:
+    """Return whether *state* belongs to this exact Responses endpoint/model."""
+    return (
+        state.kind == RESPONSES_STATE_KIND
+        and state.version == RESPONSES_STATE_VERSION
+        and state.provider == provider
+        and state.model == model
+        and _state_items(state) is not None
+    )
+
+
+def prepare_responses_input(
+    messages: list[dict[str, Any]],
+    *,
+    state: ProviderConversationState | None,
+    provider: str,
+    model: str,
+) -> tuple[str, list[dict[str, Any]], bool]:
+    """Build a request from exact prior items plus only newly appended messages.
+
+    The full Chat transcript remains the source for the current instructions.
+    When no compatible state exists, it is converted normally as a safe
+    fallback.
+    """
+    instructions, fallback_items = convert_messages(messages)
+    if state is None or not responses_state_matches(
+        state,
+        provider=provider,
+        model=model,
+    ):
+        return instructions, fallback_items, False
+
+    prior_items = _state_items(state)
+    if prior_items is None:
+        return instructions, fallback_items, False
+
+    _, delta_items = convert_messages(state.pending_messages)
+    logger.debug(
+        "Replaying Responses state: prior_items={} pending_messages={}",
+        len(prior_items),
+        len(state.pending_messages),
+    )
+    return instructions, [*deepcopy(prior_items), *delta_items], True
+
+
+def build_responses_state(
+    *,
+    provider: str,
+    model: str,
+    input_items: list[dict[str, Any]],
+    output_items: list[dict[str, Any]],
+    usage: dict[str, int] | None = None,
+) -> ProviderConversationState:
+    """Create the canonical next state from request input and every output item."""
+    unpruned_items = [*input_items, *output_items]
+    items = _prune_before_latest_output_compaction(input_items, output_items)
+    if len(items) < len(unpruned_items):
+        logger.info(
+            "Installed Responses compaction: dropped_items={} retained_items={}",
+            len(unpruned_items) - len(items),
+            len(items),
+        )
+    payload: dict[str, Any] = {_ITEMS_KEY: deepcopy(items)}
+    context_tokens = _context_tokens_from_usage(usage)
+    if context_tokens > 0:
+        payload[_CONTEXT_TOKENS_KEY] = context_tokens
+    return ProviderConversationState(
+        kind=RESPONSES_STATE_KIND,
+        provider=provider,
+        model=model,
+        version=RESPONSES_STATE_VERSION,
+        payload=payload,
+    )
+
+
+def responses_state_items(
+    state: ProviderConversationState,
+) -> list[dict[str, Any]] | None:
+    """Return an isolated copy of canonical input items for tests/consumers."""
+    items = _state_items(state)
+    return deepcopy(items) if items is not None else None
+
+
+def responses_state_context_tokens(state: ProviderConversationState) -> int:
+    """Return the last server-reported active context size."""
+    value = state.payload.get(_CONTEXT_TOKENS_KEY)
+    if isinstance(value, bool) or not isinstance(value, int):
+        return 0
+    return max(0, value)
+
+
+def resolve_compact_threshold(
+    context_window_tokens: int | None,
+    max_output_tokens: int,
+) -> int | None:
+    """Derive Codex-compatible 90% compaction headroom for a model window."""
+    if context_window_tokens is None or context_window_tokens <= 0:
+        return None
+    ninety_percent = max(1, context_window_tokens * 9 // 10)
+    output_headroom = max(1, context_window_tokens - max(1, max_output_tokens))
+    return min(ninety_percent, output_headroom)
+
+
+def is_compaction_compatibility_error(exc: Exception) -> bool:
+    """Recognize endpoints that reject native Responses compaction fields."""
+    if getattr(exc, "compaction_unsupported", False) is True:
+        return True
+    response = getattr(exc, "response", None)
+    status_code = getattr(exc, "status_code", None)
+    if status_code is None and response is not None:
+        status_code = getattr(response, "status_code", None)
+    body = (
+        getattr(exc, "body", None)
+        or getattr(exc, "doc", None)
+        or getattr(response, "text", None)
+        or str(exc)
+    )
+    text = str(body).lower()
+    has_compaction_marker = any(
+        marker in text
+        for marker in ("context_management", "compact_threshold", "compaction_trigger")
+    )
+    if not has_compaction_marker:
+        return False
+    return isinstance(exc, TypeError) or status_code in {400, 404, 422}
+
+
+def _prune_before_latest_output_compaction(
+    input_items: list[dict[str, Any]],
+    output_items: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Drop old input only when this response emits a new compaction item.
+
+    A canonical compacted input may intentionally retain messages before its
+    compaction item. Those messages must survive ordinary subsequent responses.
+    """
+    latest = None
+    for index, item in enumerate(output_items):
+        if item.get("type") in _COMPACTION_ITEM_TYPES:
+            latest = index
+    if latest is None:
+        return [*input_items, *output_items]
+    return output_items[latest:]
+
+
+def _context_tokens_from_usage(usage: dict[str, int] | None) -> int:
+    if not usage:
+        return 0
+    prompt_tokens = usage.get("prompt_tokens", 0)
+    completion_tokens = usage.get("completion_tokens", 0)
+    total_tokens = usage.get("total_tokens", 0)
+    values = (prompt_tokens, completion_tokens, total_tokens)
+    if any(isinstance(value, bool) for value in values):
+        return 0
+    return max(0, total_tokens or prompt_tokens + completion_tokens)
+
+
+def _state_items(
+    state: ProviderConversationState,
+) -> list[dict[str, Any]] | None:
+    raw_items = state.payload.get(_ITEMS_KEY)
+    if not isinstance(raw_items, list):
+        return None
+    items: list[dict[str, Any]] = []
+    for raw in cast(list[object], raw_items):
+        if not isinstance(raw, dict):
+            return None
+        items.append(cast(dict[str, Any], raw))
+    return items

nanobot/resource_links.py

@@ -1,443 +0,0 @@
-"""Stable filesystem aliases for resources exposed to the agent.
-
-The aliases in this module are a compatibility view, not a new source of
-filesystem permissions.  Callers should keep canonical paths for persistence
-and authorization, and use a non-None alias only when presenting a shorter
-path to the model.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import stat
-import subprocess
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any, cast
-
-from filelock import FileLock, Timeout
-
-_LOCK_TIMEOUT_SECONDS = 2
-_JUNCTION_TIMEOUT_SECONDS = 2
-_NAMESPACE_MARKER = ".nanobot-resource-views.json"
-_VIEW_MARKER = ".nanobot-resource-view.json"
-_MARKER_VERSION = 1
-
-
-@dataclass(frozen=True, slots=True)
-class ResourceView:
-    """The healthy aliases in one immutable resource view."""
-
-    root: Path | None = None
-    agent: Path | None = None
-    media: Path | None = None
-    package: Path | None = None
-    warnings: tuple[str, ...] = ()
-
-
-def ensure_resource_view(
-    *,
-    data_dir: Path,
-    config_path: Path,
-    agent_workspace: Path,
-    package_root: Path | None = None,
-) -> ResourceView:
-    """Create, or validate, a stable resource view.
-
-    Expected filesystem failures are deliberately non-fatal.  A caller can
-    use each non-None alias and fall back to its canonical path for any alias
-    that could not be prepared.
-    """
-
-    warnings: list[str] = []
-    try:
-        canonical_data_dir = _canonical(data_dir)
-        canonical_config_path = _canonical(config_path)
-        canonical_agent_workspace = _canonical(agent_workspace)
-        canonical_package_root = _canonical(
-            package_root if package_root is not None else Path(__file__).parent
-        )
-    except (OSError, RuntimeError) as exc:
-        return ResourceView(warnings=(f"Could not resolve resource paths: {_error_text(exc)}",))
-
-    view_id = _resource_view_id(
-        config_path=canonical_config_path,
-        agent_workspace=canonical_agent_workspace,
-        package_root=canonical_package_root,
-    )
-    namespace_root = canonical_data_dir / "resources"
-    view_root = namespace_root / view_id
-    media_root = canonical_data_dir / "media"
-
-    for label, target in (
-        ("agent", canonical_agent_workspace),
-        ("package", canonical_package_root),
-    ):
-        if _paths_overlap(target, view_root):
-            warnings.append(
-                f"Resource view overlaps the {label} target and would make recursive "
-                f"traversal unsafe: {view_root}"
-            )
-            return ResourceView(warnings=tuple(warnings))
-
-    try:
-        canonical_data_dir.mkdir(parents=True, exist_ok=True)
-        if not canonical_data_dir.is_dir():
-            warnings.append(f"Resource data directory is not a directory: {canonical_data_dir}")
-            return ResourceView(warnings=tuple(warnings))
-    except OSError as exc:
-        warnings.append(
-            f"Could not prepare resource data directory {canonical_data_dir}: {_error_text(exc)}"
-        )
-        return ResourceView(warnings=tuple(warnings))
-
-    lock_path = canonical_data_dir / ".nanobot-resource-links.lock"
-    try:
-        with FileLock(str(lock_path), timeout=_LOCK_TIMEOUT_SECONDS):
-            return _ensure_resource_view_locked(
-                namespace_root=namespace_root,
-                view_root=view_root,
-                view_id=view_id,
-                config_path=canonical_config_path,
-                agent_workspace=canonical_agent_workspace,
-                media_root=media_root,
-                package_root=canonical_package_root,
-                warnings=warnings,
-            )
-    except Timeout:
-        warnings.append(f"Timed out waiting for resource view lock: {lock_path}")
-    except OSError as exc:
-        warnings.append(f"Could not lock resource view {lock_path}: {_error_text(exc)}")
-
-    return ResourceView(warnings=tuple(warnings))
-
-
-def _ensure_resource_view_locked(
-    *,
-    namespace_root: Path,
-    view_root: Path,
-    view_id: str,
-    config_path: Path,
-    agent_workspace: Path,
-    media_root: Path,
-    package_root: Path,
-    warnings: list[str],
-) -> ResourceView:
-    namespace_marker = {
-        "kind": "nanobot-resource-views",
-        "version": _MARKER_VERSION,
-    }
-    if not _ensure_owned_directory(
-        namespace_root,
-        marker_name=_NAMESPACE_MARKER,
-        marker_payload=namespace_marker,
-        label="resource namespace",
-        warnings=warnings,
-    ):
-        return ResourceView(warnings=tuple(warnings))
-
-    view_marker = {
-        "kind": "nanobot-resource-view",
-        "version": _MARKER_VERSION,
-        "view_id": view_id,
-        "config_path": _path_identity(config_path),
-        "targets": {
-            "agent": _path_identity(agent_workspace),
-            "media": _path_identity(media_root),
-            "package": _path_identity(package_root),
-        },
-    }
-    if not _ensure_owned_directory(
-        view_root,
-        marker_name=_VIEW_MARKER,
-        marker_payload=view_marker,
-        label="resource view",
-        warnings=warnings,
-    ):
-        return ResourceView(warnings=tuple(warnings))
-
-    try:
-        media_root.mkdir(parents=True, exist_ok=True)
-    except OSError as exc:
-        warnings.append(f"Could not prepare media target {media_root}: {_error_text(exc)}")
-
-    agent_alias = _ensure_alias(
-        view_root / "agent",
-        target=agent_workspace,
-        view_root=view_root,
-        label="agent",
-        warnings=warnings,
-    )
-    media_alias = _ensure_alias(
-        view_root / "media",
-        target=media_root,
-        view_root=view_root,
-        label="media",
-        warnings=warnings,
-    )
-    package_alias = _ensure_alias(
-        view_root / "package",
-        target=package_root,
-        view_root=view_root,
-        label="package",
-        warnings=warnings,
-    )
-    return ResourceView(
-        root=view_root,
-        agent=agent_alias,
-        media=media_alias,
-        package=package_alias,
-        warnings=tuple(warnings),
-    )
-
-
-def _resource_view_id(
-    *,
-    config_path: Path,
-    agent_workspace: Path,
-    package_root: Path,
-) -> str:
-    identities = (
-        _path_identity(config_path),
-        _path_identity(agent_workspace),
-        _path_identity(package_root),
-    )
-    digest = hashlib.sha256(
-        "\0".join(identities).encode("utf-8", errors="surrogatepass")
-    ).hexdigest()
-    return digest[:16]
-
-
-def _canonical(path: Path) -> Path:
-    return Path(path).expanduser().resolve(strict=False)
-
-
-def _path_identity(path: Path) -> str:
-    return os.path.normcase(os.path.normpath(str(path)))
-
-
-def _ensure_owned_directory(
-    directory: Path,
-    *,
-    marker_name: str,
-    marker_payload: dict[str, Any],
-    label: str,
-    warnings: list[str],
-) -> bool:
-    created = False
-    try:
-        if os.path.lexists(directory):
-            if _is_link_like(directory) or not directory.is_dir():
-                warnings.append(f"Unmanaged {label} collision at {directory}")
-                return False
-        else:
-            directory.mkdir()
-            created = True
-    except OSError as exc:
-        warnings.append(f"Could not prepare {label} {directory}: {_error_text(exc)}")
-        return False
-
-    marker_path = directory / marker_name
-    if not created:
-        actual = _read_marker(marker_path, label=label, warnings=warnings)
-        if actual is None:
-            return False
-        if actual != marker_payload:
-            warnings.append(f"Ownership marker does not match expected {label}: {marker_path}")
-            return False
-        return True
-
-    try:
-        _write_marker(marker_path, marker_payload)
-    except OSError as exc:
-        warnings.append(f"Could not write {label} marker {marker_path}: {_error_text(exc)}")
-        # Only an empty directory can be removed here.  Never recursively
-        # clean a path that another process may have populated.
-        try:
-            directory.rmdir()
-        except OSError:
-            pass
-        return False
-    return True
-
-
-def _read_marker(
-    marker_path: Path,
-    *,
-    label: str,
-    warnings: list[str],
-) -> dict[str, Any] | None:
-    try:
-        if not os.path.lexists(marker_path):
-            warnings.append(f"Unmanaged {label} at {marker_path.parent}: ownership marker missing")
-            return None
-        if _is_link_like(marker_path) or not stat.S_ISREG(marker_path.lstat().st_mode):
-            warnings.append(f"Invalid {label} ownership marker: {marker_path}")
-            return None
-        payload = json.loads(marker_path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
-        warnings.append(f"Could not read {label} marker {marker_path}: {_error_text(exc)}")
-        return None
-
-    if not isinstance(payload, dict):
-        warnings.append(f"Invalid {label} ownership marker: {marker_path}")
-        return None
-    return cast(dict[str, Any], payload)
-
-
-def _write_marker(marker_path: Path, payload: dict[str, Any]) -> None:
-    serialized = json.dumps(payload, indent=2, sort_keys=True) + "\n"
-    with marker_path.open("x", encoding="utf-8", newline="\n") as marker_file:
-        marker_file.write(serialized)
-        marker_file.flush()
-        os.fsync(marker_file.fileno())
-
-
-def _ensure_alias(
-    alias: Path,
-    *,
-    target: Path,
-    view_root: Path,
-    label: str,
-    warnings: list[str],
-) -> Path | None:
-    try:
-        if not target.is_dir():
-            warnings.append(f"Resource target for {label} is not a directory: {target}")
-            return None
-    except OSError as exc:
-        warnings.append(f"Could not inspect resource target for {label} {target}: {_error_text(exc)}")
-        return None
-
-    if _paths_overlap(target, view_root):
-        warnings.append(
-            f"Resource target for {label} overlaps its view and would create a cycle: {target}"
-        )
-        return None
-
-    try:
-        if os.path.lexists(alias):
-            if _is_directory_link(alias) and _link_points_to(alias, target):
-                return alias
-            warnings.append(f"Resource alias collision for {label} at {alias}")
-            return None
-
-        _create_directory_link(alias, target)
-        if not _is_directory_link(alias) or not _link_points_to(alias, target):
-            warnings.append(f"Created resource alias for {label} could not be verified: {alias}")
-            _remove_created_link(alias, label=label, warnings=warnings)
-            return None
-    except OSError as exc:
-        warnings.append(f"Could not create resource alias for {label} at {alias}: {_error_text(exc)}")
-        return None
-
-    return alias
-
-
-def _paths_overlap(first: Path, second: Path) -> bool:
-    return first.is_relative_to(second) or second.is_relative_to(first)
-
-
-def _is_link_like(path: Path) -> bool:
-    try:
-        if path.is_symlink():
-            return True
-        attributes = getattr(path.lstat(), "st_file_attributes", 0)
-        reparse_point = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
-        return bool(attributes & reparse_point)
-    except OSError:
-        return False
-
-
-def _is_directory_link(path: Path) -> bool:
-    if not _is_link_like(path):
-        return False
-    try:
-        return path.is_dir()
-    except OSError:
-        return False
-
-
-def _link_points_to(alias: Path, target: Path) -> bool:
-    try:
-        resolved_alias = alias.resolve(strict=True)
-        resolved_target = target.resolve(strict=True)
-    except (OSError, RuntimeError):
-        return False
-    return _path_identity(resolved_alias) == _path_identity(resolved_target)
-
-
-def _remove_created_link(alias: Path, *, label: str, warnings: list[str]) -> None:
-    """Remove only a link-like entry created during the current call."""
-
-    if not os.path.lexists(alias) or not _is_link_like(alias):
-        return
-    try:
-        alias.unlink()
-        return
-    except OSError:
-        # Directory junctions on Python 3.11 may require rmdir.  os.rmdir on a
-        # reparse point removes the junction itself and does not traverse it.
-        try:
-            os.rmdir(alias)
-            return
-        except OSError as exc:
-            warnings.append(
-                f"Could not remove unverified resource alias for {label} at "
-                f"{alias}: {_error_text(exc)}"
-            )
-
-
-def _create_directory_link(alias: Path, target: Path) -> None:
-    try:
-        alias.symlink_to(target, target_is_directory=True)
-        return
-    except OSError:
-        if not _is_windows():
-            raise
-    _create_windows_junction(alias, target)
-
-
-def _is_windows() -> bool:
-    return os.name == "nt"
-
-
-def _create_windows_junction(alias: Path, target: Path) -> None:
-    alias_text = str(alias)
-    target_text = str(target)
-    if any(character in alias_text + target_text for character in ('"', "\r", "\n")):
-        raise OSError("Path cannot be safely passed to the Windows junction command")
-
-    # Keep user-controlled paths out of the command string.  Expanding fixed,
-    # quoted environment variables also protects cmd metacharacters in paths.
-    command_env = os.environ.copy()
-    command_env["NANOBOT_RESOURCE_ALIAS"] = alias_text
-    command_env["NANOBOT_RESOURCE_TARGET"] = target_text
-    command = 'mklink /J "%NANOBOT_RESOURCE_ALIAS%" "%NANOBOT_RESOURCE_TARGET%"'
-    try:
-        completed = subprocess.run(
-            f"cmd.exe /d /v:off /c {command}",
-            capture_output=True,
-            text=True,
-            errors="replace",
-            env=command_env,
-            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
-            timeout=_JUNCTION_TIMEOUT_SECONDS,
-            check=False,
-        )
-    except subprocess.TimeoutExpired as exc:
-        raise OSError(
-            f"Timed out creating Windows junction after {_JUNCTION_TIMEOUT_SECONDS}s"
-        ) from exc
-    if completed.returncode == 0:
-        return
-
-    details = (completed.stderr or completed.stdout or "").strip()
-    suffix = f": {details}" if details else ""
-    raise OSError(f"mklink /J failed with exit code {completed.returncode}{suffix}")
-
-
-def _error_text(exc: BaseException) -> str:
-    return str(exc) or exc.__class__.__name__

nanobot/templates/agent/identity.md

@@ -1,16 +1,15 @@
 ## Runtime
 {{ runtime }}
 
-{% set resource_path = agent_resource_path | default(agent_workspace_path) %}
 ## Workspace
 Your current project workspace is at: {{ workspace_path }}
 {% if agent_workspace_path != workspace_path %}
 Nanobot's agent workspace is at: {{ agent_workspace_path }}
 {% endif %}
-- Agent profile: {{ resource_path }}/SOUL.md and {{ resource_path }}/USER.md (automatically managed by Dream — do not edit directly)
-- Long-term memory: {{ resource_path }}/memory/MEMORY.md (automatically managed by Dream — do not edit directly)
-- History log: {{ resource_path }}/memory/history.jsonl (append-only JSONL; prefer built-in `grep` for search).
-- Custom skills: {{ resource_path }}/skills/{% raw %}{skill-name}{% endraw %}/SKILL.md
+- Agent profile: {{ agent_workspace_path }}/SOUL.md and {{ agent_workspace_path }}/USER.md (automatically managed by Dream — do not edit directly)
+- Long-term memory: {{ agent_workspace_path }}/memory/MEMORY.md (automatically managed by Dream — do not edit directly)
+- History log: {{ agent_workspace_path }}/memory/history.jsonl (append-only JSONL; prefer built-in `grep` for search).
+- Custom skills: {{ agent_workspace_path }}/skills/{% raw %}{skill-name}{% endraw %}/SKILL.md
 
 {{ platform_policy }}
 {% if channel == 'telegram' or channel == 'qq' or channel == 'discord' %}

nanobot/templates/agent/resource_aliases.md

@@ -1,8 +0,0 @@
-## Resource Aliases
-
-These stable filesystem aliases are available:
-{% for label, path in aliases %}
-- {{ label }}: `{{ path }}`
-{% endfor %}
-
-Aliases are alternative path names only; they do not grant additional file or shell permissions. A sandboxed shell may not expose an alias even when a file tool can use it. Continue to use paths relative to the current project workspace for project files.

nanobot/templates/agent/subagent_system.md

@@ -11,10 +11,6 @@ Current project workspace: {{ workspace }}
 Nanobot's agent workspace: {{ agent_workspace }}
 {% endif %}
 History log: {{ history_log }}
-{% if resource_aliases %}
-
-{{ resource_aliases }}
-{% endif %}
 {% if skills_summary %}
 
 ## Skills

nanobot/utils/gitstore.py

@@ -176,7 +176,10 @@ class GitStore:
             )
             if cast(object, sha_bytes) is None:
                 return None
-            sha = sha_bytes.hex()[:8]
+            # porcelain.commit returns the id as a 40-char hex string that is
+            # already encoded to bytes; .hex() would encode those ASCII bytes
+            # again and produce an id no git command can resolve.
+            sha = sha_bytes.decode()[:8]
             logger.debug("Git auto-commit: {} ({})", sha, message)
             return sha
         except Exception as exc:
@@ -200,7 +203,7 @@ class GitStore:
                     return None
 
                 while sha:
-                    if sha.hex().startswith(short_sha):
+                    if sha.decode().startswith(short_sha):
                         return sha
                     commit_obj = repo[sha]
                     if commit_obj.type_name != b"commit":
@@ -280,7 +283,7 @@ class GitStore:
                     msg = commit.message.decode("utf-8", errors="replace").strip()
                     if message_prefix is None or msg.startswith(message_prefix):
                         entries.append(CommitInfo(
-                            sha=sha.hex()[:8],
+                            sha=sha.decode()[:8],
                             message=msg,
                             timestamp=ts,
                         ))
@@ -484,7 +487,7 @@ class GitStore:
                     with Repo(str(self._workspace)) as repo:
                         commit = cast("Commit", repo[full_sha])
                         parent = commit.parents[0] if commit.parents else None
-                    diff = self.diff_commits(parent.hex()[:8], c.sha) if parent else ""
+                    diff = self.diff_commits(parent.decode()[:8], c.sha) if parent else ""
                     return c, diff
             return None
         except Exception as exc:

nanobot/webui/media_api.py

@@ -7,6 +7,7 @@ import binascii
 import hashlib
 import hmac
 import mimetypes
+import os
 import re
 import shutil
 import uuid
@@ -126,17 +127,33 @@ def sign_or_stage_media_path(
     signed = sign_media_path(path, secret=secret, media_dir=media_dir)
     if signed is not None:
         return {"url": signed, "name": path.name}
+    staged_tmp: Path | None = None
     try:
-        if not path.is_file():
+        resolved = path.resolve(strict=True)
+        if not resolved.is_file():
             return None
+        source_stat = resolved.stat()
         target_dir = media_dir("websocket")
         safe_name = safe_filename(path.name) or "attachment"
-        staged = target_dir / f"{uuid.uuid4().hex[:12]}-{safe_name}"
-        shutil.copyfile(path, staged)
+        source_version = "\0".join((
+            os.path.normcase(str(resolved)),
+            str(source_stat.st_size),
+            str(source_stat.st_mtime_ns),
+            str(source_stat.st_ctime_ns),
+        ))
+        source_digest = hashlib.sha256(source_version.encode("utf-8")).hexdigest()[:20]
+        staged = target_dir / f"{source_digest}-{safe_name}"
+        if not staged.is_file() or staged.stat().st_size != source_stat.st_size:
+            staged_tmp = target_dir / f".{source_digest}-{uuid.uuid4().hex}.tmp"
+            shutil.copyfile(resolved, staged_tmp)
+            staged_tmp.replace(staged)
     except OSError as exc:
         if logger is not None:
             logger.warning("failed to stage outbound media {}: {}", path, exc)
         return None
+    finally:
+        if staged_tmp is not None:
+            staged_tmp.unlink(missing_ok=True)
     signed = sign_media_path(staged, secret=secret, media_dir=media_dir)
     if signed is None:
         return None

nanobot/webui/metadata.py

@@ -1,5 +1,6 @@
 """Shared WebUI metadata keys."""
 
 WEBUI_TURN_METADATA_KEY = "webui_turn_id"
+WEBUI_SYSTEM_COMMAND_TURN_PREFIX = "webui-system:"
 WEBSOCKET_TURN_OWNER_METADATA_KEY = "_websocket_turn_owner"
 WEBUI_MESSAGE_SOURCE_METADATA_KEY = "_webui_message_source"

nanobot/webui/session_list_index.py

@@ -18,10 +18,12 @@ from loguru import logger
 from nanobot.config.paths import get_webui_dir
 from nanobot.session.history_visibility import is_hidden_history_message
 from nanobot.session.manager import (
+    _PROVIDER_STATE_RECORD_TYPE,  # pyright: ignore[reportPrivateUsage]
     _SESSION_LIST_PREVIEW_MAX_CHARS,  # pyright: ignore[reportPrivateUsage]
     _SESSION_LIST_PREVIEW_MAX_RECORDS,  # pyright: ignore[reportPrivateUsage]
     Session,
     SessionManager,
+    _is_provider_state_record_line,  # pyright: ignore[reportPrivateUsage]
     _message_preview_text,  # pyright: ignore[reportPrivateUsage]
     _metadata_title,  # pyright: ignore[reportPrivateUsage]
 )
@@ -298,7 +300,11 @@ def _scan_session_row(session_manager: SessionManager, path: Path) -> dict[str,
             for line in f:
                 if not line.strip():
                     continue
+                if _is_provider_state_record_line(line):
+                    continue
                 item = json.loads(line)
+                if item.get("_type") == _PROVIDER_STATE_RECORD_TYPE:
+                    continue
                 timestamp = _visible_message_timestamp(item)
                 if timestamp is not None:
                     visible_message_at = _latest_updated_at(visible_message_at, timestamp)

nanobot/webui/settings_api.py

@@ -131,10 +131,10 @@ _IMAGE_GENERATION_ASPECT_RATIOS = {
 }
 _CONTEXT_WINDOW_TOKEN_OPTIONS = {65_536, 200_000, 262_144, 500_000, 1_048_576}
 _OAUTH_PROXY_PROVIDERS = {"openai_codex", "xai_grok"}
-_XAI_WEBUI_OAUTH_TIMEOUT_S = 600
-_XAI_WEBUI_OAUTH_MAX_FLOWS = 8
-_xai_webui_oauth_flows: dict[str, Any] = {}
-_xai_webui_oauth_flows_lock = threading.Lock()
+_WEBUI_OAUTH_TIMEOUT_S = 600
+_WEBUI_OAUTH_MAX_FLOWS = 8
+_webui_oauth_flows: dict[str, tuple[str, Any]] = {}
+_webui_oauth_flows_lock = threading.Lock()
 _MODEL_CONFIGURATION_SLUG_RE = re.compile(r"[^a-z0-9_-]+")
 _ENV_REF_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
 
@@ -1810,7 +1810,7 @@ def login_oauth_provider(query: QueryParams) -> dict[str, Any]:
 
     if spec.name == "openai_codex":
         try:
-            from oauth_cli_kit import get_token, login_oauth_interactive
+            from nanobot.providers.openai_codex_oauth import start_openai_codex_oauth_login
         except ImportError:
             raise WebUISettingsError(
                 "oauth_cli_kit not installed. Run: pip install oauth-cli-kit", status=500
@@ -1820,19 +1820,30 @@ def login_oauth_provider(query: QueryParams) -> dict[str, Any]:
             proxy = resolve_config_env_vars(load_config()).providers.openai_codex.proxy or None
         except ValueError as e:
             raise WebUISettingsError(str(e), status=400) from e
-        token = None
-        with suppress(Exception):
-            token = get_token(proxy=proxy)
-        if not (token and token.access):
-            messages: list[str] = []
-            token = login_oauth_interactive(
-                print_fn=lambda message: messages.append(str(message)),
-                prompt_fn=lambda _prompt: "",
+        remote_browser_value = _query_first(query, "remote_browser")
+        remote_browser = (
+            _parse_bool(remote_browser_value, "remote_browser")
+            if remote_browser_value is not None
+            else False
+        )
+        try:
+            flow = start_openai_codex_oauth_login(
                 proxy=proxy,
+                timeout_s=_WEBUI_OAUTH_TIMEOUT_S,
+                open_browser=not remote_browser,
             )
-        if not (token and token.access):
-            raise WebUISettingsError("OAuth login failed", status=401)
-        return settings_payload()
+        except Exception as e:
+            raise WebUISettingsError(f"OpenAI Codex OAuth login failed: {e}", status=502) from e
+        flow_id = secrets.token_urlsafe(24)
+        _register_webui_oauth_flow(spec.name, flow_id, flow)
+        return {
+            "status": "authorization_required",
+            "provider": spec.name,
+            "flow_id": flow_id,
+            "authorization_url": flow.authorization_url,
+            "expires_in": flow.remaining_seconds,
+            "completion_input": "callback_url",
+        }
 
     if spec.name == "github_copilot":
         try:
@@ -1862,18 +1873,19 @@ def login_oauth_provider(query: QueryParams) -> dict[str, Any]:
         try:
             flow = start_xai_oauth_login(
                 proxy=proxy,
-                timeout_s=_XAI_WEBUI_OAUTH_TIMEOUT_S,
+                timeout_s=_WEBUI_OAUTH_TIMEOUT_S,
             )
         except Exception as e:
             raise WebUISettingsError(f"xAI OAuth login failed: {e}", status=502) from e
         flow_id = secrets.token_urlsafe(24)
-        _register_xai_webui_oauth_flow(flow_id, flow)
+        _register_webui_oauth_flow(spec.name, flow_id, flow)
         return {
             "status": "authorization_required",
             "provider": spec.name,
             "flow_id": flow_id,
             "authorization_url": flow.authorization_url,
             "expires_in": flow.remaining_seconds,
+            "completion_input": "authorization_code",
         }
 
     raise WebUISettingsError("OAuth login is not supported for this provider")
@@ -1881,34 +1893,47 @@ def login_oauth_provider(query: QueryParams) -> dict[str, Any]:
 
 def complete_oauth_provider(
     query: QueryParams,
-    authorization_code: str | None = None,
+    authorization_response: str | None = None,
 ) -> dict[str, Any]:
     provider_name = (_query_first(query, "provider") or "").strip()
     flow_id = (_query_first(query, "flow_id") or "").strip()
     spec = find_by_name(provider_name)
-    if spec is None or spec.name != "xai_grok":
+    if spec is None or spec.name not in {"openai_codex", "xai_grok"}:
         raise WebUISettingsError("OAuth completion is not supported for this provider")
     if not flow_id:
         raise WebUISettingsError("flow_id is required")
 
-    flow = _get_xai_webui_oauth_flow(flow_id)
+    flow = _get_webui_oauth_flow(spec.name, flow_id)
     if flow is None:
-        raise WebUISettingsError("xAI sign-in expired. Start again.", status=410)
-
-    from nanobot.providers.xai_oauth import complete_xai_oauth_login
+        raise WebUISettingsError(f"{spec.label} sign-in expired. Start again.", status=410)
 
     try:
-        token = complete_xai_oauth_login(flow, authorization_code)
+        if spec.name == "openai_codex":
+            from nanobot.providers.openai_codex_oauth import (
+                OpenAICodexOAuthInputError,
+                complete_openai_codex_oauth_login,
+            )
+
+            try:
+                token = complete_openai_codex_oauth_login(flow, authorization_response)
+            except OpenAICodexOAuthInputError as e:
+                raise WebUISettingsError(str(e), status=400) from e
+        else:
+            from nanobot.providers.xai_oauth import complete_xai_oauth_login
+
+            token = complete_xai_oauth_login(flow, authorization_response)
+    except WebUISettingsError:
+        raise
     except Exception as e:
-        _remove_xai_webui_oauth_flow(flow_id, flow)
-        raise WebUISettingsError(f"xAI OAuth login failed: {e}", status=502) from e
+        _remove_webui_oauth_flow(spec.name, flow_id, flow)
+        raise WebUISettingsError(f"{spec.label} OAuth login failed: {e}", status=502) from e
     if token is None:
         return {
             "status": "pending",
             "provider": spec.name,
             "flow_id": flow_id,
         }
-    _remove_xai_webui_oauth_flow(flow_id, flow, cancel=False)
+    _remove_webui_oauth_flow(spec.name, flow_id, flow, cancel=False)
     if not token.access:
         raise WebUISettingsError("OAuth login failed", status=401)
     return settings_payload()
@@ -1930,6 +1955,7 @@ def logout_oauth_provider(query: QueryParams) -> dict[str, Any]:
             raise WebUISettingsError(
                 "oauth_cli_kit not installed. Run: pip install oauth-cli-kit", status=500
             ) from None
+        _clear_webui_oauth_flows(spec.name)
         token_path = FileTokenStorage(token_filename=OPENAI_CODEX_PROVIDER.token_filename).get_token_path()
     elif spec.name == "github_copilot":
         try:
@@ -1942,7 +1968,7 @@ def logout_oauth_provider(query: QueryParams) -> dict[str, Any]:
     elif spec.name == "xai_grok":
         from nanobot.providers.xai_oauth import logout_xai_oauth
 
-        _clear_xai_webui_oauth_flows()
+        _clear_webui_oauth_flows(spec.name)
         logout_xai_oauth()
         return settings_payload()
     else:
@@ -1954,47 +1980,60 @@ def logout_oauth_provider(query: QueryParams) -> dict[str, Any]:
     return settings_payload()
 
 
-def _register_xai_webui_oauth_flow(flow_id: str, flow: Any) -> None:
+def _register_webui_oauth_flow(provider_name: str, flow_id: str, flow: Any) -> None:
     discarded: list[Any] = []
-    with _xai_webui_oauth_flows_lock:
-        for existing_id, existing in list(_xai_webui_oauth_flows.items()):
+    with _webui_oauth_flows_lock:
+        for existing_id, (_provider_name, existing) in list(_webui_oauth_flows.items()):
             if existing.expired:
-                discarded.append(_xai_webui_oauth_flows.pop(existing_id))
-        while len(_xai_webui_oauth_flows) >= _XAI_WEBUI_OAUTH_MAX_FLOWS:
-            oldest_id = next(iter(_xai_webui_oauth_flows))
-            discarded.append(_xai_webui_oauth_flows.pop(oldest_id))
-        _xai_webui_oauth_flows[flow_id] = flow
+                discarded.append(_webui_oauth_flows.pop(existing_id)[1])
+        while len(_webui_oauth_flows) >= _WEBUI_OAUTH_MAX_FLOWS:
+            oldest_id = next(iter(_webui_oauth_flows))
+            discarded.append(_webui_oauth_flows.pop(oldest_id)[1])
+        _webui_oauth_flows[flow_id] = (provider_name, flow)
     for existing in discarded:
         existing.cancel()
 
 
-def _get_xai_webui_oauth_flow(flow_id: str) -> Any | None:
-    with _xai_webui_oauth_flows_lock:
-        flow = _xai_webui_oauth_flows.get(flow_id)
-        if flow is None or not flow.expired:
+def _get_webui_oauth_flow(provider_name: str, flow_id: str) -> Any | None:
+    with _webui_oauth_flows_lock:
+        registered = _webui_oauth_flows.get(flow_id)
+        if registered is None or registered[0] != provider_name:
+            return None
+        flow = registered[1]
+        if not flow.expired:
             return flow
-        _xai_webui_oauth_flows.pop(flow_id, None)
+        _webui_oauth_flows.pop(flow_id, None)
     flow.cancel()
     return None
 
 
-def _remove_xai_webui_oauth_flow(
+def _remove_webui_oauth_flow(
+    provider_name: str,
     flow_id: str,
     flow: Any,
     *,
     cancel: bool = True,
 ) -> None:
-    with _xai_webui_oauth_flows_lock:
-        if _xai_webui_oauth_flows.get(flow_id) is flow:
-            _xai_webui_oauth_flows.pop(flow_id)
+    with _webui_oauth_flows_lock:
+        registered = _webui_oauth_flows.get(flow_id)
+        if (
+            registered is not None
+            and registered[0] == provider_name
+            and registered[1] is flow
+        ):
+            _webui_oauth_flows.pop(flow_id)
     if cancel:
         flow.cancel()
 
 
-def _clear_xai_webui_oauth_flows() -> None:
-    with _xai_webui_oauth_flows_lock:
-        flows = list(_xai_webui_oauth_flows.values())
-        _xai_webui_oauth_flows.clear()
+def _clear_webui_oauth_flows(provider_name: str) -> None:
+    with _webui_oauth_flows_lock:
+        flow_ids = [
+            flow_id
+            for flow_id, (registered_provider, _flow) in _webui_oauth_flows.items()
+            if registered_provider == provider_name
+        ]
+        flows = [_webui_oauth_flows.pop(flow_id)[1] for flow_id in flow_ids]
     for flow in flows:
         flow.cancel()
 

nanobot/webui/settings_routes.py

@@ -85,7 +85,8 @@ _CHANNEL_VALUES_HEADER_MAX_BYTES = 64 * 1024
 _API_SERVICE_VALUES_HEADER = "X-Nanobot-API-Service-Values"
 _API_SERVICE_VALUES_HEADER_MAX_BYTES = 8 * 1024
 _OAUTH_CODE_HEADER = "X-Nanobot-OAuth-Code"
-_OAUTH_CODE_HEADER_MAX_BYTES = 8 * 1024
+_OAUTH_CALLBACK_HEADER = "X-Nanobot-OAuth-Callback"
+_OAUTH_RESPONSE_HEADER_MAX_BYTES = 8 * 1024
 
 _SKIP_FIELD = object()
 _CHANNEL_CONNECT_ACTIONS = frozenset({"start", "poll", "cancel"})
@@ -471,16 +472,22 @@ class WebUISettingsRouter:
             if action == "login":
                 payload = await asyncio.to_thread(login_oauth_provider, query)
             elif action == "complete":
-                authorization_code = case_insensitive_header(
+                authorization_response = case_insensitive_header(
+                    request.headers,
+                    _OAUTH_CALLBACK_HEADER,
+                ) or case_insensitive_header(
                     request.headers,
                     _OAUTH_CODE_HEADER,
                 )
-                if len(authorization_code.encode("utf-8")) > _OAUTH_CODE_HEADER_MAX_BYTES:
-                    raise WebUISettingsError("OAuth authorization code is too large")
+                if (
+                    len(authorization_response.encode("utf-8"))
+                    > _OAUTH_RESPONSE_HEADER_MAX_BYTES
+                ):
+                    raise WebUISettingsError("OAuth authorization response is too large")
                 payload = await asyncio.to_thread(
                     complete_oauth_provider,
                     query,
-                    authorization_code or None,
+                    authorization_response or None,
                 )
             else:
                 payload = await asyncio.to_thread(logout_oauth_provider, query)

nanobot/webui/token_usage.py

@@ -159,6 +159,13 @@ def normalize_token_usage_state(raw: Any) -> dict[str, Any]:
         if not isinstance(date, str) or len(date) != 10 or not isinstance(row_value, dict):
             continue
         row = cast(dict[str, Any], row_value)
+        try:
+            datetime.fromisoformat(date)
+        except ValueError:
+            # A hand-edited or foreign day key that is not a real date would
+            # otherwise reach token_usage_payload's date parsing and fail every
+            # settings request; drop it like any other malformed row.
+            continue
         normalized = _normalize_usage_row(row)
         if normalized["total_tokens"] <= 0 and normalized["requests"] <= 0:
             continue

nanobot/webui/transcript.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import base64
 import binascii
+import hashlib
 import json
 import os
 import re
@@ -34,6 +35,7 @@ _TRANSCRIPT_SEGMENT_RE = re.compile(r"^\d{6}\.jsonl$")
 _DEFAULT_TRANSCRIPT_PAGE_LIMIT = 160
 _MAX_TRANSCRIPT_PAGE_LIMIT = 1000
 _WEBUI_TURN_ID_RE = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
+_WEBUI_REPLAY_IDENTITY_KEY = "_webui_replay_identity"
 _MARKDOWN_LOCAL_IMAGE_RE = re.compile(
     r"!\[([^\]]*)\]\((<[^>]+>|[^)\s]+)(\s+(?:\"[^\"]*\"|'[^']*'))?\)"
 )
@@ -194,6 +196,20 @@ def _flatten_turns(turns: list[list[dict[str, Any]]]) -> list[dict[str, Any]]:
     return [record for turn in turns for record in turn]
 
 
+def _records_with_replay_identity(
+    records: list[dict[str, Any]],
+    *,
+    turn_ordinal: int,
+) -> list[dict[str, Any]]:
+    return [
+        {
+            **record,
+            _WEBUI_REPLAY_IDENTITY_KEY: f"turn:{turn_ordinal}:record:{record_index}",
+        }
+        for record_index, record in enumerate(records)
+    ]
+
+
 def _write_records_to_path(path: Path, rows: list[dict[str, Any]]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp_path = path.with_suffix(path.suffix + ".tmp")
@@ -543,7 +559,14 @@ def _select_transcript_page(
             break
 
     selected_chronological = list(reversed(selected))
-    lines = [record for ref in selected_chronological for record in ref.records]
+    lines = [
+        record
+        for ref in selected_chronological
+        for record in _records_with_replay_identity(
+            ref.records,
+            turn_ordinal=ref.ordinal,
+        )
+    ]
     if not selected_chronological:
         return [], {
             "before_cursor": None,
@@ -1030,6 +1053,74 @@ def _split_transcript_turns(lines: list[dict[str, Any]]) -> list[list[dict[str,
     return turns
 
 
+def _annotate_replay_identities(lines: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        record
+        for turn_ordinal, turn in enumerate(_split_transcript_turns(lines))
+        for record in _records_with_replay_identity(
+            turn,
+            turn_ordinal=turn_ordinal,
+        )
+    ]
+
+
+def _stable_record_digest(record: dict[str, Any]) -> str:
+    persisted = {
+        key: value
+        for key, value in record.items()
+        if key != _WEBUI_REPLAY_IDENTITY_KEY
+    }
+    raw = json.dumps(
+        persisted,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+        default=str,
+    )
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]
+
+
+def _ensure_replay_identities(lines: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Give backfilled/recovered rows a stable identity beside persisted rows."""
+    annotated: list[dict[str, Any]] = []
+    for fallback_turn_index, turn in enumerate(_split_transcript_turns(lines)):
+        anchor = next(
+            (
+                value
+                for record in turn
+                if isinstance(
+                    value := record.get(_WEBUI_REPLAY_IDENTITY_KEY),
+                    str,
+                )
+                and value
+            ),
+            None,
+        )
+        if anchor and ":record:" in anchor:
+            turn_identity = anchor.rsplit(":record:", 1)[0]
+        else:
+            turn_digest = hashlib.sha256(
+                "\n".join(_stable_record_digest(record) for record in turn).encode("ascii")
+            ).hexdigest()[:16]
+            turn_identity = f"legacy:{fallback_turn_index}:{turn_digest}"
+        synthetic_occurrences: dict[str, int] = {}
+        for record in turn:
+            identity = record.get(_WEBUI_REPLAY_IDENTITY_KEY)
+            if isinstance(identity, str) and identity:
+                annotated.append(record)
+                continue
+            digest = _stable_record_digest(record)
+            occurrence = synthetic_occurrences.get(digest, 0)
+            synthetic_occurrences[digest] = occurrence + 1
+            annotated.append({
+                **record,
+                _WEBUI_REPLAY_IDENTITY_KEY: (
+                    f"{turn_identity}:synthetic:{digest}:{occurrence}"
+                ),
+            })
+    return annotated
+
+
 def _transcript_turn_signature(records: list[dict[str, Any]]) -> tuple[str, ...]:
     texts: list[str] = []
     for message in replay_transcript_to_ui_messages(records):
@@ -1464,9 +1555,18 @@ def replay_transcript_to_ui_messages(
     _ts_base = _now_ms()
     closed_turn_ids: set[str] = set()
     replay_turn_aliases: dict[str, str] = {}
+    generated_id_occurrences: dict[str, int] = {}
 
     def _new_id(prefix: str, idx: int) -> str:
-        return f"{prefix}-{idx}-{uuid.uuid4().hex[:8]}"
+        record = lines[idx] if 0 <= idx < len(lines) else {}
+        identity = record.get(_WEBUI_REPLAY_IDENTITY_KEY)
+        if not isinstance(identity, str) or not identity:
+            identity = f"direct:{idx}:{_stable_record_digest(record)}"
+        digest = hashlib.sha256(f"{prefix}\0{identity}".encode("utf-8")).hexdigest()[:16]
+        base = f"{prefix}-{digest}"
+        occurrence = generated_id_occurrences.get(base, 0)
+        generated_id_occurrences[base] = occurrence + 1
+        return base if occurrence == 0 else f"{base}-{occurrence}"
 
     def _created_at_ms(rec: dict[str, Any], idx: int) -> int:
         created_at_ms = _valid_created_at_ms(rec.get("created_at_ms"))
@@ -1926,6 +2026,7 @@ def replay_transcript_to_ui_messages(
                 continue
             close_activity_for_answer()
             turn_fields = _turn_fields(rec, "answer")
+            source_fields = _source_fields(rec)
             adopted = find_active_placeholder(messages, turn_fields) if buffer_message_id is None else None
             if buffer_message_id is None:
                 if adopted:
@@ -1938,7 +2039,8 @@ def replay_transcript_to_ui_messages(
                             "role": "assistant",
                             "content": "",
                             "isStreaming": True,
-                            **_turn_fields(rec, "answer"),
+                            **turn_fields,
+                            **source_fields,
                             "createdAt": _created_at_ms(rec, idx),
                         },
                     )
@@ -1950,7 +2052,8 @@ def replay_transcript_to_ui_messages(
                         **m,
                         "content": combined,
                         "isStreaming": True,
-                        **_turn_fields(rec, "answer"),
+                        **turn_fields,
+                        **source_fields,
                     }
                     break
             continue
@@ -1962,6 +2065,8 @@ def replay_transcript_to_ui_messages(
                 continue
             merge_next = rec.get("resuming") is True and rec.get("merge_next") is True
             final_text = rec.get("text")
+            turn_fields = _turn_fields(rec, "answer")
+            source_fields = _source_fields(rec)
             if isinstance(final_text, str):
                 if buffer_message_id is None:
                     buffer_message_id = _new_id("buf", idx)
@@ -1971,7 +2076,8 @@ def replay_transcript_to_ui_messages(
                             "role": "assistant",
                             "content": final_text,
                             "isStreaming": True,
-                            **_turn_fields(rec, "answer"),
+                            **turn_fields,
+                            **source_fields,
                             "createdAt": _created_at_ms(rec, idx),
                         },
                     )
@@ -1982,11 +2088,21 @@ def replay_transcript_to_ui_messages(
                                 **m,
                                 "content": final_text,
                                 "isStreaming": True,
-                                **_turn_fields(rec, "answer"),
+                                **turn_fields,
+                                **source_fields,
                             }
                             break
                 if merge_next:
                     buffer_parts = [final_text]
+            elif source_fields and buffer_message_id is not None:
+                for i, m in enumerate(messages):
+                    if m.get("id") == buffer_message_id:
+                        messages[i] = {
+                            **m,
+                            **turn_fields,
+                            **source_fields,
+                        }
+                        break
             if not merge_next:
                 buffer_message_id = None
                 buffer_parts = []
@@ -2255,7 +2371,7 @@ def build_webui_thread_response(
     if paginated:
         lines, page = _select_transcript_page(session_key, limit=limit, before=before)
     else:
-        lines = read_transcript_lines(session_key)
+        lines = _annotate_replay_identities(read_transcript_lines(session_key))
     if not lines and active_turn_started_at is None:
         return None
     lines = inject_missing_user_events_from_session(session_key, lines, session_messages)
@@ -2264,6 +2380,7 @@ def build_webui_thread_response(
         session_messages,
         session_key=session_key,
     )
+    lines = _ensure_replay_identities(lines)
     fork_boundary = fork_boundary_message_count(lines)
     msgs = replay_transcript_to_ui_messages(
         lines,

tests/agent/test_auto_compact.py

@@ -80,7 +80,6 @@ def _make_fake_compact(
     track_archived: list | None = None,
     track_count: bool = False,
 ):
-    """Return a fake compact_idle_session that mirrors the real method's session mutation."""
     from nanobot.session.manager import Session as _Session
 
     state = {"count": 0}
@@ -106,21 +105,20 @@ def _make_fake_compact(
             max_suffix,
             extend_to_user=True,
         )
-        kept = probe.messages
-        archive_msgs = result.dropped[result.already_consolidated_count:]
+        visible_suffix = probe.messages
+        archive_msgs = result.dropped
 
-        if not archive_msgs and not kept:
+        if not archive_msgs:
             loop.sessions.save(session)
             return ""
 
         last_active = session.updated_at
         s = summary
-        if archive_msgs:
-            if on_archive:
-                result = on_archive(archive_msgs)
-                s = result if isinstance(result, str) else summary
-            if track_archived is not None:
-                track_archived.extend(archive_msgs)
+        if on_archive:
+            result = on_archive(archive_msgs)
+            s = result if isinstance(result, str) else summary
+        if track_archived is not None:
+            track_archived.extend(archive_msgs)
 
         if s and s != "(nothing)":
             session.metadata["_last_summary"] = {
@@ -128,8 +126,7 @@ def _make_fake_compact(
                 "last_active": last_active.isoformat(),
             }
 
-        session.messages = kept
-        session.last_consolidated = 0
+        session.last_consolidated = len(session.messages) - len(visible_suffix)
         loop.sessions.save(session)
         return s
 
@@ -359,7 +356,7 @@ class TestAutoCompact:
         loop.sessions.save(s2)
 
         loop.consolidator.compact_idle_session = _make_fake_compact(loop)
-        loop.auto_compact.check_expired(loop._schedule_background, loop.runtime_for_session)
+        loop.auto_compact.check_expired(loop.schedule_background, loop.runtime_for_session)
         await _drain_background_tasks(loop)
 
         active_after = loop.sessions.get_or_create("cli:active")
@@ -368,8 +365,7 @@ class TestAutoCompact:
         await loop.close_mcp()
 
     @pytest.mark.asyncio
-    async def test_auto_compact_archives_prefix_and_keeps_recent_suffix(self, tmp_path):
-        """_archive should summarize the old prefix and keep a recent legal suffix."""
+    async def test_auto_compact_archives_prefix_without_deleting_history(self, tmp_path):
         loop = _make_loop(tmp_path, session_ttl_minutes=15)
         session = loop.sessions.get_or_create("cli:test")
         _add_turns(session, 6)
@@ -384,9 +380,12 @@ class TestAutoCompact:
 
         assert len(archived_messages) == 4
         session_after = loop.sessions.get_or_create("cli:test")
-        assert len(session_after.messages) == loop.auto_compact._RECENT_SUFFIX_MESSAGES
-        assert session_after.messages[0]["content"] == "msg user 2"
-        assert session_after.messages[-1]["content"] == "msg assistant 5"
+        assert len(session_after.messages) == 12
+        assert session_after.messages[0]["content"] == "msg user 0"
+        visible = session_after.get_history(max_messages=12)
+        assert len(visible) == loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        assert visible[0]["content"] == "msg user 2"
+        assert visible[-1]["content"] == "msg assistant 5"
         await loop.close_mcp()
 
     @pytest.mark.asyncio
@@ -403,17 +402,19 @@ class TestAutoCompact:
         await loop.auto_compact._archive("cli:test", runtime=loop.llm_runtime())
 
         session_after = loop.sessions.get_or_create("cli:test")
-        assert len(session_after.messages) > loop.auto_compact._RECENT_SUFFIX_MESSAGES
-        assert session_after.messages[0]["content"] == "record this"
-        assert session_after.messages[-1]["content"] == "done"
+        assert session_after.messages[0]["content"] == "old user 0"
+        visible = session_after.get_history(max_messages=len(session_after.messages))
+        assert len(visible) > loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        assert visible[0]["content"] == "record this"
+        assert visible[-1]["content"] == "done"
         tool_results = {
             m.get("tool_call_id")
-            for m in session_after.messages
+            for m in visible
             if m.get("role") == "tool"
         }
         assert all(
             tc["id"] in tool_results
-            for m in session_after.messages
+            for m in visible
             for tc in (m.get("tool_calls") or [])
         )
         await loop.close_mcp()
@@ -436,7 +437,10 @@ class TestAutoCompact:
         assert entry is not None
         assert entry[0] == "User said hello."
         session_after = loop.sessions.get_or_create("cli:test")
-        assert len(session_after.messages) == loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        assert len(session_after.messages) == 12
+        assert len(session_after.get_history(max_messages=12)) == (
+            loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        )
         await loop.close_mcp()
 
     @pytest.mark.asyncio
@@ -474,11 +478,10 @@ class TestAutoCompact:
 
 
 class TestAutoCompactIdleDetection:
-    """Test idle detection triggers auto-new in _process_message."""
+    """Idle detection tests."""
 
     @pytest.mark.asyncio
     async def test_no_auto_compact_when_ttl_disabled(self, tmp_path):
-        """No auto-new should happen when TTL is 0 (disabled)."""
         loop = _make_loop(tmp_path, session_ttl_minutes=0)
         session = loop.sessions.get_or_create("cli:test")
         session.add_message("user", "old message")
@@ -494,7 +497,6 @@ class TestAutoCompactIdleDetection:
 
     @pytest.mark.asyncio
     async def test_auto_compact_triggers_on_idle(self, tmp_path):
-        """Proactive auto-new archives expired session; _process_message reloads it."""
         loop = _make_loop(tmp_path, session_ttl_minutes=15)
         session = loop.sessions.get_or_create("cli:test")
         _add_turns(session, 6, prefix="old")
@@ -514,13 +516,16 @@ class TestAutoCompactIdleDetection:
 
         session_after = loop.sessions.get_or_create("cli:test")
         assert len(archived_messages) == 4
-        assert not any(m["content"] == "old user 0" for m in session_after.messages)
+        assert any(m["content"] == "old user 0" for m in session_after.messages)
+        assert not any(
+            m["content"] == "old user 0"
+            for m in session_after.get_history(max_messages=len(session_after.messages))
+        )
         assert any(m["content"] == "new msg" for m in session_after.messages)
         await loop.close_mcp()
 
     @pytest.mark.asyncio
     async def test_no_auto_compact_when_active(self, tmp_path):
-        """No auto-new should happen when session is recently active."""
         loop = _make_loop(tmp_path, session_ttl_minutes=15)
         session = loop.sessions.get_or_create("cli:test")
         session.add_message("user", "recent message")
@@ -558,7 +563,6 @@ class TestAutoCompactIdleDetection:
 
     @pytest.mark.asyncio
     async def test_auto_compact_with_slash_new(self, tmp_path):
-        """Auto-new fires before /new dispatches; session is cleared twice but idempotent."""
         loop = _make_loop(tmp_path, session_ttl_minutes=15)
         session = loop.sessions.get_or_create("cli:test")
         for i in range(4):
@@ -576,7 +580,6 @@ class TestAutoCompactIdleDetection:
         assert "new session started" in response.content.lower()
 
         session_after = loop.sessions.get_or_create("cli:test")
-        # Session is empty (auto-new archived and cleared, /new cleared again)
         assert len(session_after.messages) == 0
         await loop.close_mcp()
 
@@ -617,11 +620,10 @@ class TestAutoCompactIdleDetection:
 
 
 class TestAutoCompactSystemMessages:
-    """Test that auto-new also works for system messages."""
+    """System-message idle compaction tests."""
 
     @pytest.mark.asyncio
     async def test_auto_compact_triggers_for_system_messages(self, tmp_path):
-        """Proactive auto-new archives expired session; system messages reload it."""
         loop = _make_loop(tmp_path, session_ttl_minutes=15)
         session = loop.sessions.get_or_create("cli:test")
         _add_turns(session, 6, prefix="old")
@@ -640,9 +642,10 @@ class TestAutoCompactSystemMessages:
         await loop._process_message(msg)
 
         session_after = loop.sessions.get_or_create("cli:test")
+        assert any(m["content"] == "old user 0" for m in session_after.messages)
         assert not any(
             m["content"] == "old user 0"
-            for m in session_after.messages
+            for m in session_after.get_history(max_messages=len(session_after.messages))
         )
         await loop.close_mcp()
 
@@ -652,7 +655,6 @@ class TestAutoCompactEdgeCases:
 
     @pytest.mark.asyncio
     async def test_auto_compact_with_nothing_summary(self, tmp_path):
-        """Auto-new should not inject when archive produces '(nothing)'."""
         loop = _make_loop(tmp_path, session_ttl_minutes=15)
         session = loop.sessions.get_or_create("cli:test")
         _add_turns(session, 6, prefix="thanks")
@@ -666,15 +668,17 @@ class TestAutoCompactEdgeCases:
         await loop.auto_compact._archive("cli:test", runtime=loop.llm_runtime())
 
         session_after = loop.sessions.get_or_create("cli:test")
-        assert len(session_after.messages) == loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        assert len(session_after.messages) == 12
+        assert len(session_after.get_history(max_messages=12)) == (
+            loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        )
         # "(nothing)" summary should not be stored
         assert "cli:test" not in loop.auto_compact._summaries
 
         await loop.close_mcp()
 
     @pytest.mark.asyncio
-    async def test_auto_compact_archive_failure_still_keeps_recent_suffix(self, tmp_path):
-        """Auto-new should keep the recent suffix even if LLM archive falls back to raw dump."""
+    async def test_auto_compact_archive_failure_preserves_raw_history(self, tmp_path):
         loop = _make_loop(tmp_path, session_ttl_minutes=15)
         session = loop.sessions.get_or_create("cli:test")
         _add_turns(session, 6, prefix="important")
@@ -687,7 +691,10 @@ class TestAutoCompactEdgeCases:
         await loop.auto_compact._archive("cli:test", runtime=loop.llm_runtime())
 
         session_after = loop.sessions.get_or_create("cli:test")
-        assert len(session_after.messages) == loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        assert len(session_after.messages) == 12
+        assert len(session_after.get_history(max_messages=12)) == (
+            loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        )
 
         await loop.close_mcp()
 
@@ -725,13 +732,10 @@ class TestAutoCompactEdgeCases:
 
 
 class TestAutoCompactIntegration:
-    """End-to-end test of auto session new feature."""
+    """Idle compaction integration tests."""
 
     @pytest.mark.asyncio
     async def test_full_lifecycle(self, tmp_path):
-        """
-        Full lifecycle: messages -> idle -> auto-new -> archive -> clear -> summary injected as runtime context.
-        """
         loop = _make_loop(tmp_path, session_ttl_minutes=15)
         session = loop.sessions.get_or_create("cli:test")
 
@@ -759,6 +763,7 @@ class TestAutoCompactIntegration:
                 tool_calls=[],
             )
         )
+        await loop.auto_compact._archive("cli:test", runtime=loop.llm_runtime())
 
         msg = InboundMessage(
             channel="cli", sender_id="user", chat_id="test",
@@ -769,9 +774,13 @@ class TestAutoCompactIntegration:
         # Phase 4: Verify
         session_after = loop.sessions.get_or_create("cli:test")
 
-        # The oldest messages should be trimmed from live session history
+        assert any(
+            "past tense is used" in str(m.get("content", "")).lower()
+            for m in session_after.messages
+        )
         assert not any(
-            "past tense is used" in str(m.get("content", "")) for m in session_after.messages
+            "past tense is used" in str(m.get("content", "")).lower()
+            for m in session_after.get_history(max_messages=len(session_after.messages))
         )
 
         # Summary should NOT be persisted in session (ephemeral, one-shot)
@@ -821,13 +830,13 @@ class TestAutoCompactIntegration:
 
 
 class TestProactiveAutoCompact:
-    """Test proactive auto-new on idle ticks (TimeoutError path in run loop)."""
+    """Proactive idle compaction tests."""
 
     @staticmethod
     async def _run_check_expired(loop, active_session_keys=()):
         """Helper: run check_expired via callback and wait for background tasks."""
         loop.auto_compact.check_expired(
-            loop._schedule_background,
+            loop.schedule_background,
             loop.runtime_for_session,
             active_session_keys=active_session_keys,
         )
@@ -899,7 +908,10 @@ class TestProactiveAutoCompact:
         await self._run_check_expired(loop)
 
         session_after = loop.sessions.get_or_create("cli:test")
-        assert len(session_after.messages) == loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        assert len(session_after.messages) == 10
+        assert len(session_after.get_history(max_messages=10)) == (
+            loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        )
         assert len(archived_messages) == 2
         entry = loop.auto_compact._summaries.get("cli:test")
         assert entry is not None
@@ -964,12 +976,12 @@ class TestProactiveAutoCompact:
         loop.consolidator.compact_idle_session = _slow_compact
 
         # First call starts archiving via callback
-        loop.auto_compact.check_expired(loop._schedule_background, loop.runtime_for_session)
+        loop.auto_compact.check_expired(loop.schedule_background, loop.runtime_for_session)
         await started.wait()
         assert archive_count == 1
 
         # Second call should skip (key is in _archiving)
-        loop.auto_compact.check_expired(loop._schedule_background, loop.runtime_for_session)
+        loop.auto_compact.check_expired(loop.schedule_background, loop.runtime_for_session)
         assert archive_count == 1
 
         # Clean up
@@ -1082,7 +1094,10 @@ class TestProactiveAutoCompact:
 
         assert _fake_compact.state["count"] == 1
         s1_after = loop.sessions.get_or_create("cli:expired_idle")
-        assert len(s1_after.messages) == loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        assert len(s1_after.messages) == 12
+        assert len(s1_after.get_history(max_messages=12)) == (
+            loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        )
         s2_after = loop.sessions.get_or_create("cli:expired_active")
         assert len(s2_after.messages) == 12  # Preserved
         s3_after = loop.sessions.get_or_create("cli:recent")
@@ -1211,7 +1226,10 @@ class TestSummaryPersistence:
 
         # prepare_session should recover summary from metadata
         reloaded = loop.sessions.get_or_create("cli:test")
-        assert len(reloaded.messages) == loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        assert len(reloaded.messages) == 12
+        assert len(reloaded.get_history(max_messages=12)) == (
+            loop.auto_compact._RECENT_SUFFIX_MESSAGES
+        )
         _, summary = loop.auto_compact.prepare_session(reloaded, "cli:test")
 
         assert summary is not None

tests/agent/test_autocompact_unit.py

@@ -154,6 +154,26 @@ class TestIsExpired:
         now_over = datetime(2026, 1, 1, 10, 10, 0)
         assert ac._is_expired(ts, now=now_over) is True
 
+    def test_unparseable_string_timestamp_returns_false(self):
+        """A persisted timestamp that no longer parses must not raise.
+
+        list_sessions() forwards the raw persisted updated_at string, and
+        SessionManager._load already tolerates a malformed value through its
+        recovery path. The idle scan must mirror that tolerance instead of crashing.
+        """
+        ac = _make_autocompact(ttl=15)
+        assert ac._is_expired("not-a-timestamp") is False
+
+    def test_tz_aware_string_timestamp_is_compared_by_instant(self):
+        """A valid timestamp with an offset remains eligible for expiry."""
+        ac = _make_autocompact(ttl=15)
+        now = datetime(2026, 1, 1, 12, 0, 0)
+        recent = (now - timedelta(minutes=10)).astimezone().isoformat()
+        expired = (now - timedelta(minutes=20)).astimezone().isoformat()
+
+        assert ac._is_expired(recent, now=now) is False
+        assert ac._is_expired(expired, now=now) is True
+
 
 # ---------------------------------------------------------------------------
 # _format_summary
@@ -221,6 +241,36 @@ class TestCheckExpired:
         assert len(scheduled) == 1
         assert "cli:old" in ac._archiving
 
+    def test_unparseable_updated_at_does_not_stop_scan(self):
+        """A malformed timestamp is skipped without hiding later sessions.
+
+        The idle scan runs from the agent loop's inbound-timeout branch, so a
+        raised exception here would tear down the loop. list_sessions() forwards
+        the raw string, so check_expired must tolerate it like SessionManager
+        does when loading.
+        """
+        ac = _make_autocompact(ttl=15)
+        mock_sm = MagicMock(spec=SessionManager)
+        old_dt = datetime.now() - timedelta(minutes=20)
+        session = _make_session("cli:old", updated_at=old_dt)
+        _add_turns(session, 5)
+        mock_sm.list_sessions.return_value = [
+            {"key": "cli:corrupt", "updated_at": "not-a-timestamp"},
+            {"key": "cli:old", "updated_at": old_dt.isoformat()},
+        ]
+        mock_sm.get_or_create.return_value = session
+        ac.sessions = mock_sm
+        scheduled = []
+
+        def scheduler(coro):
+            scheduled.append(coro)
+            coro.close()
+
+        ac.check_expired(scheduler, _runtime)
+
+        assert len(scheduled) == 1
+        assert ac._archiving == {"cli:old"}
+
     @pytest.mark.asyncio
     async def test_runtime_is_captured_before_background_starts(self):
         ac = _make_autocompact(ttl=15)

tests/agent/test_consolidator.py

@@ -10,7 +10,11 @@ from nanobot.agent.memory import (
     Consolidator,
     MemoryStore,
 )
-from nanobot.providers.base import GenerationSettings, LLMResponse
+from nanobot.providers.base import (
+    GenerationSettings,
+    LLMResponse,
+    ProviderConversationState,
+)
 from nanobot.runtime_context import (
     RUNTIME_CONTEXT_HISTORY_META,
     RuntimeContextBlock,
@@ -74,6 +78,16 @@ def _tool_round(call_id: str) -> list[dict]:
     ]
 
 
+def _provider_state() -> ProviderConversationState:
+    return ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="test-model",
+        version=1,
+        payload={"items": []},
+    )
+
+
 class TestConsolidatorSummarize:
     async def test_archive_prompt_includes_media_breadcrumb(
         self, consolidator, mock_provider, store, runtime
@@ -385,6 +399,7 @@ class TestConsolidatorTokenBudget:
         """Old messages that cannot be replayed should be materialized first."""
         consolidator._SAFETY_BUFFER = 0
         session = Session(key="test:replay-overflow")
+        session.provider_state = _provider_state()
         for i in range(10):
             session.add_message("user", f"u{i}")
             session.add_message("assistant", f"a{i}")
@@ -404,6 +419,7 @@ class TestConsolidatorTokenBudget:
         assert archived_chunk[-1]["content"] == "a6"
         assert session.last_consolidated == 14
         assert session.metadata["_last_summary"]["text"] == "old conversation summary"
+        assert session.provider_state is None
         consolidator.sessions.save.assert_called()
 
     async def test_replay_window_overflow_extends_to_long_recent_user_turn(
@@ -479,6 +495,7 @@ class TestConsolidatorTokenBudget:
         session = MagicMock()
         session.last_consolidated = 0
         session.key = "test:key"
+        session.provider_state = _provider_state()
         session.messages = [
             {
                 "role": "user" if i in {0, 50, 61} else "assistant",
@@ -500,6 +517,7 @@ class TestConsolidatorTokenBudget:
         # pick_consolidation_boundary returns (50, tokens) — user turn at idx 50
         assert archived_chunk[0]["content"] == "m0"
         assert session.last_consolidated > 0
+        assert session.provider_state is None
 
     async def test_raw_archive_fallback_advances_last_consolidated(
         self, consolidator, runtime
@@ -586,7 +604,7 @@ class TestConsolidatorTokenBudget:
 
 
 class TestCompactIdleSession:
-    """Tests for Consolidator.compact_idle_session — lock-protected idle truncation."""
+    """Idle compaction tests."""
 
     @pytest.fixture
     def real_consolidator(self, store, mock_provider):
@@ -602,16 +620,15 @@ class TestCompactIdleSession:
         )
 
     @pytest.mark.asyncio
-    async def test_archives_prefix_keeps_suffix(
+    async def test_archives_prefix_preserves_messages_and_hides_prefix(
         self, real_consolidator, mock_provider, runtime
     ):
-        """20 user/assistant turns → compact with max_suffix=8 → messages ≤ 8,
-        last_consolidated=0, _last_summary stored."""
         mock_provider.chat_with_retry.return_value = MagicMock(
             content="Summary of old conversation.", finish_reason="stop"
         )
         sessions = real_consolidator.sessions
         session = sessions.get_or_create("cli:test")
+        session.provider_state = _provider_state()
         old_ts = session.updated_at
         for i in range(20):
             session.add_message("user", f"user msg {i}")
@@ -624,9 +641,16 @@ class TestCompactIdleSession:
         )
         assert result == "Summary of old conversation."
 
+        sessions.invalidate("cli:test")
         reloaded = sessions.get_or_create("cli:test")
-        assert len(reloaded.messages) <= 8
-        assert reloaded.last_consolidated == 0
+        assert len(reloaded.messages) == 40
+        assert reloaded.messages[0]["content"] == "user msg 0"
+        assert reloaded.last_consolidated == 32
+        assert reloaded.provider_state is None
+        visible = reloaded.get_history(max_messages=40)
+        assert len(visible) == 8
+        assert visible[0]["content"] == "user msg 16"
+        assert visible[-1]["content"] == "assistant msg 19"
         meta = reloaded.metadata.get("_last_summary")
         assert meta is not None
         assert meta["text"] == "Summary of old conversation."
@@ -665,9 +689,7 @@ class TestCompactIdleSession:
     async def test_raw_dumps_only_dropped_messages_on_llm_failure(
         self, real_consolidator, mock_provider, store, runtime
     ):
-        """Summarizing over the full tail must not widen what gets raw-dumped on
-        LLM failure: the breadcrumb should contain only the removed prefix, not
-        the retained suffix that stays live in the session. Regression for #4264."""
+        """Extra summary context must not enter raw fallback. Regression for #4264."""
         mock_provider.chat_with_retry.side_effect = RuntimeError("LLM unavailable")
         sessions = real_consolidator.sessions
         session = sessions.get_or_create("cli:rawdrop")
@@ -684,8 +706,11 @@ class TestCompactIdleSession:
 
         raw = "\n".join(e["content"] for e in store.read_unprocessed_history(since_cursor=0))
         assert "[RAW]" in raw
-        assert "user msg 0" in raw  # removed prefix is the breadcrumb
-        assert "RETAINED_SUFFIX_marker" not in raw  # retained suffix not dumped
+        assert "user msg 0" in raw
+        assert "RETAINED_SUFFIX_marker" not in raw
+        reloaded = sessions.get_or_create("cli:rawdrop")
+        assert len(reloaded.messages) == 38
+        assert reloaded.messages[-1]["content"] == "RETAINED_SUFFIX_marker"
 
     @pytest.mark.asyncio
     async def test_idle_compact_writes_session_key_to_history(
@@ -757,10 +782,9 @@ class TestCompactIdleSession:
         assert "_last_summary" not in reloaded.metadata
 
     @pytest.mark.asyncio
-    async def test_llm_failure_still_truncates(
+    async def test_llm_failure_preserves_history_but_advances_replay_boundary(
         self, real_consolidator, mock_provider, store, runtime
     ):
-        """LLM raises RuntimeError → raw_archive fires, session still truncated, returns None."""
         mock_provider.chat_with_retry.side_effect = RuntimeError("LLM unavailable")
         sessions = real_consolidator.sessions
         session = sessions.get_or_create("cli:fail")
@@ -778,9 +802,16 @@ class TestCompactIdleSession:
         entries = store.read_unprocessed_history(since_cursor=0)
         assert any("[RAW]" in e["content"] for e in entries)
 
-        # Session should still be truncated
         reloaded = sessions.get_or_create("cli:fail")
-        assert len(reloaded.messages) <= 4
+        assert len(reloaded.messages) == 20
+        assert reloaded.messages[0]["content"] == "u0"
+        assert reloaded.last_consolidated == 16
+        assert [m["content"] for m in reloaded.get_history(max_messages=20)] == [
+            "u8",
+            "a8",
+            "u9",
+            "a9",
+        ]
 
     @pytest.mark.asyncio
     async def test_respects_last_consolidated(
@@ -802,6 +833,9 @@ class TestCompactIdleSession:
             "cli:offset", runtime=runtime, max_suffix=4
         )
         assert result == "Tail summary."
+        reloaded = sessions.get_or_create("cli:offset")
+        assert len(reloaded.messages) == 60
+        assert reloaded.last_consolidated == 56
 
         # Verify only the unconsolidated tail was processed:
         # 10 unconsolidated messages (50-59), keep suffix of 4 → archive 6
@@ -812,14 +846,12 @@ class TestCompactIdleSession:
         assert "u25" in user_content or "a25" in user_content
 
     @pytest.mark.asyncio
-    async def test_non_contiguous_suffix_archives_actual_dropped_messages(
+    async def test_extended_suffix_archives_only_hidden_prefix(
         self,
         real_consolidator,
         mock_provider,
         runtime,
     ):
-        """Assistant-only tails extend back to the latest user turn, so archive
-        the actual dropped messages rather than a computed prefix."""
         mock_provider.chat_with_retry.return_value = MagicMock(
             content="Tail summary.", finish_reason="stop"
         )
@@ -837,7 +869,9 @@ class TestCompactIdleSession:
         assert result == "Tail summary."
 
         reloaded = sessions.get_or_create("cli:noncontiguous")
-        assert [m["content"] for m in reloaded.messages] == [
+        assert len(reloaded.messages) == 25
+        assert reloaded.last_consolidated == 14
+        assert [m["content"] for m in reloaded.get_history(max_messages=25)] == [
             "user-14",
             "assistant-00",
             "assistant-01",
@@ -987,23 +1021,21 @@ class TestConsolidatorSessionRefresh:
         # Simulate: background consolidation captures old reference
         old_ref = session
 
-        # AutoCompact runs first and truncates to 8
         await consolidator.compact_idle_session(
             "cli:test",
             runtime=runtime,
             max_suffix=8,
         )
 
-        # Background consolidation runs with stale reference —
-        # should detect the session was replaced and not undo the compact.
         await consolidator.maybe_consolidate_by_tokens(
             old_ref,
             runtime=runtime,
         )
 
         session_after = sessions.get_or_create("cli:test")
-        # Messages should still be truncated (not restored to 40)
-        assert len(session_after.messages) <= 8
+        assert len(session_after.messages) == 40
+        assert session_after.last_consolidated == 32
+        assert len(session_after.get_history(max_messages=40)) == 8
 
 
 class TestRawArchiveTruncation:

tests/agent/test_context_builder.py

@@ -5,7 +5,6 @@ from pathlib import Path
 import pytest
 
 from nanobot.agent.context import ContextBuilder
-from nanobot.resource_links import ResourceView
 from nanobot.runtime_context import RuntimeContextBlock
 
 # ---------------------------------------------------------------------------
@@ -347,65 +346,6 @@ class TestBuildSystemPrompt:
         assert "## AGENTS.md" not in result
         assert "[Archived Context Summary]" not in result
 
-    def test_resource_aliases_are_absent_without_explicit_mode(self, tmp_path):
-        aliases = tmp_path / "resources" / "view"
-        resource_view = ResourceView(
-            root=aliases,
-            agent=aliases / "agent",
-            media=aliases / "media",
-            package=aliases / "package",
-        )
-
-        result = _builder(tmp_path, resource_view=resource_view).build_system_prompt()
-
-        assert "## Resource Aliases" not in result
-
-    def test_full_resource_aliases_show_roots_and_policy(self, tmp_path):
-        aliases = tmp_path / "resources" / "view"
-        resource_view = ResourceView(
-            root=aliases,
-            agent=aliases / "agent",
-            media=aliases / "media",
-            package=aliases / "package",
-        )
-
-        result = _builder(tmp_path, resource_view=resource_view).build_system_prompt(
-            resource_view_mode="full",
-        )
-
-        assert "## Resource Aliases" in result
-        assert f"Agent workspace: `{resource_view.agent}`" in result
-        assert f"Media: `{resource_view.media}`" in result
-        assert f"Nanobot package: `{resource_view.package}`" in result
-        assert f"Long-term memory: {resource_view.agent}/memory/MEMORY.md" in result
-        assert f"History log: {resource_view.agent}/memory/history.jsonl" in result
-        assert f"Custom skills: {resource_view.agent}/skills/" in result
-        assert "do not grant additional file or shell permissions" in result
-        assert "sandboxed shell may not expose an alias" in result
-        assert "paths relative to the current project workspace" in result
-
-    def test_restricted_resource_aliases_only_show_allowed_subtrees(self, tmp_path):
-        aliases = tmp_path / "resources" / "view"
-        resource_view = ResourceView(
-            root=aliases,
-            agent=aliases / "agent",
-            media=aliases / "media",
-            package=aliases / "package",
-        )
-
-        result = _builder(tmp_path, resource_view=resource_view).build_system_prompt(
-            resource_view_mode="restricted",
-        )
-
-        assert f"Custom skills: `{resource_view.agent / 'skills'}`" in result
-        assert f"Media: `{resource_view.media}`" in result
-        assert f"Built-in skills: `{resource_view.package / 'skills'}`" in result
-        assert f"Agent workspace: `{resource_view.agent}`" not in result
-        assert f"Nanobot package: `{resource_view.package}`" not in result
-        canonical_workspace = tmp_path.resolve()
-        assert f"History log: {canonical_workspace}/memory/history.jsonl" in result
-        assert f"History log: {resource_view.agent}/memory/history.jsonl" not in result
-
 
 # ---------------------------------------------------------------------------
 # build_messages
@@ -429,25 +369,6 @@ class TestBuildMessages:
         assert messages[1]["role"] == "user"
         assert "hello" in str(messages[1]["content"])
 
-    def test_resource_view_mode_is_forwarded_to_system_prompt(self, tmp_path):
-        aliases = tmp_path / "resources" / "view"
-        resource_view = ResourceView(
-            root=aliases,
-            agent=aliases / "agent",
-            media=aliases / "media",
-            package=aliases / "package",
-        )
-        builder = _builder(tmp_path, resource_view=resource_view)
-
-        messages = builder.build_messages(
-            [],
-            "hello",
-            resource_view_mode="restricted",
-        )
-
-        assert "## Resource Aliases" in messages[0]["content"]
-        assert f"Custom skills: `{resource_view.agent / 'skills'}`" in messages[0]["content"]
-
     def test_public_builder_preserves_assistant_role_compatibility(self, tmp_path):
         from nanobot.agent import ContextBuilder as PublicContextBuilder
 
@@ -531,6 +452,20 @@ class TestBuildMessages:
         assert "previous user message" in str(messages[1]["content"])
         assert "new message" in str(messages[1]["content"])
 
+    def test_current_message_can_be_built_without_history_merge(self, tmp_path):
+        builder = _builder(tmp_path)
+        current = builder.build_current_message(
+            "new message",
+            runtime_context_blocks=[
+                RuntimeContextBlock(source="test", content="fresh context"),
+            ],
+        )
+
+        assert current["role"] == "user"
+        assert "new message" in current["content"]
+        assert "fresh context" in current["content"]
+        assert current["_meta"]["runtime_context"]["sources"] == ["test"]
+
     def test_different_role_appended(self, tmp_path):
         builder = _builder(tmp_path)
         history = [{"role": "assistant", "content": "previous response"}]

tests/agent/test_dream.py

@@ -5,7 +5,6 @@ import pytest
 from nanobot.agent.memory import MemoryStore
 from nanobot.config.schema import ModelPresetConfig
 from nanobot.providers.base import LLMResponse
-from nanobot.resource_links import ResourceView
 from nanobot.security.workspace_access import (
     bind_workspace_scope,
     default_workspace_scope,
@@ -63,27 +62,6 @@ class TestBuildDreamPrompt:
         prompt, _ = result
         assert "skill-creator" in prompt
 
-    def test_prompt_uses_package_alias_for_skill_creator(self, tmp_path):
-        aliases = tmp_path / "resources" / "view"
-        resource_view = ResourceView(
-            root=aliases,
-            agent=aliases / "agent",
-            media=aliases / "media",
-            package=aliases / "package",
-        )
-        store = MemoryStore(tmp_path / "workspace", resource_view=resource_view)
-        store.append_history("test")
-
-        result = store.build_dream_prompt()
-
-        assert result is not None
-        prompt, _ = result
-        expected = resource_view.package / "skills" / "skill-creator" / "SKILL.md"
-        assert str(expected) in prompt
-
-    def test_default_dream_prompt_class_call_remains_compatible(self):
-        assert "skill-creator" in MemoryStore.default_dream_prompt()
-
     def test_prompt_embeds_current_memory_file_contents(self, store):
         """Dream must see the real current file contents (Tier 4) so it edits the
         files, not a stale mental model."""

tests/agent/test_loop_consolidation_tokens.py

@@ -215,7 +215,7 @@ async def test_preflight_consolidation_receives_pending_summary(tmp_path) -> Non
         return_value=(session, "Previous conversation summary: earlier context")
     )  # type: ignore[method-assign]
     loop.consolidator.maybe_consolidate_by_tokens = AsyncMock(return_value=None)  # type: ignore[method-assign]
-    loop._schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
+    loop.schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
 
     runtime = loop.llm_runtime()
     await loop.process_direct("hello", session_key="cli:test", runtime=runtime)
@@ -252,7 +252,7 @@ async def test_preflight_consolidation_before_llm_call(tmp_path, monkeypatch) ->
         return LLMResponse(content="ok", tool_calls=[])
     loop.provider.chat_with_retry = track_llm
     loop.provider.chat_stream_with_retry = track_llm
-    loop._schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
+    loop.schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
 
     session = loop.sessions.get_or_create("cli:test")
     session.messages = [

tests/agent/test_loop_direct_websocket_status.py

@@ -33,7 +33,7 @@ def _make_loop(tmp_path):
     WebuiTurnCoordinator(
         bus=bus,
         sessions=loop.sessions,
-        schedule_background=lambda coro: loop._schedule_background(coro),
+        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=[])

tests/agent/test_loop_progress.py

@@ -52,7 +52,7 @@ def _attach_webui_runtime_events(loop: AgentLoop, bus: MessageBus) -> None:
     coordinator = WebuiTurnCoordinator(
         bus=bus,
         sessions=loop.sessions,
-        schedule_background=lambda coro: loop._schedule_background(coro),
+        schedule_background=lambda coro: loop.schedule_background(coro),
     )
     coordinator.subscribe(loop.runtime_events)
 
@@ -1203,7 +1203,7 @@ class TestToolEventProgress:
             elif hasattr(coro, "close"):
                 coro.close()
 
-        loop._schedule_background = schedule_background  # type: ignore[method-assign]
+        loop.schedule_background = schedule_background  # type: ignore[method-assign]
 
         await loop._dispatch(InboundMessage(
             channel="websocket",
@@ -1249,7 +1249,7 @@ class TestToolEventProgress:
             fake_title_after_turn,
         )
         scheduled: list[object] = []
-        loop._schedule_background = scheduled.append  # type: ignore[method-assign]
+        loop.schedule_background = scheduled.append  # type: ignore[method-assign]
 
         await loop._dispatch(InboundMessage(
             channel="websocket",

tests/agent/test_loop_resource_view.py

@@ -1,107 +0,0 @@
-"""AgentLoop integration tests for the runtime resource view."""
-
-from pathlib import Path
-from types import SimpleNamespace
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from nanobot.agent.loop import AgentLoop, TurnKind
-from nanobot.bus.queue import MessageBus
-from nanobot.config.schema import ToolsConfig
-from nanobot.resource_links import ResourceView
-from nanobot.security.workspace_access import build_workspace_scope
-
-
-def _provider() -> MagicMock:
-    provider = MagicMock()
-    provider.get_default_model.return_value = "test-model"
-    provider.generation = SimpleNamespace(
-        max_tokens=4096,
-        temperature=0.1,
-        reasoning_effort=None,
-    )
-    return provider
-
-
-def _loop(
-    tmp_path: Path,
-    *,
-    resource_view: ResourceView | None,
-    tools_config: ToolsConfig | None = None,
-) -> tuple[AgentLoop, MagicMock, MagicMock]:
-    with (
-        patch("nanobot.agent.loop.ContextBuilder") as context_builder,
-        patch("nanobot.agent.loop.SessionManager"),
-        patch("nanobot.agent.loop.SubagentManager") as subagent_manager,
-        patch.object(AgentLoop, "_register_default_tools"),
-    ):
-        loop = AgentLoop(
-            bus=MessageBus(),
-            provider=_provider(),
-            workspace=tmp_path,
-            tools_config=tools_config,
-            resource_view=resource_view,
-        )
-    return loop, context_builder, subagent_manager
-
-
-def test_loop_injects_resource_view_without_creating_one(tmp_path: Path) -> None:
-    view = ResourceView(root=tmp_path / "resources" / "view")
-
-    loop, context_builder, subagent_manager = _loop(
-        tmp_path,
-        resource_view=view,
-    )
-
-    assert loop.resource_view is view
-    assert context_builder.call_args.kwargs["resource_view"] is view
-    assert subagent_manager.call_args.kwargs["resource_view"] is view
-
-
-@pytest.mark.parametrize(
-    ("access_mode", "sandbox", "expected"),
-    [
-        ("full", "", "full"),
-        ("restricted", "", "restricted"),
-        ("full", "bwrap", "restricted"),
-    ],
-)
-def test_initial_prompt_uses_effective_resource_view_mode(
-    tmp_path: Path,
-    access_mode: str,
-    sandbox: str,
-    expected: str,
-) -> None:
-    tools_config = ToolsConfig()
-    tools_config.exec.sandbox = sandbox
-    view = ResourceView(root=tmp_path / "resources" / "view")
-    loop, _, _ = _loop(
-        tmp_path,
-        resource_view=view,
-        tools_config=tools_config,
-    )
-    scope = build_workspace_scope(tmp_path, access_mode)
-    loop.workspace_scopes = SimpleNamespace(for_message=MagicMock(return_value=scope))
-    loop.context.build_messages.return_value = []
-    turn = SimpleNamespace(
-        session=SimpleNamespace(key="cli:test", metadata={}),
-        msg=SimpleNamespace(content="hello", media=None),
-        history=[],
-        kind=TurnKind.USER,
-        delivery=SimpleNamespace(route=SimpleNamespace(channel="cli")),
-        pending_summary=None,
-        runtime_context_blocks=[],
-        ephemeral=False,
-    )
-
-    loop._build_initial_messages(turn)
-
-    assert loop.context.build_messages.call_args.kwargs["resource_view_mode"] == expected
-
-
-def test_initial_prompt_keeps_legacy_mode_without_resource_view(tmp_path: Path) -> None:
-    loop, _, _ = _loop(tmp_path, resource_view=None)
-    scope = build_workspace_scope(tmp_path, "full")
-
-    assert loop._resource_view_mode_for_scope(scope) is None

tests/agent/test_loop_save_turn.py

@@ -1,4 +1,5 @@
 import asyncio
+import json
 from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import AsyncMock, MagicMock
@@ -19,7 +20,7 @@ from nanobot.bus.outbound_events import (
 )
 from nanobot.bus.queue import MessageBus
 from nanobot.cron.session_turns import CRON_HISTORY_META, CRON_TRIGGER_META
-from nanobot.providers.base import LLMResponse
+from nanobot.providers.base import LLMProvider, LLMResponse, ProviderConversationState
 from nanobot.providers.factory import ProviderSnapshot
 from nanobot.runtime_context import (
     RUNTIME_CONTEXT_HISTORY_META,
@@ -59,6 +60,16 @@ def _mk_loop() -> AgentLoop:
     return loop
 
 
+def _provider_state() -> ProviderConversationState:
+    return ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="test-model",
+        version=1,
+        payload={"items": []},
+    )
+
+
 def _runtime_message(content, blocks: list[RuntimeContextBlock]) -> dict:
     merged, marker = append_runtime_context(content, blocks)
     assert marker is not None
@@ -78,7 +89,7 @@ def _make_full_loop(tmp_path: Path) -> AgentLoop:
     WebuiTurnCoordinator(
         bus=loop.bus,
         sessions=loop.sessions,
-        schedule_background=lambda coro: loop._schedule_background(coro),
+        schedule_background=lambda coro: loop.schedule_background(coro),
     ).subscribe(loop.runtime_events)
     return loop
 
@@ -494,6 +505,7 @@ def test_restore_runtime_checkpoint_rehydrates_completed_and_pending_tools() ->
     loop = _mk_loop()
     session = Session(
         key="test:checkpoint",
+        provider_state=_provider_state(),
         metadata={
             AgentLoop._RUNTIME_CHECKPOINT_KEY: {
                 "assistant_message": {
@@ -539,6 +551,104 @@ def test_restore_runtime_checkpoint_rehydrates_completed_and_pending_tools() ->
     assert session.messages[1]["tool_call_id"] == "call_done"
     assert session.messages[2]["tool_call_id"] == "call_pending"
     assert "interrupted before this tool finished" in session.messages[2]["content"].lower()
+    assert session.provider_state is None
+
+
+def test_restore_final_response_checkpoint_preserves_matching_provider_state() -> None:
+    loop = _mk_loop()
+    state = _provider_state()
+    session = Session(
+        key="test:final-checkpoint",
+        provider_state=state,
+        metadata={
+            AgentLoop._RUNTIME_CHECKPOINT_KEY: {
+                "phase": "final_response",
+                AgentLoop._PROVIDER_STATE_CHECKPOINT_VERSION_KEY: (
+                    AgentLoop._PROVIDER_STATE_CHECKPOINT_VERSION
+                ),
+                "assistant_message": {
+                    "role": "assistant",
+                    "content": "finished",
+                },
+                "completed_tool_results": [],
+                "pending_tool_calls": [],
+            }
+        },
+    )
+
+    restored = loop._restore_runtime_checkpoint(session)
+
+    assert restored is True
+    assert session.messages[-1]["content"] == "finished"
+    assert session.provider_state is state
+    assert session.metadata.get(AgentLoop._RUNTIME_CHECKPOINT_KEY) is None
+
+
+def test_restore_legacy_final_checkpoint_discards_unproven_provider_state() -> None:
+    loop = _mk_loop()
+    session = Session(
+        key="test:legacy-final-checkpoint",
+        provider_state=_provider_state(),
+        metadata={
+            AgentLoop._RUNTIME_CHECKPOINT_KEY: {
+                "phase": "final_response",
+                "assistant_message": {
+                    "role": "assistant",
+                    "content": "finished",
+                },
+                "completed_tool_results": [],
+                "pending_tool_calls": [],
+            }
+        },
+    )
+
+    restored = loop._restore_runtime_checkpoint(session)
+
+    assert restored is True
+    assert session.messages[-1]["content"] == "finished"
+    assert session.provider_state is None
+
+
+def test_restore_completed_tools_checkpoint_preserves_matching_provider_state() -> None:
+    loop = _mk_loop()
+    tool_result = {
+        "role": "tool",
+        "tool_call_id": "call_done",
+        "name": "read_file",
+        "content": "compacted result",
+    }
+    state = _provider_state().with_pending_messages([tool_result])
+    session = Session(
+        key="test:completed-tools-checkpoint",
+        provider_state=state,
+        metadata={
+            AgentLoop._RUNTIME_CHECKPOINT_KEY: {
+                "phase": "tools_completed",
+                AgentLoop._PROVIDER_STATE_CHECKPOINT_VERSION_KEY: (
+                    AgentLoop._PROVIDER_STATE_CHECKPOINT_VERSION
+                ),
+                "assistant_message": {
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "id": "call_done",
+                            "type": "function",
+                            "function": {"name": "read_file", "arguments": "{}"},
+                        }
+                    ],
+                },
+                "completed_tool_results": [tool_result],
+                "pending_tool_calls": [],
+            }
+        },
+    )
+
+    restored = loop._restore_runtime_checkpoint(session)
+
+    assert restored is True
+    assert session.messages[-1]["content"] == "compacted result"
+    assert session.provider_state is state
 
 
 def test_restore_runtime_checkpoint_dedupes_overlapping_tail() -> None:
@@ -616,6 +726,55 @@ def test_restore_runtime_checkpoint_dedupes_overlapping_tail() -> None:
     assert session.messages[2]["tool_call_id"] == "call_pending"
 
 
+@pytest.mark.asyncio
+async def test_runtime_checkpoint_keeps_provider_state_out_of_public_metadata(
+    tmp_path: Path,
+) -> None:
+    loop = _make_full_loop(tmp_path)
+    state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="test-model",
+        version=1,
+        payload={
+            "items": [
+                {
+                    "type": "reasoning",
+                    "encrypted_content": "private-checkpoint-blob",
+                }
+            ]
+        },
+    )
+    loop.provider.can_resume_conversation_state.return_value = True
+    loop.provider.chat_with_retry = AsyncMock(
+        return_value=LLMResponse(content="done", provider_state=state)
+    )
+    session = loop.sessions.get_or_create("cli:private-checkpoint")
+
+    await loop._run_agent_loop(
+        [
+            {"role": "system", "content": "system"},
+            {"role": "user", "content": "question"},
+        ],
+        runtime=loop.llm_runtime(),
+        session=session,
+    )
+
+    assert session.provider_state is not None
+    checkpoint = session.metadata[AgentLoop._RUNTIME_CHECKPOINT_KEY]
+    assert "provider_state" not in checkpoint
+    assert checkpoint[AgentLoop._PROVIDER_STATE_CHECKPOINT_VERSION_KEY] == (
+        AgentLoop._PROVIDER_STATE_CHECKPOINT_VERSION
+    )
+    assert "private-checkpoint-blob" not in json.dumps(session.metadata)
+
+    public_payload = loop.sessions.read_session_file(session.key)
+    assert public_payload is not None
+    assert "private-checkpoint-blob" not in json.dumps(public_payload)
+    raw = loop.sessions._get_session_path(session.key).read_text(encoding="utf-8")
+    assert "private-checkpoint-blob" in raw
+
+
 @pytest.mark.asyncio
 async def test_process_message_persists_user_message_before_turn_completes(tmp_path: Path) -> None:
     loop = _make_full_loop(tmp_path)
@@ -634,6 +793,150 @@ async def test_process_message_persists_user_message_before_turn_completes(tmp_p
     assert persisted.updated_at >= persisted.created_at
 
 
+@pytest.mark.asyncio
+async def test_subagent_followup_stages_provider_state_before_turn_runs(
+    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._run_agent_loop = AsyncMock(side_effect=RuntimeError("boom"))  # type: ignore[method-assign]
+    loop.provider.can_resume_conversation_state.return_value = True
+    session = loop.sessions.get_or_create("cli:subagent-crash")
+    session.provider_state = _provider_state()
+    loop.sessions.save(session)
+
+    msg = InboundMessage(
+        channel="system",
+        sender_id="subagent",
+        chat_id="cli:subagent-crash",
+        content="subagent result",
+        metadata={"subagent_task_id": "sub-1"},
+    )
+    with pytest.raises(RuntimeError, match="boom"):
+        await loop._process_message(msg)
+
+    loop.sessions.invalidate("cli:subagent-crash")
+    persisted = loop.sessions.get_or_create("cli:subagent-crash")
+    assert persisted.messages[-1]["content"] == "subagent result"
+    assert persisted.provider_state is not None
+    assert persisted.provider_state.pending_messages[-1]["role"] == "user"
+    assert persisted.provider_state.pending_messages[-1]["content"] == "subagent result"
+
+
+@pytest.mark.asyncio
+async def test_subagent_followup_state_is_durable_before_prompt_assembly(
+    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.provider.can_resume_conversation_state.return_value = True
+    loop._build_initial_messages = MagicMock(  # type: ignore[method-assign]
+        side_effect=RuntimeError("prompt boom"),
+    )
+    session = loop.sessions.get_or_create("cli:subagent-prompt-crash")
+    session.provider_state = _provider_state()
+    loop.sessions.save(session)
+
+    msg = InboundMessage(
+        channel="system",
+        sender_id="subagent",
+        chat_id="cli:subagent-prompt-crash",
+        content="subagent result",
+        metadata={"subagent_task_id": "sub-1"},
+    )
+    with pytest.raises(RuntimeError, match="prompt boom"):
+        await loop._process_message(msg)
+
+    loop.sessions.invalidate("cli:subagent-prompt-crash")
+    persisted = loop.sessions.get_or_create("cli:subagent-prompt-crash")
+    assert persisted.messages[-1]["content"] == "subagent result"
+    assert persisted.provider_state is not None
+    assert persisted.provider_state.pending_messages[-1]["content"] == (
+        "subagent result"
+    )
+
+
+@pytest.mark.asyncio
+async def test_subagent_redelivery_does_not_duplicate_staged_provider_input(
+    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.provider.can_resume_conversation_state.return_value = True
+    build_initial_messages = loop._build_initial_messages
+    loop._build_initial_messages = MagicMock(  # type: ignore[method-assign]
+        side_effect=RuntimeError("prompt boom"),
+    )
+    session = loop.sessions.get_or_create("cli:subagent-redelivery")
+    session.provider_state = _provider_state()
+    loop.sessions.save(session)
+    msg = InboundMessage(
+        channel="system",
+        sender_id="subagent",
+        chat_id="cli:subagent-redelivery",
+        content="subagent result",
+        metadata={"subagent_task_id": "sub-1"},
+    )
+
+    with pytest.raises(RuntimeError, match="prompt boom"):
+        await loop._process_message(msg)
+
+    loop.sessions.invalidate("cli:subagent-redelivery")
+    persisted = loop.sessions.get_or_create("cli:subagent-redelivery")
+    assert persisted.provider_state is not None
+    assert [
+        message.get("content")
+        for message in persisted.provider_state.pending_messages
+    ].count("subagent result") == 1
+    loop._build_initial_messages = build_initial_messages  # type: ignore[method-assign]
+    loop._run_agent_loop = AsyncMock(  # type: ignore[method-assign]
+        side_effect=RuntimeError("provider boom"),
+    )
+    with pytest.raises(RuntimeError, match="provider boom"):
+        await loop._process_message(msg)
+
+    provider_state = loop._run_agent_loop.await_args.kwargs["provider_state"]
+    assert provider_state is not None
+    pending_results = [
+        message
+        for message in provider_state.pending_messages
+        if message.get("content") == "subagent result"
+    ]
+    assert len(pending_results) == 1
+    assert LLMProvider._sanitize_empty_content(pending_results) == [
+        {"role": "user", "content": "subagent result"},
+    ]
+
+
+@pytest.mark.asyncio
+async def test_subagent_followup_clears_state_before_compatibility_failure(
+    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.provider.can_resume_conversation_state.side_effect = RuntimeError(
+        "compatibility boom"
+    )
+    session = loop.sessions.get_or_create("cli:subagent-compat-crash")
+    session.provider_state = _provider_state()
+    loop.sessions.save(session)
+
+    msg = InboundMessage(
+        channel="system",
+        sender_id="subagent",
+        chat_id="cli:subagent-compat-crash",
+        content="subagent result",
+        metadata={"subagent_task_id": "sub-1"},
+    )
+    with pytest.raises(RuntimeError, match="compatibility boom"):
+        await loop._process_message(msg)
+
+    loop.sessions.invalidate("cli:subagent-compat-crash")
+    persisted = loop.sessions.get_or_create("cli:subagent-compat-crash")
+    assert persisted.messages[-1]["content"] == "subagent result"
+    assert persisted.provider_state is None
+
+
 @pytest.mark.asyncio
 async def test_process_message_persists_unified_session_delivery_route(tmp_path: Path) -> None:
     loop = _make_full_loop(tmp_path)
@@ -1245,6 +1548,9 @@ async def test_next_turn_after_crash_closes_pending_user_turn_before_new_input(t
     session = loop.sessions.get_or_create("feishu:c3")
     session.add_message("user", "old question")
     session.metadata[AgentLoop._PENDING_USER_TURN_KEY] = True
+    session.provider_state = _provider_state().with_pending_messages([
+        {"role": "user", "content": "old question"},
+    ])
     loop.sessions.save(session)
 
     loop._run_agent_loop = AsyncMock(return_value=(
@@ -1278,6 +1584,7 @@ async def test_next_turn_after_crash_closes_pending_user_turn_before_new_input(t
         {"role": "assistant", "content": "new answer"},
     ]
     assert AgentLoop._PENDING_USER_TURN_KEY not in session.metadata
+    assert session.provider_state is None
 
 
 @pytest.mark.asyncio

tests/agent/test_mcp_reconnect_crash.py

@@ -27,8 +27,10 @@ from nanobot.bus.queue import MessageBus
 from nanobot.config.schema import MCPServerConfig
 from nanobot.security import network as security_network
 
-_IDLE_TIMEOUT_SECONDS = 0.25
-_IDLE_EXPIRY_GRACE_SECONDS = 0.25
+# Leave enough headroom for reconnect handshakes on slower CI hosts; each test
+# still waits beyond this deadline explicitly before exercising recovery.
+_IDLE_TIMEOUT_SECONDS = 1.0
+_IDLE_EXPIRY_GRACE_SECONDS = 0.5
 _TOOL_TIMEOUT_SECONDS = 10
 
 

tests/agent/test_runner_core.py

@@ -11,7 +11,13 @@ import pytest
 
 from agent.runner_helpers import make_run_spec
 from nanobot.config.schema import AgentDefaults
-from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+from nanobot.providers.base import (
+    LLMProvider,
+    LLMResponse,
+    ProviderCallContext,
+    ProviderConversationState,
+    ToolCallRequest,
+)
 
 _MAX_TOOL_RESULT_CHARS = AgentDefaults().max_tool_result_chars
 
@@ -73,6 +79,311 @@ async def test_runner_preserves_reasoning_fields_and_tool_results():
     )
 
 
+@pytest.mark.asyncio
+async def test_runner_replays_provider_state_without_chat_projection_duplicates():
+    from nanobot.agent.runner import AgentRunner
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.can_resume_conversation_state.return_value = True
+    provider.supports_native_compaction.return_value = False
+    captured_second_kwargs: dict = {}
+    checkpoints: list[dict] = []
+    calls = 0
+
+    async def checkpoint(payload: dict) -> None:
+        checkpoints.append(payload)
+
+    first_state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={"items": [{"type": "reasoning", "encrypted_content": "opaque"}]},
+    )
+    second_state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={"items": [{"type": "message", "role": "assistant"}]},
+    )
+
+    async def chat_with_retry(**kwargs):
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            provider_context = kwargs["provider_context"]
+            assert isinstance(provider_context, ProviderCallContext)
+            assert provider_context.conversation_state is None
+            return LLMResponse(
+                content=None,
+                tool_calls=[
+                    ToolCallRequest(
+                        id="call_1|fc_1",
+                        name="list_dir",
+                        arguments={"path": "."},
+                    ),
+                ],
+                provider_state=first_state,
+            )
+        captured_second_kwargs.update(kwargs)
+        return LLMResponse(content="done", provider_state=second_state)
+
+    provider.chat_with_retry = chat_with_retry
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+    tools.execute = AsyncMock(return_value="tool result")
+
+    result = await AgentRunner().run(make_run_spec(
+        provider,
+        initial_messages=[
+            {"role": "system", "content": "system"},
+            {"role": "user", "content": "do task"},
+        ],
+        tools=tools,
+        model="gpt-5.6",
+        max_iterations=3,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        checkpoint_callback=checkpoint,
+    ))
+
+    provider_context = captured_second_kwargs["provider_context"]
+    assert isinstance(provider_context, ProviderCallContext)
+    assert provider_context.conversation_state is not None
+    assert provider_context.conversation_state.payload == first_state.payload
+    assert provider_context.conversation_state.pending_messages == [{
+        "role": "tool",
+        "tool_call_id": "call_1|fc_1",
+        "name": "list_dir",
+        "content": "tool result",
+    }]
+    assert not any(
+        message.get("role") == "assistant"
+        for message in provider_context.conversation_state.pending_messages
+    )
+    assert result.provider_state is not None
+    assert result.provider_state.payload == second_state.payload
+    assert result.provider_state.pending_messages == []
+    assert checkpoints[0]["phase"] == "awaiting_tools"
+    assert "provider_state" not in checkpoints[0]
+    assert checkpoints[1]["phase"] == "tools_completed"
+    assert checkpoints[1]["provider_state"].pending_messages == [{
+        "role": "tool",
+        "tool_call_id": "call_1|fc_1",
+        "name": "list_dir",
+        "content": "tool result",
+    }]
+    assert checkpoints[2]["phase"] == "final_response"
+    assert checkpoints[2]["provider_state"].payload == second_state.payload
+
+
+@pytest.mark.asyncio
+async def test_runner_governs_tool_result_before_adding_it_to_provider_state():
+    from nanobot.agent.runner import AgentRunner
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.can_resume_conversation_state.return_value = True
+    provider.supports_native_compaction.return_value = False
+    calls = 0
+    captured_context: ProviderCallContext | None = None
+    checkpoints: list[dict] = []
+    state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={"items": [{"type": "reasoning", "encrypted_content": "opaque"}]},
+    )
+
+    async def chat_with_retry(**kwargs):
+        nonlocal calls, captured_context
+        calls += 1
+        if calls == 1:
+            return LLMResponse(
+                content=None,
+                tool_calls=[
+                    ToolCallRequest(
+                        id="call_1",
+                        name="read_file",
+                        arguments={"path": "large.txt"},
+                    ),
+                ],
+                provider_state=state,
+            )
+        captured_context = kwargs["provider_context"]
+        return LLMResponse(content="done")
+
+    provider.chat_with_retry = chat_with_retry
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+    tools.execute = AsyncMock(return_value="x" * 5_000)
+
+    async def checkpoint(payload: dict) -> None:
+        checkpoints.append(payload)
+
+    await AgentRunner().run(make_run_spec(
+        provider,
+        initial_messages=[
+            {"role": "system", "content": "system"},
+            {"role": "user", "content": "read the file"},
+        ],
+        tools=tools,
+        model="gpt-5.6",
+        context_window_tokens=3_000,
+        context_block_limit=200,
+        max_tokens=1_000,
+        max_iterations=3,
+        max_tool_result_chars=10_000,
+        checkpoint_callback=checkpoint,
+    ))
+
+    assert captured_context is not None
+    assert captured_context.conversation_state is not None
+    pending = captured_context.conversation_state.pending_messages
+    assert len(pending) == 1
+    assert pending[0]["role"] == "tool"
+    assert "compacted to fit context" in pending[0]["content"]
+    assert pending[0]["content"] != "x" * 5_000
+    completed_checkpoint = next(
+        checkpoint
+        for checkpoint in checkpoints
+        if checkpoint["phase"] == "tools_completed"
+    )
+    checkpoint_pending = completed_checkpoint["provider_state"].pending_messages
+    assert "compacted to fit context" in checkpoint_pending[0]["content"]
+    assert checkpoint_pending[0]["content"] != "x" * 5_000
+
+
+@pytest.mark.asyncio
+async def test_injected_final_response_checkpoint_includes_provider_state():
+    from nanobot.agent.runner import AgentRunner
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.can_resume_conversation_state.return_value = True
+    provider.supports_native_compaction.return_value = False
+    first_state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={"items": [{"type": "message", "content": "first answer"}]},
+    )
+    second_state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={"items": [{"type": "message", "content": "second answer"}]},
+    )
+    provider.chat_with_retry = AsyncMock(side_effect=[
+        LLMResponse(content="first answer", provider_state=first_state),
+        LLMResponse(content="second answer", provider_state=second_state),
+    ])
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+    checkpoints: list[dict] = []
+    injections = [[{"role": "user", "content": "follow up"}], []]
+
+    async def checkpoint(payload: dict) -> None:
+        checkpoints.append(payload)
+
+    async def inject() -> list[dict]:
+        return injections.pop(0)
+
+    await AgentRunner().run(make_run_spec(
+        provider,
+        initial_messages=[{"role": "user", "content": "start"}],
+        tools=tools,
+        model="gpt-5.6",
+        max_iterations=3,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        checkpoint_callback=checkpoint,
+        injection_callback=inject,
+    ))
+
+    assert checkpoints[0]["phase"] == "final_response"
+    assert checkpoints[0]["provider_state"].payload == first_state.payload
+
+
+@pytest.mark.asyncio
+async def test_runner_preserves_last_completed_provider_state_on_model_error():
+    from nanobot.agent.runner import AgentRunner
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.can_resume_conversation_state.return_value = True
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="temporary upstream failure",
+        finish_reason="error",
+        error_kind="timeout",
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+    state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={"items": [{"type": "reasoning", "encrypted_content": "opaque"}]},
+    )
+    unsaved_input = {"role": "user", "content": "ephemeral follow-up"}
+
+    result = await AgentRunner().run(make_run_spec(
+        provider,
+        initial_messages=[
+            {"role": "system", "content": "system"},
+            unsaved_input,
+        ],
+        tools=tools,
+        model="gpt-5.6",
+        max_iterations=1,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        provider_state=state.with_pending_messages([unsaved_input]),
+    ))
+
+    assert result.stop_reason == "error"
+    assert result.provider_state is not None
+    assert result.provider_state.payload == state.payload
+    assert result.provider_state.pending_messages[0] == unsaved_input
+    assert result.provider_state.pending_messages[1]["role"] == "assistant"
+    assert "model error" in result.provider_state.pending_messages[1]["content"]
+
+
+@pytest.mark.asyncio
+async def test_runner_discards_provider_state_on_non_retryable_model_error():
+    from nanobot.agent.runner import AgentRunner
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.can_resume_conversation_state.return_value = True
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="context length exceeded",
+        finish_reason="error",
+        error_status_code=400,
+        error_should_retry=False,
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+    state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={"items": [{"type": "reasoning", "encrypted_content": "opaque"}]},
+    )
+
+    result = await AgentRunner().run(make_run_spec(
+        provider,
+        initial_messages=[{"role": "user", "content": "continue"}],
+        tools=tools,
+        model="gpt-5.6",
+        max_iterations=1,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        provider_state=state,
+    ))
+
+    assert result.stop_reason == "error"
+    assert result.provider_state is None
+
+
 @pytest.mark.asyncio
 async def test_runner_returns_max_iterations_fallback():
     from nanobot.agent.runner import AgentRunner
@@ -422,6 +733,66 @@ async def test_runner_retries_empty_final_response_with_summary_prompt():
     assert result.usage["completion_tokens"] == 9
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize("finish_reason", ["refusal", "content_filter"])
+async def test_runner_does_not_retry_blank_policy_terminal(
+    finish_reason: str,
+) -> None:
+    from nanobot.agent.runner import AgentRunner
+    from nanobot.utils.runtime import EMPTY_FINAL_RESPONSE_MESSAGE
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content=None,
+        finish_reason=finish_reason,
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    result = await AgentRunner().run(make_run_spec(
+        provider,
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=3,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+    ))
+
+    assert provider.chat_with_retry.await_count == 1
+    assert result.final_content == EMPTY_FINAL_RESPONSE_MESSAGE
+    assert result.stop_reason == "empty_final_response"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("finish_reason", ["refusal", "content_filter"])
+async def test_runner_does_not_auto_continue_goal_after_policy_terminal(
+    finish_reason: str,
+) -> None:
+    from nanobot.agent.runner import AgentRunner
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="Request blocked by provider policy.",
+        finish_reason=finish_reason,
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    result = await AgentRunner().run(make_run_spec(
+        provider,
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=3,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        goal_active_predicate=lambda: True,
+    ))
+
+    assert provider.chat_with_retry.await_count == 1
+    assert result.final_content == "Request blocked by provider policy."
+    assert result.stop_reason == "completed"
+
+
 @pytest.mark.asyncio
 async def test_runner_uses_specific_message_after_empty_finalization_retry():
     """After silent retries + finalization all return empty, stop_reason is empty_final_response."""
@@ -450,6 +821,56 @@ async def test_runner_uses_specific_message_after_empty_finalization_retry():
     assert result.stop_reason == "empty_final_response"
 
 
+@pytest.mark.asyncio
+async def test_empty_finalization_retry_discards_candidate_provider_state():
+    from nanobot.agent.runner import AgentRunner
+
+    candidate = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="test-model",
+        version=1,
+        payload={
+            "items": [{
+                "type": "function_call",
+                "call_id": "call_1",
+                "name": "exec",
+                "arguments": "{}",
+            }],
+        },
+    )
+    provider = MagicMock(spec=LLMProvider)
+    provider.can_resume_conversation_state.return_value = True
+    provider.chat_with_retry = AsyncMock(side_effect=[
+        LLMResponse(content=None, tool_calls=[], usage={}),
+        LLMResponse(content=None, tool_calls=[], usage={}),
+        LLMResponse(
+            content="finalized without tools",
+            tool_calls=[ToolCallRequest(id="call_1", name="exec", arguments={})],
+            finish_reason="stop",
+            provider_state=candidate,
+            usage={},
+        ),
+    ])
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+    tools.execute = AsyncMock(return_value="must not run")
+
+    runner = AgentRunner()
+    result = await runner.run(make_run_spec(
+        provider,
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=3,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+    ))
+
+    tools.execute.assert_not_awaited()
+    assert result.final_content == "finalized without tools"
+    assert result.provider_state is None
+
+
 @pytest.mark.asyncio
 async def test_runner_length_recovery_returns_all_segments():
     """Recovered output segments are returned together instead of only the tail."""

tests/agent/test_runner_errors.py

@@ -310,3 +310,50 @@ async def test_runner_tool_error_preserves_tool_results_in_messages():
         i for i, m in enumerate(result.messages) if m.get("role") == "tool"
     ]
     assert all(ti > asst_tc_idx for ti in tool_indices)
+
+
+@pytest.mark.asyncio
+async def test_length_finish_with_blank_content_routes_to_length_recovery():
+    """Regression test for #5133.
+
+    A response with finish_reason='length' and blank content (e.g. the model
+    spent its whole output budget on a tool call whose closing tag was
+    truncated) must take the length-recovery path, not the empty-response
+    retry path. Retrying the same prompt cannot recover from output-budget
+    exhaustion.
+    """
+    from nanobot.agent.runner import AgentRunner
+    from nanobot.utils.runtime import LENGTH_RECOVERY_PROMPT
+
+    provider = MagicMock(spec=LLMProvider)
+    # First call: truncated (length) with blank content and a dropped tool call.
+    # Second call: normal completion so the loop can terminate.
+    provider.chat_with_retry = AsyncMock(side_effect=[
+        LLMResponse(
+            content="",
+            finish_reason="length",
+            tool_calls=[ToolCallRequest(id="call_1", name="exec", arguments={})],
+            usage={},
+        ),
+        LLMResponse(content="done", finish_reason="stop", tool_calls=[], usage={}),
+    ])
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    runner = AgentRunner()
+    result = await runner.run(make_run_spec(provider,
+        initial_messages=[{"role": "user", "content": "do a long task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=5,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+    ))
+
+    # The runner must have injected a length-recovery prompt and continued,
+    # rather than exhausting empty-response retries into a generic apology.
+    user_msgs = [m.get("content") or "" for m in result.messages if m.get("role") == "user"]
+    assert any(LENGTH_RECOVERY_PROMPT in c for c in user_msgs), (
+        "expected a length-recovery message to be appended for a "
+        "finish_reason='length' response with blank content"
+    )
+    assert result.final_content == "done"

tests/agent/test_runner_fallback.py

@@ -9,8 +9,15 @@ import pytest
 from loguru import logger
 
 from nanobot.config.schema import ModelPresetConfig
-from nanobot.providers.base import LLMProvider, LLMResponse
+from nanobot.providers.base import (
+    LLMProvider,
+    LLMResponse,
+    ProviderCallContext,
+    ProviderConversationState,
+)
+from nanobot.providers.conversation_state import ProviderConversationStateController
 from nanobot.providers.fallback_provider import FallbackProvider
+from nanobot.providers.openai_responses import resolve_compact_threshold
 
 
 def _make_response(
@@ -66,6 +73,9 @@ class _FakeProvider(LLMProvider):
         self._response = response or _make_response()
         self.chat_calls: list[dict[str, Any]] = []
         self.chat_stream_calls: list[dict[str, Any]] = []
+        self.context_calls: list[ProviderCallContext | None] = []
+        self.resumable = False
+        self.compact = False
 
     def get_default_model(self) -> str:
         return f"{self.name}/model"
@@ -81,6 +91,26 @@ class _FakeProvider(LLMProvider):
             await on_delta(self._response.content)
         return self._response
 
+    async def chat_with_context(
+        self,
+        provider_context: ProviderCallContext | None = None,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        self.context_calls.append(provider_context)
+        return await self.chat(**kwargs)
+
+    def can_resume_conversation_state(
+        self,
+        state: ProviderConversationState,
+        model: str | None = None,
+    ) -> bool:
+        _ = state, model
+        return self.resumable
+
+    def supports_native_compaction(self, model: str | None = None) -> bool:
+        _ = model
+        return self.compact
+
 
 # -- config-level tests --
 
@@ -211,6 +241,8 @@ def test_provider_snapshot_uses_smallest_fallback_context_window() -> None:
         snapshot = build_provider_snapshot(config)
 
     assert snapshot.context_window_tokens == 64000
+    assert isinstance(snapshot.provider, FallbackProvider)
+    assert snapshot.provider._primary_context_window_tokens == 128000
 
 
 def test_inline_fallback_reasoning_effort_does_not_inherit_primary() -> None:
@@ -285,6 +317,257 @@ class TestFallbackOnPrimaryError:
         assert primary.chat_calls[0]["model"] == "primary-model"
         assert fallback.chat_calls[0]["model"] == "fallback-a"
 
+    @pytest.mark.asyncio
+    async def test_primary_compaction_uses_primary_context_window(self) -> None:
+        primary = _FakeProvider("primary", _make_response("primary ok"))
+        primary.compact = True
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("small-chat", context_window_tokens=50_000),
+            ],
+            provider_factory=MagicMock(),
+            primary_context_window_tokens=200_000,
+        )
+
+        await fb.chat_with_context(
+            messages=[{"role": "user", "content": "hi"}],
+            model="gpt-5.6",
+            max_tokens=10_000,
+            provider_context=ProviderCallContext(context_window_tokens=50_000),
+        )
+
+        primary_context = primary.context_calls[0]
+        assert primary_context is not None
+        assert primary_context.context_window_tokens == 200_000
+        assert resolve_compact_threshold(
+            primary_context.context_window_tokens,
+            10_000,
+        ) == 180_000
+
+    @pytest.mark.asyncio
+    async def test_native_fallback_compaction_uses_its_own_context_window(self) -> None:
+        primary = _FakeProvider("primary", _error_response())
+        primary.compact = True
+        fallback = _FakeProvider("fallback", _make_response("fallback ok"))
+        fallback.compact = True
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", context_window_tokens=120_000),
+            ],
+            provider_factory=MagicMock(return_value=fallback),
+            primary_context_window_tokens=200_000,
+        )
+
+        result = await fb.chat_with_context(
+            messages=[{"role": "user", "content": "hi"}],
+            model="gpt-5.6",
+            provider_context=ProviderCallContext(context_window_tokens=50_000),
+        )
+
+        assert result.content == "fallback ok"
+        assert primary.context_calls == [
+            ProviderCallContext(context_window_tokens=200_000)
+        ]
+        assert fallback.context_calls == [
+            ProviderCallContext(context_window_tokens=120_000)
+        ]
+
+    @pytest.mark.asyncio
+    async def test_native_fallback_gets_context_when_primary_does_not_use_it(self) -> None:
+        primary = _FakeProvider("primary", _error_response())
+        fallback = _FakeProvider("fallback", _make_response("fallback ok"))
+        fallback.compact = True
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", context_window_tokens=120_000),
+            ],
+            provider_factory=MagicMock(return_value=fallback),
+            primary_context_window_tokens=200_000,
+        )
+        messages = [{"role": "user", "content": "hi"}]
+        controller = ProviderConversationStateController(
+            provider=fb,
+            model="primary-model",
+            messages=messages,
+        )
+        assert fb.supports_native_compaction("primary-model") is False
+        provider_context = controller.prepare_request(
+            messages,
+            context_window_tokens=50_000,
+        )
+
+        assert provider_context == ProviderCallContext(
+            context_window_tokens=50_000
+        )
+        result = await fb.chat_with_context(
+            messages=messages,
+            model="primary-model",
+            provider_context=provider_context,
+        )
+
+        assert result.content == "fallback ok"
+        assert primary.context_calls == [ProviderCallContext()]
+        assert fallback.context_calls == [
+            ProviderCallContext(context_window_tokens=120_000)
+        ]
+
+    @pytest.mark.asyncio
+    async def test_responses_chat_fallback_responses_rebuilds_state(self) -> None:
+        primary = _FakeProvider("primary", _error_response())
+        primary.resumable = True
+        primary.compact = True
+        fallback = _FakeProvider("fallback", _make_response("fallback ok"))
+        messages = [{"role": "user", "content": "hi"}]
+        state = ProviderConversationState(
+            kind="openai_responses",
+            provider="openai:test",
+            model="gpt-5.6",
+            version=1,
+            payload={"items": [{"type": "reasoning", "encrypted_content": "opaque"}]},
+            pending_messages=list(messages),
+        )
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[_fallback("fallback-a")],
+            provider_factory=MagicMock(return_value=fallback),
+        )
+        controller = ProviderConversationStateController(
+            provider=fb,
+            model="gpt-5.6",
+            messages=messages,
+            state=state,
+        )
+        provider_context = controller.prepare_request(
+            messages,
+            context_window_tokens=200_000,
+        )
+        assert provider_context is not None
+
+        result = await fb.chat_with_context(
+            messages=messages,
+            model="gpt-5.6",
+            provider_context=provider_context,
+        )
+
+        assert result.content == "fallback ok"
+        assert primary.context_calls == [provider_context]
+        assert fallback.context_calls == [ProviderCallContext()]
+        assert fallback.chat_calls[0]["messages"] == messages
+
+        controller.observe_response(result, messages)
+        messages.append({"role": "assistant", "content": result.content})
+        assert controller.finish(messages) is None
+
+        recovered_state = ProviderConversationState(
+            kind="openai_responses",
+            provider="openai:test",
+            model="gpt-5.6",
+            version=1,
+            payload={"items": [{"type": "reasoning", "encrypted_content": "recovered"}]},
+        )
+        primary._response = LLMResponse(
+            content="primary recovered",
+            provider_state=recovered_state,
+        )
+        next_turn = ProviderConversationStateController(
+            provider=fb,
+            model="gpt-5.6",
+            messages=messages,
+        )
+        next_context = next_turn.prepare_request(
+            messages,
+            context_window_tokens=200_000,
+        )
+        assert next_context == ProviderCallContext(context_window_tokens=200_000)
+
+        recovered = await fb.chat_with_context(
+            messages=messages,
+            model="gpt-5.6",
+            provider_context=next_context,
+        )
+
+        assert recovered.provider_state is recovered_state
+        assert primary.context_calls[-1] == next_context
+        assert primary.chat_calls[-1]["messages"] == messages
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        ("primary_error_kind", "primary_status", "primary_should_retry"),
+        [
+            ("server_error", 503, True),
+            ("authentication", 401, False),
+        ],
+        ids=["transient", "authentication"],
+    )
+    async def test_final_fallback_error_uses_primary_state_disposition(
+        self,
+        primary_error_kind: str,
+        primary_status: int,
+        primary_should_retry: bool,
+    ) -> None:
+        primary = _FakeProvider(
+            "primary",
+            _make_response(
+                "primary unavailable",
+                finish_reason="error",
+                error_kind=primary_error_kind,
+                error_status_code=primary_status,
+                error_should_retry=primary_should_retry,
+            ),
+        )
+        primary.resumable = True
+        fallback = _FakeProvider(
+            "fallback",
+            _make_response(
+                "fallback invalid request",
+                finish_reason="error",
+                error_kind="invalid_request",
+                error_status_code=400,
+                error_should_retry=False,
+            ),
+        )
+        messages = [{"role": "user", "content": "continue"}]
+        state = ProviderConversationState(
+            kind="openai_responses",
+            provider="openai:test",
+            model="gpt-5.6",
+            version=1,
+            payload={"items": [{"type": "reasoning", "encrypted_content": "opaque"}]},
+            pending_messages=list(messages),
+        )
+        provider = FallbackProvider(
+            primary=primary,
+            fallback_presets=[_fallback("fallback-a")],
+            provider_factory=MagicMock(return_value=fallback),
+        )
+        controller = ProviderConversationStateController(
+            provider=provider,
+            model="gpt-5.6",
+            messages=messages,
+            state=state,
+        )
+        provider_context = controller.prepare_request(
+            messages,
+            context_window_tokens=200_000,
+        )
+        assert provider_context is not None
+
+        response = await provider.chat_with_context(
+            messages=messages,
+            model="gpt-5.6",
+            provider_context=provider_context,
+        )
+        controller.observe_response(response, messages)
+
+        assert response.content == "fallback invalid request"
+        assert response.preserve_provider_state_on_error is True
+        restored = controller.finish(messages)
+        assert restored is not None
+        assert restored.payload == state.payload
+
     @pytest.mark.asyncio
     async def test_reports_the_fallback_model_before_its_request(self) -> None:
         primary = _FakeProvider("primary", _error_response())

tests/agent/test_runner_governance.py

@@ -15,7 +15,11 @@ from nanobot.agent.context_governance import (
 )
 from nanobot.agent.runner import AgentRunSpec
 from nanobot.config.schema import AgentDefaults
-from nanobot.providers.base import LLMResponse, ToolCallRequest
+from nanobot.providers.base import (
+    LLMResponse,
+    ProviderConversationState,
+    ToolCallRequest,
+)
 
 _MAX_TOOL_RESULT_CHARS = AgentDefaults().max_tool_result_chars
 
@@ -886,6 +890,13 @@ def test_drop_malformed_tool_calls_trims_response():
     """LLM response tool_calls with a missing/empty name are dropped in place."""
     from nanobot.agent.runner import AgentRunner
 
+    candidate_state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={"items": [{"type": "function_call", "name": None}]},
+    )
     response = LLMResponse(
         content=None,
         tool_calls=[
@@ -895,9 +906,11 @@ def test_drop_malformed_tool_calls_trims_response():
             ToolCallRequest(id="4", name="read_file", arguments={}),
         ],
         finish_reason="tool_calls",
+        provider_state=candidate_state,
     )
     dropped, all_dropped, orig = AgentRunner._drop_malformed_tool_calls(response)
     assert [tc.name for tc in response.tool_calls] == ["read_file"]
+    assert response.provider_state is None
     assert response.finish_reason == "tool_calls"
     assert response.should_execute_tools is True
     assert dropped == 3

tests/agent/test_session_atomic.py

@@ -4,6 +4,7 @@ import json
 from datetime import datetime
 from pathlib import Path
 
+from nanobot.providers.base import ProviderConversationState
 from nanobot.session.manager import Session, SessionManager
 
 
@@ -101,6 +102,137 @@ class TestAtomicSave:
         for i in range(5):
             assert loaded.messages[i]["content"] == f"msg{i}"
 
+    def test_provider_state_round_trips_in_private_record_only(self, tmp_path: Path):
+        mgr = SessionManager(tmp_path)
+        secret = "encrypted-reasoning-blob"
+        session = Session(
+            key="test:provider-state",
+            provider_state=ProviderConversationState(
+                kind="openai_responses",
+                provider="openai:https://api.openai.com/v1",
+                model="gpt-5.6",
+                version=1,
+                payload={
+                    "items": [
+                        {
+                            "type": "reasoning",
+                            "encrypted_content": secret,
+                        }
+                    ]
+                },
+                pending_messages=[{"role": "user", "content": "continue"}],
+            ),
+        )
+        session.add_message("user", "hello")
+        mgr.save(session)
+
+        records = [
+            json.loads(line)
+            for line in mgr._get_session_path(session.key)
+            .read_text(encoding="utf-8")
+            .splitlines()
+        ]
+        assert [record.get("_type") for record in records] == [
+            "metadata",
+            "provider_state",
+            None,
+        ]
+        assert secret in records[1]["state"]["payload"]["items"][0]["encrypted_content"]
+
+        mgr.invalidate(session.key)
+        loaded = mgr.get_or_create(session.key)
+        assert loaded.provider_state is not None
+        assert loaded.provider_state.to_private_record() == session.provider_state.to_private_record()
+
+        public_payload = mgr.read_session_file(session.key)
+        assert public_payload is not None
+        assert public_payload["messages"] == [session.messages[0]]
+        assert secret not in json.dumps(public_payload)
+        assert secret not in json.dumps(mgr.list_sessions())
+
+    def test_provider_state_does_not_consume_list_preview_budget(
+        self,
+        tmp_path: Path,
+        monkeypatch,
+    ):
+        import nanobot.session.manager as session_manager
+
+        monkeypatch.setattr(session_manager, "_SESSION_LIST_PREVIEW_MAX_CHARS", 100)
+        mgr = SessionManager(tmp_path)
+        session = Session(
+            key="test:provider-state-preview",
+            provider_state=ProviderConversationState(
+                kind="openai_responses",
+                provider="openai:test",
+                model="test-model",
+                version=1,
+                payload={"items": [{"encrypted_content": "x" * 200}]},
+            ),
+        )
+        session.add_message("user", "visible preview")
+        mgr.save(session)
+
+        assert mgr.list_sessions()[0]["preview"] == "visible preview"
+
+    def test_clear_and_fork_discard_provider_state(self, tmp_path: Path):
+        mgr = SessionManager(tmp_path)
+        state = ProviderConversationState(
+            kind="openai_responses",
+            provider="openai:test",
+            model="gpt-5.6",
+            version=1,
+            payload={"items": []},
+        )
+        source = Session(key="test:state-source", provider_state=state)
+        source.add_message("user", "hello")
+        mgr.save(source)
+
+        fork = mgr.fork_session_before_user_index(
+            source.key,
+            "test:state-fork",
+            1,
+        )
+        assert fork is not None
+        assert fork.provider_state is None
+
+        source.clear()
+        assert source.provider_state is None
+
+    def test_invalid_provider_state_record_is_not_public_history(self, tmp_path: Path):
+        mgr = SessionManager(tmp_path)
+        path = mgr._get_session_path("test:bad-provider-state")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            "\n".join(
+                [
+                    json.dumps(
+                        {
+                            "_type": "metadata",
+                            "key": "test:bad-provider-state",
+                            "created_at": datetime.now().isoformat(),
+                            "updated_at": datetime.now().isoformat(),
+                            "metadata": {},
+                            "last_consolidated": 0,
+                        }
+                    ),
+                    json.dumps(
+                        {
+                            "_type": "provider_state",
+                            "state": {"kind": "openai_responses"},
+                        }
+                    ),
+                    json.dumps({"role": "user", "content": "safe"}),
+                ]
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+
+        loaded = mgr._load("test:bad-provider-state")
+        assert loaded is not None
+        assert loaded.provider_state is None
+        assert loaded.messages == [{"role": "user", "content": "safe"}]
+
 
 class TestRepairCorruptFile:
     def _write_corrupt_jsonl(self, path: Path, lines: list[str]) -> None:

tests/agent/test_session_lock_lifecycle.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import asyncio
+import gc
+from unittest.mock import MagicMock
+
+import pytest
+
+
+def _make_loop(loop_factory):
+    provider = MagicMock()
+    provider.get_default_model.return_value = "test-model"
+    return loop_factory(provider=provider)
+
+
+def test_idle_agent_session_locks_are_released(loop_factory):
+    loop = _make_loop(loop_factory)
+
+    for index in range(1000):
+        lock = loop._get_session_lock(f"api:temporary-{index}")
+
+    del lock
+    gc.collect()
+
+    assert len(loop._session_locks) == 0
+
+
+@pytest.mark.asyncio
+async def test_waiter_keeps_agent_session_lock_alive(loop_factory):
+    loop = _make_loop(loop_factory)
+    owner_lock = loop._get_session_lock("api:shared")
+    await owner_lock.acquire()
+    waiter_started = asyncio.Event()
+    waiter_entered = asyncio.Event()
+
+    async def wait_for_lock() -> None:
+        lock = loop._get_session_lock("api:shared")
+        waiter_started.set()
+        async with lock:
+            waiter_entered.set()
+
+    waiter = asyncio.create_task(wait_for_lock())
+    await waiter_started.wait()
+
+    assert loop._get_session_lock("api:shared") is owner_lock
+    assert not waiter_entered.is_set()
+
+    owner_lock.release()
+    await waiter
+    del owner_lock
+    gc.collect()
+
+    assert "api:shared" not in loop._session_locks

tests/agent/test_session_manager_history.py

@@ -1,3 +1,4 @@
+from nanobot.providers.base import ProviderConversationState
 from nanobot.runtime_context import (
     RUNTIME_CONTEXT_HISTORY_META,
     RuntimeContextBlock,
@@ -769,7 +770,16 @@ def test_get_history_extend_to_user_keeps_newer_user_inside_window():
 
 def test_retain_recent_legal_suffix_returns_dropped_messages():
     """retain_recent_legal_suffix returns the actually-dropped messages."""
-    session = Session(key="test:return-dropped")
+    session = Session(
+        key="test:return-dropped",
+        provider_state=ProviderConversationState(
+            kind="openai_responses",
+            provider="openai:test",
+            model="test-model",
+            version=1,
+            payload={"items": []},
+        ),
+    )
     for i in range(10):
         session.messages.append({"role": "user", "content": f"msg{i}"})
 
@@ -779,11 +789,19 @@ def test_retain_recent_legal_suffix_returns_dropped_messages():
     assert [m["content"] for m in result.dropped] == [f"msg{i}" for i in range(6)]
     assert len(session.messages) == 4
     assert result.already_consolidated_count == 0
+    assert session.provider_state is None
 
 
 def test_retain_recent_legal_suffix_returns_empty_when_no_drop():
     """No messages dropped → empty list returned."""
-    session = Session(key="test:no-drop")
+    state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="test-model",
+        version=1,
+        payload={"items": []},
+    )
+    session = Session(key="test:no-drop", provider_state=state)
     for i in range(3):
         session.messages.append({"role": "user", "content": f"msg{i}"})
 
@@ -792,6 +810,7 @@ def test_retain_recent_legal_suffix_returns_empty_when_no_drop():
     assert result.dropped == []
     assert result.already_consolidated_count == 0
     assert len(session.messages) == 3
+    assert session.provider_state is state
 
 
 def test_retain_recent_legal_suffix_returns_all_on_zero():

tests/agent/test_session_model_runtime.py

@@ -65,7 +65,7 @@ async def test_sessions_run_concurrently_with_isolated_model_presets(tmp_path) -
         model_presets=presets,
         preset_snapshot_loader=load_preset,
     )
-    loop._schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
+    loop.schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
     loop.set_session_model_preset("sdk:fast", "fast")
     loop.set_session_model_preset("sdk:deep", "deep")
 
@@ -116,7 +116,7 @@ async def test_removed_session_model_preset_falls_back_and_clears_metadata(tmp_p
         model="base-model",
         context_window_tokens=8_000,
     )
-    loop._schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
+    loop.schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
     session_key = "sdk:removed-preset"
     session = loop.sessions.get_or_create(session_key)
     session.metadata[SESSION_MODEL_PRESET_METADATA_KEY] = "removed"
@@ -161,7 +161,7 @@ async def test_streamed_sdk_resolves_session_runtime_after_lock_admission(tmp_pa
         model_presets=presets,
         preset_snapshot_loader=load_preset,
     )
-    loop._schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
+    loop.schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
     session_key = "sdk:queued"
     loop.set_session_model_preset(session_key, "fast")
 
@@ -198,7 +198,7 @@ async def test_sdk_custom_model_preset_metadata_does_not_select_runtime(
         model="base-model",
         context_window_tokens=8_000,
     )
-    loop._schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
+    loop.schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
     bot = Nanobot(loop)
 
     await bot.sessions.ingest(
@@ -239,7 +239,7 @@ async def test_sdk_invalid_internal_model_preset_metadata_fails_explicitly(
         model="base-model",
         context_window_tokens=8_000,
     )
-    loop._schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
+    loop.schedule_background = lambda coro: coro.close()  # type: ignore[method-assign]
     bot = Nanobot(loop)
 
     await bot.sessions.ingest(

tests/agent/test_skills_loader.py

@@ -8,7 +8,6 @@ from pathlib import Path
 import pytest
 
 from nanobot.agent.skills import SkillsLoader
-from nanobot.resource_links import ResourceView
 
 
 def _write_skill(
@@ -316,41 +315,6 @@ def test_build_skills_summary_groups_paths_by_root(tmp_path: Path) -> None:
     assert "`beta/SKILL.md`" in summary
 
 
-def test_build_skills_summary_uses_alias_roots_but_keeps_canonical_entries(
-    tmp_path: Path,
-) -> None:
-    workspace = tmp_path / "ws"
-    workspace_skills = workspace / "skills"
-    workspace_skills.mkdir(parents=True)
-    workspace_path = _write_skill(workspace_skills, "alpha", body="# Alpha")
-    builtin = tmp_path / "builtin"
-    builtin_path = _write_skill(builtin, "beta", body="# Beta")
-    aliases = tmp_path / "resources" / "view"
-    resource_view = ResourceView(
-        root=aliases,
-        agent=aliases / "agent",
-        media=aliases / "media",
-        package=aliases / "package",
-    )
-
-    loader = SkillsLoader(
-        workspace,
-        builtin_skills_dir=builtin,
-        resource_view=resource_view,
-    )
-    entries = loader.list_skills(filter_unavailable=False)
-    summary = loader.build_skills_summary()
-
-    assert {entry["path"] for entry in entries} == {
-        str(workspace_path),
-        str(builtin_path),
-    }
-    assert f"`{resource_view.agent / 'skills'}`" in summary
-    assert f"`{resource_view.package / 'skills'}`" in summary
-    assert str(workspace_path) not in summary
-    assert str(builtin_path) not in summary
-
-
 def test_bundled_update_setup_description_is_valid_yaml(tmp_path: Path) -> None:
     metadata = SkillsLoader(tmp_path).get_skill_metadata("update-setup")
 

tests/agent/test_subagent.py

@@ -11,7 +11,6 @@ from nanobot.agent.tools.filesystem import FileToolsConfig
 from nanobot.bus.queue import MessageBus
 from nanobot.config.schema import ToolsConfig
 from nanobot.providers.base import GenerationSettings, LLMProvider
-from nanobot.resource_links import ResourceView
 from nanobot.security.workspace_access import build_workspace_scope
 from nanobot.utils.llm_runtime import LLMRuntime
 
@@ -110,51 +109,6 @@ def test_subagent_prompt_explains_grouped_skill_paths(tmp_path):
     assert "project-custom" not in prompt
 
 
-def test_subagent_prompt_uses_restricted_resource_aliases(tmp_path):
-    agent_workspace = tmp_path / "agent"
-    aliases = tmp_path / "resources" / "view"
-    resource_view = ResourceView(
-        root=aliases,
-        agent=aliases / "agent",
-        media=aliases / "media",
-        package=aliases / "package",
-    )
-    manager = SubagentManager(
-        workspace=agent_workspace,
-        bus=MessageBus(),
-        max_tool_result_chars=16_000,
-        resource_view=resource_view,
-    )
-
-    prompt = manager._build_subagent_prompt(resource_view_mode="restricted")
-
-    assert f"Custom skills: `{resource_view.agent / 'skills'}`" in prompt
-    assert f"Media: `{resource_view.media}`" in prompt
-    assert f"Built-in skills: `{resource_view.package / 'skills'}`" in prompt
-    assert f"Agent workspace: `{resource_view.agent}`" not in prompt
-    assert f"Nanobot package: `{resource_view.package}`" not in prompt
-    assert f"History log: {agent_workspace.resolve() / 'memory' / 'history.jsonl'}" in prompt
-
-
-def test_subagent_prompt_uses_agent_alias_for_full_history_path(tmp_path):
-    agent_workspace = tmp_path / "agent"
-    aliases = tmp_path / "resources" / "view"
-    resource_view = ResourceView(
-        root=aliases,
-        agent=aliases / "agent",
-    )
-    manager = SubagentManager(
-        workspace=agent_workspace,
-        bus=MessageBus(),
-        max_tool_result_chars=16_000,
-        resource_view=resource_view,
-    )
-
-    prompt = manager._build_subagent_prompt(resource_view_mode="full")
-
-    assert f"History log: {resource_view.agent / 'memory' / 'history.jsonl'}" in prompt
-
-
 @pytest.mark.asyncio
 async def test_subagent_keeps_project_runtime_scope_with_agent_owned_tools(tmp_path):
     agent_workspace = tmp_path / "agent"

tests/agent/test_unified_session.py

@@ -246,7 +246,7 @@ class TestCmdNewUnifiedSession:
         assert len(sessions.get_or_create("unified:default").messages) == 2
         expected_snapshot = list(shared.messages)
 
-        # _schedule_background is a *sync* method that schedules a coroutine via
+        # schedule_background is a *sync* method that schedules a coroutine via
         # asyncio.create_task().  Mirror that exactly so the coroutine is consumed
         # and no RuntimeWarning is emitted.
         admitted_runtime = MagicMock(name="admitted_runtime")
@@ -255,8 +255,8 @@ class TestCmdNewUnifiedSession:
             consolidator=SimpleNamespace(archive=AsyncMock(return_value=True)),
             _cancel_active_tasks=AsyncMock(return_value=0),
             llm_runtime=MagicMock(return_value=MagicMock()),
+            schedule_background=lambda coro: asyncio.ensure_future(coro),
         )
-        loop._schedule_background = lambda coro: asyncio.ensure_future(coro)
 
         msg = InboundMessage(
             channel="telegram", sender_id="user1", chat_id="111", content="/new",
@@ -303,8 +303,8 @@ class TestCmdNewUnifiedSession:
             consolidator=SimpleNamespace(archive=AsyncMock(return_value=True)),
             _cancel_active_tasks=AsyncMock(return_value=0),
             runtime_for_session=MagicMock(return_value=MagicMock()),
+            schedule_background=lambda coro: asyncio.ensure_future(coro),
         )
-        loop._schedule_background = lambda coro: asyncio.ensure_future(coro)
 
         msg = InboundMessage(
             channel="telegram", sender_id="user1", chat_id="111", content="/new",

tests/agent/tools/test_subagent_tools.py

@@ -504,6 +504,7 @@ async def test_drain_pending_blocks_while_subagents_running(tmp_path):
             usage={},
             had_injections=False,
             tools_used=[],
+            provider_state=None,
         )
 
     loop.runner.run = AsyncMock(side_effect=fake_runner_run)
@@ -589,6 +590,7 @@ async def test_drain_pending_no_block_when_no_subagents(tmp_path):
             usage={},
             had_injections=False,
             tools_used=[],
+            provider_state=None,
         )
 
     loop.runner.run = AsyncMock(side_effect=fake_runner_run)
@@ -638,6 +640,7 @@ async def test_drain_pending_timeout(tmp_path):
             usage={},
             had_injections=False,
             tools_used=[],
+            provider_state=None,
         )
 
     loop.runner.run = AsyncMock(side_effect=fake_runner_run)

tests/channels/test_base_channel.py

@@ -83,6 +83,49 @@ async def test_handle_message_dm_sends_pairing_code(monkeypatch) -> None:
     assert msg.metadata.get("_pairing_code") == "ABCD-EFGH"
 
 
+@pytest.mark.asyncio
+async def test_dm_during_transient_store_failure_keeps_approvals(
+    tmp_path, monkeypatch
+) -> None:
+    """An unapproved DM while pairing.json is unreadable must not wipe approvals.
+
+    The pairing store treated a transient OSError like corruption and returned
+    an empty store; the DM pairing path then persisted that empty view,
+    erasing every approved sender.
+    """
+    import builtins
+    from pathlib import Path
+
+    from nanobot.pairing import store
+
+    path = tmp_path / "pairing.json"
+    monkeypatch.setattr(store, "_store_path", lambda: path)
+    code = store.generate_code("dummy", "friend")
+    store.approve_code(code)
+
+    channel = _DummyChannel({"allowFrom": []}, MessageBus())
+
+    real_open = builtins.open
+
+    def flaky_open(file, mode="r", *args, **kwargs):
+        try:
+            same = Path(file) == path
+        except TypeError:
+            same = False
+        if same and "r" in mode and "+" not in mode:
+            raise PermissionError(13, "temporarily locked", str(path))
+        return real_open(file, mode, *args, **kwargs)
+
+    with monkeypatch.context() as m:
+        m.setattr(builtins, "open", flaky_open)
+        await channel._handle_message(
+            sender_id="stranger", chat_id="chat1", content="hello", is_dm=True
+        )
+
+    assert channel._sent == []
+    assert store.is_approved("dummy", "friend") is True
+
+
 @pytest.mark.asyncio
 async def test_handle_message_group_ignores_unknown() -> None:
     channel = _DummyChannel({"allowFrom": []}, MessageBus())

tests/cli/test_cli_input.py

@@ -5,8 +5,8 @@ from unittest.mock import AsyncMock, MagicMock, call, patch
 import pytest
 from prompt_toolkit.formatted_text import HTML
 
-from nanobot.cli import commands
 from nanobot.cli import stream as stream_mod
+from nanobot.cli import terminal
 
 
 @pytest.fixture
@@ -14,8 +14,8 @@ def mock_prompt_session():
     """Mock the global prompt session."""
     mock_session = MagicMock()
     mock_session.prompt_async = AsyncMock()
-    with patch("nanobot.cli.commands._PROMPT_SESSION", mock_session), \
-         patch("nanobot.cli.commands.patch_stdout"):
+    with patch("nanobot.cli.terminal._prompt_session", mock_session), \
+         patch("nanobot.cli.terminal.patch_stdout"):
         yield mock_session
 
 
@@ -24,7 +24,7 @@ async def test_read_interactive_input_async_returns_input(mock_prompt_session):
     """Test that _read_interactive_input_async returns the user input from prompt_session."""
     mock_prompt_session.prompt_async.return_value = "hello world"
 
-    result = await commands._read_interactive_input_async()
+    result = await terminal._read_interactive_input_async()
 
     assert result == "hello world"
     mock_prompt_session.prompt_async.assert_called_once()
@@ -38,23 +38,23 @@ async def test_read_interactive_input_async_handles_eof(mock_prompt_session):
     mock_prompt_session.prompt_async.side_effect = EOFError()
 
     with pytest.raises(KeyboardInterrupt):
-        await commands._read_interactive_input_async()
+        await terminal._read_interactive_input_async()
 
 
 def test_init_prompt_session_creates_session():
     """Test that _init_prompt_session initializes the global session."""
     # Ensure global is None before test
-    commands._PROMPT_SESSION = None
+    terminal._prompt_session = None
 
-    with patch("nanobot.cli.commands.PromptSession") as mock_session_cls, \
-         patch("nanobot.cli.commands.FileHistory"), \
+    with patch("nanobot.cli.terminal.PromptSession") as mock_session_cls, \
+         patch("nanobot.cli.terminal.FileHistory"), \
          patch("pathlib.Path.home") as mock_home:
 
         mock_home.return_value = MagicMock()
 
-        commands._init_prompt_session()
+        terminal._init_prompt_session()
 
-        assert commands._PROMPT_SESSION is not None
+        assert terminal._prompt_session is not None
         mock_session_cls.assert_called_once()
         _, kwargs = mock_session_cls.call_args
         # Buffer is multiline-capable so Alt+Enter can insert newlines;
@@ -68,7 +68,7 @@ def test_cli_key_bindings_enter_submits_and_alt_enter_newlines():
     """Enter submits the buffer; Alt+Enter inserts a newline."""
     from prompt_toolkit.keys import Keys
 
-    kb = commands._build_cli_key_bindings()
+    kb = terminal._build_cli_key_bindings()
 
     def _keys(binding):
         return tuple(getattr(k, "value", k) for k in binding.keys)
@@ -102,8 +102,8 @@ async def test_raw_lf_enter_still_submits_like_wsl_terminals():
 
     with create_pipe_input() as pipe_input:
         with create_app_session(input=pipe_input, output=DummyOutput()):
-            commands._init_prompt_session()
-            session = commands._PROMPT_SESSION
+            terminal._init_prompt_session()
+            session = terminal._prompt_session
             pipe_input.send_text("hello\x0aworld\r")
             result = await session.prompt_async("> ")
 
@@ -119,8 +119,8 @@ async def test_alt_enter_inserts_newline_on_lf_terminals():
 
     with create_pipe_input() as pipe_input:
         with create_app_session(input=pipe_input, output=DummyOutput()):
-            commands._init_prompt_session()
-            session = commands._PROMPT_SESSION
+            terminal._init_prompt_session()
+            session = terminal._prompt_session
             pipe_input.send_text("foo\x1b\x0abar\r")
             result = await session.prompt_async("> ")
 
@@ -136,8 +136,8 @@ async def test_csi_u_shift_enter_inserts_newline_not_raw_escape():
 
     with create_pipe_input() as pipe_input:
         with create_app_session(input=pipe_input, output=DummyOutput()):
-            commands._init_prompt_session()
-            session = commands._PROMPT_SESSION
+            terminal._init_prompt_session()
+            session = terminal._prompt_session
             pipe_input.send_text("foo\x1b[13;2ubar\r")
             result = await session.prompt_async("> ")
 
@@ -173,10 +173,10 @@ def test_print_cli_progress_line_pauses_spinner_before_printing():
     mock_console = MagicMock()
     mock_console.status.return_value = spinner
 
-    with patch.object(commands.console, "print", side_effect=lambda *_args, **_kwargs: order.append("print")):
+    with patch.object(terminal.console, "print", side_effect=lambda *_args, **_kwargs: order.append("print")):
         thinking = stream_mod.ThinkingSpinner(console=mock_console)
         with thinking:
-            commands._print_cli_progress_line("tool running", thinking)
+            terminal._print_cli_progress_line("tool running", thinking)
 
     assert order == ["start", "stop", "print", "start", "stop"]
 
@@ -224,7 +224,7 @@ def test_print_cli_progress_line_opens_renderer_header_before_trace():
     renderer.ensure_header.side_effect = lambda: order.append("header")
     renderer.pause_spinner.return_value = nullcontext()
 
-    commands._print_cli_progress_line("tool running", None, renderer)
+    terminal._print_cli_progress_line("tool running", None, renderer)
 
     assert order == ["header", "print"]
 
@@ -235,7 +235,7 @@ def test_print_cli_progress_line_stops_live_before_trace():
     renderer = stream_mod.StreamRenderer(show_spinner=False)
     renderer._live = mock_live
 
-    commands._print_cli_progress_line("tool running", None, renderer)
+    terminal._print_cli_progress_line("tool running", None, renderer)
 
     mock_live.stop.assert_called_once()
     assert renderer._live is None
@@ -254,10 +254,10 @@ async def test_print_interactive_progress_line_pauses_spinner_before_printing():
     async def fake_print(_text: str) -> None:
         order.append("print")
 
-    with patch("nanobot.cli.commands._print_interactive_line", side_effect=fake_print):
+    with patch("nanobot.cli.terminal._print_interactive_line", side_effect=fake_print):
         thinking = stream_mod.ThinkingSpinner(console=mock_console)
         with thinking:
-            await commands._print_interactive_progress_line("tool running", thinking)
+            await terminal._print_interactive_progress_line("tool running", thinking)
 
     assert order == ["start", "stop", "print", "start", "stop"]
 
@@ -269,7 +269,7 @@ def test_response_renderable_uses_text_for_explicit_plain_rendering():
         "📊 Tokens: 20639 in / 29 out"
     )
 
-    renderable = commands._response_renderable(
+    renderable = terminal._response_renderable(
         status,
         render_markdown=True,
         metadata={"render_as": "text"},
@@ -279,7 +279,7 @@ def test_response_renderable_uses_text_for_explicit_plain_rendering():
 
 
 def test_response_renderable_preserves_normal_markdown_rendering():
-    renderable = commands._response_renderable("**bold**", render_markdown=True)
+    renderable = terminal._response_renderable("**bold**", render_markdown=True)
 
     assert renderable.__class__.__name__ == "Markdown"
 
@@ -287,7 +287,7 @@ def test_response_renderable_preserves_normal_markdown_rendering():
 def test_response_renderable_without_metadata_keeps_markdown_path():
     help_text = "🐈 nanobot commands:\n/status — Show bot status\n/help — Show available commands"
 
-    renderable = commands._response_renderable(help_text, render_markdown=True)
+    renderable = terminal._response_renderable(help_text, render_markdown=True)
 
     assert renderable.__class__.__name__ == "Markdown"
 
@@ -389,9 +389,9 @@ def test_render_interactive_ansi_force_terminal_follows_isatty():
         captured["console"] = c
 
     with patch.object(sys.stdout, "isatty", return_value=True):
-        commands._render_interactive_ansi(render_fn)
+        terminal._render_interactive_ansi(render_fn)
         assert captured["console"]._force_terminal is True
 
     with patch.object(sys.stdout, "isatty", return_value=False):
-        commands._render_interactive_ansi(render_fn)
+        terminal._render_interactive_ansi(render_fn)
         assert captured["console"]._force_terminal is False

tests/cli/test_commands.py

@@ -17,6 +17,11 @@ from nanobot.agent.tools.registry import ToolRegistry
 from nanobot.agent.turn_delivery import TurnDeliveryFactory
 from nanobot.bus.events import InboundMessage, OutboundMessage
 from nanobot.cli import commands as cli_commands
+from nanobot.cli import gateway_runtime as cli_gateway_runtime
+from nanobot.cli import provider as provider_commands
+from nanobot.cli import terminal as cli_terminal
+from nanobot.cli import webui as cli_webui
+from nanobot.cli import webui_support as cli_webui_support
 from nanobot.cli.commands import app
 from nanobot.config.schema import Config
 from nanobot.cron.service import CronJobSkippedError
@@ -113,7 +118,7 @@ def test_gateway_signal_handler_first_signal_stops_and_second_forces() -> None:
         task = asyncio.create_task(never.wait())
         output: list[str] = []
 
-        restore = cli_commands._install_gateway_shutdown_handlers(
+        restore = cli_gateway_runtime._install_gateway_shutdown_handlers(
             loop, shutdown_event, [task], output.append,
         )
         try:
@@ -161,8 +166,8 @@ def test_interactive_tty_mode_restores_line_input(monkeypatch) -> None:
         attrs[3] &= ~(termios.ISIG | termios.ICANON | termios.ECHO)
         termios.tcsetattr(slave_fd, termios.TCSANOW, attrs)
 
-        monkeypatch.setattr(cli_commands.sys, "stdin", _Stdin())
-        cli_commands._ensure_interactive_tty_mode()
+        monkeypatch.setattr(cli_terminal.sys, "stdin", _Stdin())
+        cli_terminal._ensure_interactive_tty_mode()
 
         restored = termios.tcgetattr(slave_fd)
         assert restored[0] & termios.ICRNL
@@ -179,24 +184,24 @@ def test_webui_restores_tty_before_loading_config(monkeypatch, tmp_path: Path) -
     config_file = tmp_path / "config.json"
     config_file.write_text("{}", encoding="utf-8")
     calls: list[str] = []
-    original_resolve = cli_commands._resolve_webui_config_path
+    original_resolve = cli_webui._resolve_webui_config_path
 
     monkeypatch.setattr(
-        cli_commands,
+        cli_terminal,
         "_ensure_interactive_tty_mode",
         lambda: calls.append("tty"),
     )
     monkeypatch.setattr(
-        cli_commands,
+        cli_webui,
         "_resolve_webui_config_path",
         lambda path: calls.append("config") or original_resolve(path),
     )
     _patch_webui_provider_ready(monkeypatch)
-    monkeypatch.setattr(cli_commands, "sync_workspace_templates", lambda _path: None)
-    monkeypatch.setattr(cli_commands, "_gateway_health_ready", lambda *_args, **_kwargs: False)
-    monkeypatch.setattr(cli_commands, "_webui_endpoint_reachable", lambda *_args, **_kwargs: False)
-    monkeypatch.setattr(cli_commands, "_tcp_endpoint_reachable", lambda *_args, **_kwargs: False)
-    monkeypatch.setattr(cli_commands, "_run_gateway", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(cli_webui, "sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr(cli_webui, "_gateway_health_ready", lambda *_args, **_kwargs: False)
+    monkeypatch.setattr(cli_webui, "_webui_endpoint_reachable", lambda *_args, **_kwargs: False)
+    monkeypatch.setattr(cli_webui, "_tcp_endpoint_reachable", lambda *_args, **_kwargs: False)
+    monkeypatch.setattr(cli_webui, "_run_gateway", lambda *_args, **_kwargs: None)
 
     result = runner.invoke(app, ["webui", "--config", str(config_file), "--yes", "--no-open"])
 
@@ -209,11 +214,11 @@ def test_disabled_dream_cursor_only_advances_when_behind(tmp_path) -> None:
     store.append_history("first")
     store.append_history("second")
 
-    cli_commands._advance_dream_cursor_if_behind(store)
+    cli_gateway_runtime._advance_dream_cursor_if_behind(store)
     assert store.get_last_dream_cursor() == 2
 
     store.set_last_dream_cursor(10)
-    cli_commands._advance_dream_cursor_if_behind(store)
+    cli_gateway_runtime._advance_dream_cursor_if_behind(store)
     assert store.get_last_dream_cursor() == 10
 
 
@@ -225,7 +230,7 @@ def test_commit_dream_changes_skips_noop_run(tmp_path) -> None:
     store.git.auto_commit("initial")
     store.git.auto_commit = MagicMock(wraps=store.git.auto_commit)
 
-    assert cli_commands._commit_dream_changes(store) is None
+    assert cli_gateway_runtime._commit_dream_changes(store) is None
     store.git.auto_commit.assert_not_called()
 
 
@@ -238,7 +243,7 @@ def test_commit_dream_changes_commits_real_edits(tmp_path) -> None:
     store.write_memory("# Memory\n- Research notes")
     store.git.auto_commit = MagicMock(wraps=store.git.auto_commit)
 
-    sha = cli_commands._commit_dream_changes(store)
+    sha = cli_gateway_runtime._commit_dream_changes(store)
 
     assert sha is not None
     store.git.auto_commit.assert_called_once()
@@ -390,7 +395,7 @@ def test_status_help_shows_workspace_and_config_options():
     assert "-c" in stripped_output
 
 
-def test_status_uses_explicit_config_and_workspace(tmp_path: Path, monkeypatch):
+def test_status_uses_explicit_config_and_workspace(tmp_path: Path):
     config_path = tmp_path / "instance" / "config.json"
     config_workspace = tmp_path / "config-workspace"
     override_workspace = tmp_path / "override-workspace"
@@ -398,11 +403,6 @@ def test_status_uses_explicit_config_and_workspace(tmp_path: Path, monkeypatch):
     config.agents.defaults.workspace = str(config_workspace)
     config_path.parent.mkdir(parents=True)
     config_path.write_text(json.dumps(config.model_dump(mode="json", by_alias=True)))
-    monkeypatch.setattr(
-        cli_commands,
-        "_prepare_resource_view",
-        lambda _config: pytest.fail("status must not prepare runtime resource links"),
-    )
 
     result = runner.invoke(
         app,
@@ -417,58 +417,6 @@ def test_status_uses_explicit_config_and_workspace(tmp_path: Path, monkeypatch):
     assert str(config_workspace) not in compact_output
 
 
-def test_prepare_resource_view_uses_active_config_and_workspace(
-    monkeypatch,
-    tmp_path: Path,
-) -> None:
-    from nanobot import resource_links
-
-    config_path = (tmp_path / "instance" / "config.json").resolve()
-    workspace = (tmp_path / "workspace").resolve()
-    config = Config()
-    config.agents.defaults.workspace = str(workspace)
-    expected = SimpleNamespace(warnings=())
-    captured: dict[str, Path] = {}
-
-    monkeypatch.setattr(
-        "nanobot.config.loader.get_config_path",
-        lambda: config_path,
-    )
-
-    def _fake_ensure_resource_view(**kwargs):
-        captured.update(kwargs)
-        return expected
-
-    monkeypatch.setattr(resource_links, "ensure_resource_view", _fake_ensure_resource_view)
-
-    assert cli_commands._prepare_resource_view(config) is expected
-    assert captured == {
-        "data_dir": config_path.parent,
-        "config_path": config_path,
-        "agent_workspace": workspace,
-    }
-
-
-def test_prepare_resource_view_failure_does_not_block_runtime(
-    monkeypatch,
-    tmp_path: Path,
-) -> None:
-    from nanobot import resource_links
-
-    config_path = tmp_path / "config.json"
-    monkeypatch.setattr(
-        "nanobot.config.loader.get_config_path",
-        lambda: config_path,
-    )
-
-    def _fail(**_kwargs):
-        raise OSError("read-only filesystem")
-
-    monkeypatch.setattr(resource_links, "ensure_resource_view", _fail)
-
-    assert cli_commands._prepare_resource_view(Config()) is None
-
-
 def test_onboard_interactive_discard_does_not_save_or_create_workspace(mock_paths, monkeypatch):
     config_file, workspace_dir, _ = mock_paths
 
@@ -550,7 +498,7 @@ def test_openai_codex_oauth_default_matches_curated_flagship():
 
     assert spec is not None
     assert spec.builtin_models
-    assert cli_commands._OAUTH_PROVIDER_DEFAULT_MODELS["openai_codex"] == (
+    assert provider_commands._OAUTH_PROVIDER_DEFAULT_MODELS["openai_codex"] == (
         spec.builtin_models[0].id
     )
 
@@ -728,16 +676,28 @@ def test_provider_login_rejects_unknown_provider():
     assert "Unknown OAuth provider" in result.stdout
 
 
+def test_provider_login_openai_codex_handles_missing_oauth_symbol(monkeypatch):
+    import oauth_cli_kit
+
+    monkeypatch.delattr(oauth_cli_kit, "get_token")
+
+    result = runner.invoke(app, ["provider", "login", "openai-codex"])
+
+    assert result.exit_code == 1
+    assert "oauth_cli_kit not installed" in result.stdout
+    assert result.exception is not None
+
+
 def test_provider_login_can_set_openai_codex_as_main_provider(tmp_path):
     config_path = tmp_path / "config.json"
     called = False
-    original = cli_commands._LOGIN_HANDLERS["openai_codex"]
+    original = provider_commands._LOGIN_HANDLERS["openai_codex"]
 
     def fake_login() -> None:
         nonlocal called
         called = True
 
-    cli_commands._LOGIN_HANDLERS["openai_codex"] = fake_login
+    provider_commands._LOGIN_HANDLERS["openai_codex"] = fake_login
     try:
         result = runner.invoke(
             app,
@@ -751,7 +711,7 @@ def test_provider_login_can_set_openai_codex_as_main_provider(tmp_path):
             ],
         )
     finally:
-        cli_commands._LOGIN_HANDLERS["openai_codex"] = original
+        provider_commands._LOGIN_HANDLERS["openai_codex"] = original
 
     assert result.exit_code == 0
     assert called is True
@@ -766,8 +726,8 @@ def test_provider_login_can_set_openai_codex_as_main_provider(tmp_path):
 
 def test_provider_login_can_set_github_copilot_as_main_provider(tmp_path):
     config_path = tmp_path / "config.json"
-    original = cli_commands._LOGIN_HANDLERS["github_copilot"]
-    cli_commands._LOGIN_HANDLERS["github_copilot"] = lambda: None
+    original = provider_commands._LOGIN_HANDLERS["github_copilot"]
+    provider_commands._LOGIN_HANDLERS["github_copilot"] = lambda: None
     try:
         result = runner.invoke(
             app,
@@ -781,7 +741,7 @@ def test_provider_login_can_set_github_copilot_as_main_provider(tmp_path):
             ],
         )
     finally:
-        cli_commands._LOGIN_HANDLERS["github_copilot"] = original
+        provider_commands._LOGIN_HANDLERS["github_copilot"] = original
 
     assert result.exit_code == 0
     assert "Set github-copilot as the main provider" in result.stdout
@@ -795,8 +755,8 @@ def test_provider_login_can_set_github_copilot_as_main_provider(tmp_path):
 
 def test_provider_login_can_set_xai_grok_as_main_provider(tmp_path):
     config_path = tmp_path / "config.json"
-    original = cli_commands._LOGIN_HANDLERS["xai_grok"]
-    cli_commands._LOGIN_HANDLERS["xai_grok"] = lambda: None
+    original = provider_commands._LOGIN_HANDLERS["xai_grok"]
+    provider_commands._LOGIN_HANDLERS["xai_grok"] = lambda: None
     try:
         result = runner.invoke(
             app,
@@ -810,7 +770,7 @@ def test_provider_login_can_set_xai_grok_as_main_provider(tmp_path):
             ],
         )
     finally:
-        cli_commands._LOGIN_HANDLERS["xai_grok"] = original
+        provider_commands._LOGIN_HANDLERS["xai_grok"] = original
 
     assert result.exit_code == 0
     assert "Set xai-grok as the main provider" in result.stdout
@@ -825,8 +785,8 @@ def test_provider_login_can_set_xai_grok_as_main_provider(tmp_path):
 
 def test_provider_login_model_implies_set_main_provider(tmp_path):
     config_path = tmp_path / "config.json"
-    original = cli_commands._LOGIN_HANDLERS["github_copilot"]
-    cli_commands._LOGIN_HANDLERS["github_copilot"] = lambda: None
+    original = provider_commands._LOGIN_HANDLERS["github_copilot"]
+    provider_commands._LOGIN_HANDLERS["github_copilot"] = lambda: None
     try:
         result = runner.invoke(
             app,
@@ -841,7 +801,7 @@ def test_provider_login_model_implies_set_main_provider(tmp_path):
             ],
         )
     finally:
-        cli_commands._LOGIN_HANDLERS["github_copilot"] = original
+        provider_commands._LOGIN_HANDLERS["github_copilot"] = original
 
     assert result.exit_code == 0
     assert "Set github-copilot as the main provider" in result.stdout
@@ -1524,20 +1484,15 @@ def mock_agent_runtime(tmp_path):
     """Mock agent command dependencies for focused CLI tests."""
     config = Config()
     config.agents.defaults.workspace = str(tmp_path / "default-workspace")
-    resource_view = object()
 
     with patch("nanobot.config.loader.load_config", return_value=config) as mock_load_config, \
          patch("nanobot.config.loader.resolve_config_env_vars", side_effect=lambda c: c), \
-         patch("nanobot.cli.commands.sync_workspace_templates") as mock_sync_templates, \
-         patch(
-             "nanobot.cli.commands._prepare_resource_view",
-             return_value=resource_view,
-         ) as mock_prepare_resource_view, \
+         patch("nanobot.cli.agent.sync_workspace_templates") as mock_sync_templates, \
          patch("nanobot.providers.factory.make_provider", return_value=_fake_provider()), \
-         patch("nanobot.cli.commands._print_agent_response") as mock_print_response, \
+         patch("nanobot.cli.terminal._print_agent_response") as mock_print_response, \
          patch("nanobot.bus.queue.MessageBus"), \
          patch("nanobot.cron.service.CronService"), \
-         patch("nanobot.cli.commands.AgentLoop.from_config") as mock_from_config:
+         patch("nanobot.cli.agent.AgentLoop.from_config") as mock_from_config:
         agent_loop = MagicMock()
         agent_loop.channels_config = None
         agent_loop.process_direct = AsyncMock(
@@ -1550,8 +1505,6 @@ def mock_agent_runtime(tmp_path):
             "config": config,
             "load_config": mock_load_config,
             "sync_templates": mock_sync_templates,
-            "prepare_resource_view": mock_prepare_resource_view,
-            "resource_view": resource_view,
             "from_config": mock_from_config,
             "agent_loop": agent_loop,
             "print_response": mock_print_response,
@@ -1579,9 +1532,6 @@ def test_agent_uses_default_config_when_no_workspace_or_config_flags(mock_agent_
     )
     passed_config = mock_agent_runtime["from_config"].call_args.args[0]
     assert passed_config.workspace_path == mock_agent_runtime["config"].workspace_path
-    assert mock_agent_runtime["from_config"].call_args.kwargs["resource_view"] is (
-        mock_agent_runtime["resource_view"]
-    )
     mock_agent_runtime["agent_loop"].process_direct.assert_awaited_once()
     mock_agent_runtime["print_response"].assert_called_once_with(
         "mock-response", render_markdown=True, metadata={},
@@ -1611,8 +1561,7 @@ def test_agent_config_sets_active_path(monkeypatch, tmp_path: Path) -> None:
         lambda path: seen.__setitem__("config_path", path),
     )
     monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
-    monkeypatch.setattr("nanobot.cli.commands._prepare_resource_view", lambda _config: None)
+    monkeypatch.setattr("nanobot.cli.agent.sync_workspace_templates", lambda _path: None)
     monkeypatch.setattr("nanobot.providers.factory.make_provider", lambda _config: _fake_provider())
     monkeypatch.setattr("nanobot.bus.queue.MessageBus", lambda: object())
     monkeypatch.setattr("nanobot.cron.service.CronService", lambda _store: object())
@@ -1630,8 +1579,8 @@ def test_agent_config_sets_active_path(monkeypatch, tmp_path: Path) -> None:
         async def close_mcp(self) -> None:
             return None
 
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
-    monkeypatch.setattr("nanobot.cli.commands._print_agent_response", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr("nanobot.cli.agent.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.terminal._print_agent_response", lambda *_args, **_kwargs: None)
 
     result = runner.invoke(app, ["agent", "-m", "hello", "-c", str(config_file)])
 
@@ -1650,8 +1599,7 @@ def test_agent_uses_workspace_directory_for_cron_store(monkeypatch, tmp_path: Pa
 
     monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
     monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
-    monkeypatch.setattr("nanobot.cli.commands._prepare_resource_view", lambda _config: None)
+    monkeypatch.setattr("nanobot.cli.agent.sync_workspace_templates", lambda _path: None)
     monkeypatch.setattr("nanobot.providers.factory.make_provider", lambda _config: _fake_provider())
     monkeypatch.setattr("nanobot.bus.queue.MessageBus", lambda: object())
 
@@ -1673,8 +1621,8 @@ def test_agent_uses_workspace_directory_for_cron_store(monkeypatch, tmp_path: Pa
             return None
 
     monkeypatch.setattr("nanobot.cron.service.CronService", _FakeCron)
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
-    monkeypatch.setattr("nanobot.cli.commands._print_agent_response", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr("nanobot.cli.agent.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.terminal._print_agent_response", lambda *_args, **_kwargs: None)
 
     result = runner.invoke(app, ["agent", "-m", "hello", "-c", str(config_file)])
 
@@ -1700,8 +1648,7 @@ def test_agent_workspace_override_does_not_migrate_legacy_cron(
 
     monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
     monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
-    monkeypatch.setattr("nanobot.cli.commands._prepare_resource_view", lambda _config: None)
+    monkeypatch.setattr("nanobot.cli.agent.sync_workspace_templates", lambda _path: None)
     monkeypatch.setattr("nanobot.providers.factory.make_provider", lambda _config: _fake_provider())
     monkeypatch.setattr("nanobot.bus.queue.MessageBus", lambda: object())
     monkeypatch.setattr("nanobot.config.paths.get_cron_dir", lambda: legacy_dir)
@@ -1724,8 +1671,8 @@ def test_agent_workspace_override_does_not_migrate_legacy_cron(
             return None
 
     monkeypatch.setattr("nanobot.cron.service.CronService", _FakeCron)
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
-    monkeypatch.setattr("nanobot.cli.commands._print_agent_response", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr("nanobot.cli.agent.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.terminal._print_agent_response", lambda *_args, **_kwargs: None)
 
     result = runner.invoke(
         app,
@@ -1757,8 +1704,7 @@ def test_agent_custom_config_workspace_does_not_migrate_legacy_cron(
 
     monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
     monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
-    monkeypatch.setattr("nanobot.cli.commands._prepare_resource_view", lambda _config: None)
+    monkeypatch.setattr("nanobot.cli.agent.sync_workspace_templates", lambda _path: None)
     monkeypatch.setattr("nanobot.providers.factory.make_provider", lambda _config: _fake_provider())
     monkeypatch.setattr("nanobot.bus.queue.MessageBus", lambda: object())
     monkeypatch.setattr("nanobot.config.paths.get_cron_dir", lambda: legacy_dir)
@@ -1781,9 +1727,9 @@ def test_agent_custom_config_workspace_does_not_migrate_legacy_cron(
             return None
 
     monkeypatch.setattr("nanobot.cron.service.CronService", _FakeCron)
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.agent.AgentLoop", _FakeAgentLoop)
     monkeypatch.setattr(
-        "nanobot.cli.commands._print_agent_response", lambda *_args, **_kwargs: None
+        "nanobot.cli.terminal._print_agent_response", lambda *_args, **_kwargs: None
     )
 
     result = runner.invoke(app, ["agent", "-m", "hello", "-c", str(config_file)])
@@ -1845,20 +1791,20 @@ def test_heartbeat_retains_recent_messages_by_default():
     ],
 )
 def test_heartbeat_has_active_tasks(content, expected):
-    from nanobot.cli.commands import _heartbeat_has_active_tasks
+    from nanobot.cli.gateway_runtime import _heartbeat_has_active_tasks
 
     assert _heartbeat_has_active_tasks(content) is expected
 
 
 def test_heartbeat_skips_bundled_template():
-    from nanobot.cli.commands import _heartbeat_has_active_tasks
+    from nanobot.cli.gateway_runtime import _heartbeat_has_active_tasks
     from nanobot.utils.helpers import load_bundled_template
 
     assert _heartbeat_has_active_tasks(load_bundled_template("HEARTBEAT.md")) is False
 
 
 def test_heartbeat_target_skips_archived_webui_sessions():
-    from nanobot.cli.commands import _pick_heartbeat_target_from_sessions
+    from nanobot.cli.gateway_runtime import _pick_heartbeat_target_from_sessions
 
     target = _pick_heartbeat_target_from_sessions(
         enabled_channels=["websocket"],
@@ -1873,7 +1819,7 @@ def test_heartbeat_target_skips_archived_webui_sessions():
 
 
 def test_heartbeat_target_uses_last_channel_for_unified_session():
-    from nanobot.cli.commands import _pick_heartbeat_target_from_sessions
+    from nanobot.cli.gateway_runtime import _pick_heartbeat_target_from_sessions
     from nanobot.session.keys import LAST_CHANNEL_METADATA_KEY, UNIFIED_SESSION_KEY
 
     target = _pick_heartbeat_target_from_sessions(
@@ -1895,7 +1841,7 @@ def test_heartbeat_target_uses_last_channel_for_unified_session():
     ],
 )
 def test_heartbeat_target_rejects_unroutable_unified_metadata(metadata):
-    from nanobot.cli.commands import _pick_heartbeat_target_from_sessions
+    from nanobot.cli.gateway_runtime import _pick_heartbeat_target_from_sessions
     from nanobot.session.keys import UNIFIED_SESSION_KEY
 
     target = _pick_heartbeat_target_from_sessions(
@@ -1936,9 +1882,17 @@ def _patch_webui_provider_ready(monkeypatch) -> None:
 
 
 def _patch_gateway_ports_free(monkeypatch) -> None:
-    monkeypatch.setattr("nanobot.cli.commands._gateway_health_ready", lambda *_a, **_kw: False)
-    monkeypatch.setattr("nanobot.cli.commands._tcp_endpoint_reachable", lambda *_a, **_kw: False)
-    monkeypatch.setattr("nanobot.cli.commands._webui_endpoint_reachable", lambda *_a, **_kw: False)
+    monkeypatch.setattr("nanobot.cli.webui._gateway_health_ready", lambda *_a, **_kw: False)
+    monkeypatch.setattr("nanobot.cli.webui._tcp_endpoint_reachable", lambda *_a, **_kw: False)
+    monkeypatch.setattr("nanobot.cli.webui._webui_endpoint_reachable", lambda *_a, **_kw: False)
+    monkeypatch.setattr(
+        "nanobot.cli.gateway_runtime._tcp_endpoint_reachable",
+        lambda *_a, **_kw: False,
+    )
+    monkeypatch.setattr(
+        "nanobot.cli.gateway_runtime._webui_endpoint_reachable",
+        lambda *_a, **_kw: False,
+    )
 
 
 def _patch_cli_command_runtime(
@@ -1952,7 +1906,6 @@ def _patch_cli_command_runtime(
     session_manager=None,
     cron_service=None,
     get_cron_dir=None,
-    prepare_resource_view=None,
 ) -> None:
     provider_factory = make_provider or (lambda _config: _fake_provider())
 
@@ -1967,8 +1920,12 @@ def _patch_cli_command_runtime(
         sync_templates or (lambda _path: None),
     )
     monkeypatch.setattr(
-        "nanobot.cli.commands._prepare_resource_view",
-        prepare_resource_view or (lambda _config: None),
+        "nanobot.cli.webui.sync_workspace_templates",
+        sync_templates or (lambda _path: None),
+    )
+    monkeypatch.setattr(
+        "nanobot.cli.gateway_runtime.sync_workspace_templates",
+        sync_templates or (lambda _path: None),
     )
     monkeypatch.setattr(
         "nanobot.providers.factory.make_provider",
@@ -1983,7 +1940,7 @@ def _patch_cli_command_runtime(
         lambda _config_path=None: _test_provider_snapshot(provider_factory(config), config),
     )
     monkeypatch.setattr(
-        "nanobot.cli.commands._provider_setup_error",
+        "nanobot.cli.webui_support._provider_setup_error",
         lambda _config: None,
     )
     _patch_gateway_ports_free(monkeypatch)
@@ -2084,10 +2041,10 @@ def test_heartbeat_empty_response_still_retains_recent_messages(
         session_manager=_FakeSessionManager,
         cron_service=_FakeCron,
     )
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.AgentLoop", _FakeAgentLoop)
     monkeypatch.setattr("nanobot.channels.manager.ChannelManager", _FakeChannelManager)
-    monkeypatch.setattr("nanobot.cli.commands.read_webui_sidebar_state", lambda: {})
-    monkeypatch.setattr("nanobot.cli.commands.evaluate_response", _unexpected_evaluator)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.read_webui_sidebar_state", lambda: {})
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.evaluate_response", _unexpected_evaluator)
 
     result = runner.invoke(app, ["gateway", "--config", str(config_file)])
 
@@ -2110,7 +2067,7 @@ def test_webui_yes_creates_config_and_enables_local_websocket(
     seen: dict[str, object] = {}
     _patch_webui_provider_ready(monkeypatch)
     monkeypatch.setattr(
-        "nanobot.cli.commands.sync_workspace_templates",
+        "nanobot.cli.webui.sync_workspace_templates",
         lambda path: seen.__setitem__("templates", path),
     )
 
@@ -2118,7 +2075,7 @@ def test_webui_yes_creates_config_and_enables_local_websocket(
         seen["gateway_config"] = config
         seen["gateway_kwargs"] = kwargs
 
-    monkeypatch.setattr("nanobot.cli.commands._run_gateway", _fake_run_gateway)
+    monkeypatch.setattr("nanobot.cli.webui._run_gateway", _fake_run_gateway)
 
     result = runner.invoke(
         app,
@@ -2167,13 +2124,17 @@ def test_webui_yes_starts_first_run_without_provider_setup(monkeypatch, tmp_path
     seen: dict[str, object] = {}
 
     monkeypatch.setattr(
-        "nanobot.cli.commands._provider_setup_error",
+        "nanobot.cli.webui_support._provider_setup_error",
+        lambda _config: "No API key configured for provider 'custom'.",
+    )
+    monkeypatch.setattr(
+        "nanobot.cli.webui._provider_setup_error",
         lambda _config: "No API key configured for provider 'custom'.",
     )
     _patch_gateway_ports_free(monkeypatch)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.webui.sync_workspace_templates", lambda _path: None)
     monkeypatch.setattr(
-        "nanobot.cli.commands._run_gateway",
+        "nanobot.cli.webui._run_gateway",
         lambda config, **kwargs: seen.update(config=config, **kwargs),
     )
 
@@ -2211,7 +2172,7 @@ def test_webui_missing_runtime_env_fails_before_starting_gateway(
         encoding="utf-8",
     )
     monkeypatch.setattr(
-        "nanobot.cli.commands._run_gateway",
+        "nanobot.cli.webui._run_gateway",
         lambda *_args, **_kwargs: pytest.fail("gateway must not start with unresolved config"),
     )
 
@@ -2265,9 +2226,9 @@ def test_webui_background_starts_runtime_and_opens_browser(monkeypatch, tmp_path
     config_file.write_text("{}")
     seen: dict[str, object] = {}
     _patch_webui_provider_ready(monkeypatch)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.webui.sync_workspace_templates", lambda _path: None)
     monkeypatch.setattr(
-        "nanobot.cli.commands._prepare_webui_bundle_for_gateway",
+        "nanobot.cli.webui._prepare_webui_bundle_for_gateway",
         lambda *_args, **_kwargs: None,
     )
 
@@ -2289,7 +2250,7 @@ def test_webui_background_starts_runtime_and_opens_browser(monkeypatch, tmp_path
 
     monkeypatch.setattr("nanobot.gateway.GatewayRuntime", _FakeRuntime)
     monkeypatch.setattr(
-        "nanobot.cli.commands._open_webui_browser",
+        "nanobot.cli.webui._open_webui_browser",
         lambda url: seen.__setitem__("opened_url", url),
     )
 
@@ -2332,7 +2293,7 @@ def test_open_webui_browser_redacts_bootstrap_secret(monkeypatch, capsys) -> Non
     url = "http://127.0.0.1:8765/#/?bootstrapSecret=super-secret"
     monkeypatch.setattr("webbrowser.open", lambda value: opened.append(value))
 
-    cli_commands._open_webui_browser(url, wait=False)
+    cli_webui_support._open_webui_browser(url, wait=False)
 
     assert opened == [url]
     output = _strip_ansi(capsys.readouterr().out)
@@ -2351,9 +2312,9 @@ def test_webui_background_restarts_when_config_changes_and_gateway_is_running(
     config_file.write_text("{}")
     seen: dict[str, object] = {}
     _patch_webui_provider_ready(monkeypatch)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.webui.sync_workspace_templates", lambda _path: None)
     monkeypatch.setattr(
-        "nanobot.cli.commands._prepare_webui_bundle_for_gateway",
+        "nanobot.cli.webui._prepare_webui_bundle_for_gateway",
         lambda *_args, **_kwargs: None,
     )
 
@@ -2382,7 +2343,7 @@ def test_webui_background_restarts_when_config_changes_and_gateway_is_running(
 
     monkeypatch.setattr("nanobot.gateway.GatewayRuntime", _FakeRuntime)
     monkeypatch.setattr(
-        "nanobot.cli.commands._open_webui_browser",
+        "nanobot.cli.webui._open_webui_browser",
         lambda url: seen.__setitem__("opened_url", url),
     )
 
@@ -2423,15 +2384,15 @@ def test_webui_foreground_attaches_to_existing_managed_gateway(monkeypatch, tmp_
     config_file.write_text("{}")
     seen: dict[str, object] = {}
     _patch_webui_provider_ready(monkeypatch)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
-    monkeypatch.setattr("nanobot.cli.commands._gateway_health_ready", lambda *_args, **_kwargs: True)
-    monkeypatch.setattr("nanobot.cli.commands._webui_endpoint_reachable", lambda *_args, **_kwargs: True)
+    monkeypatch.setattr("nanobot.cli.webui.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.webui._gateway_health_ready", lambda *_args, **_kwargs: True)
+    monkeypatch.setattr("nanobot.cli.webui._webui_endpoint_reachable", lambda *_args, **_kwargs: True)
     monkeypatch.setattr(
-        "nanobot.cli.commands._open_webui_browser",
+        "nanobot.cli.webui._open_webui_browser",
         lambda url, **kwargs: seen.update({"opened_url": url, "open_kwargs": kwargs}),
     )
     monkeypatch.setattr(
-        "nanobot.cli.commands._run_gateway",
+        "nanobot.cli.webui._run_gateway",
         lambda *_args, **_kwargs: pytest.fail("existing gateway should be reused"),
     )
 
@@ -2444,7 +2405,7 @@ def test_webui_foreground_attaches_to_existing_managed_gateway(monkeypatch, tmp_
 
     monkeypatch.setattr("nanobot.gateway.GatewayRuntime", _FakeRuntime)
     monkeypatch.setattr(
-        "nanobot.cli.commands._attach_to_background_gateway",
+        "nanobot.cli.webui._attach_to_background_gateway",
         lambda runtime: seen.__setitem__("attached_runtime", runtime),
     )
 
@@ -2477,9 +2438,9 @@ def test_attach_to_background_gateway_stops_on_ctrl_c(monkeypatch, capsys) -> No
     def _interrupt(_seconds: float) -> None:
         raise KeyboardInterrupt
 
-    monkeypatch.setattr("nanobot.cli.commands.time.sleep", _interrupt)
+    monkeypatch.setattr("nanobot.cli.webui_support.time.sleep", _interrupt)
 
-    cli_commands._attach_to_background_gateway(_FakeRuntime())
+    cli_webui_support._attach_to_background_gateway(_FakeRuntime())
 
     assert stopped is True
     output = capsys.readouterr().out
@@ -2492,12 +2453,12 @@ def test_webui_foreground_does_not_claim_unmanaged_gateway(monkeypatch, tmp_path
     config_file = tmp_path / "config.json"
     config_file.write_text("{}")
     _patch_webui_provider_ready(monkeypatch)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
-    monkeypatch.setattr("nanobot.cli.commands._gateway_health_ready", lambda *_args: True)
-    monkeypatch.setattr("nanobot.cli.commands._webui_endpoint_reachable", lambda *_args: True)
-    monkeypatch.setattr("nanobot.cli.commands._open_webui_browser", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr("nanobot.cli.webui.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.webui._gateway_health_ready", lambda *_args: True)
+    monkeypatch.setattr("nanobot.cli.webui._webui_endpoint_reachable", lambda *_args: True)
+    monkeypatch.setattr("nanobot.cli.webui._open_webui_browser", lambda *_args, **_kwargs: None)
     monkeypatch.setattr(
-        "nanobot.cli.commands._attach_to_background_gateway",
+        "nanobot.cli.webui._attach_to_background_gateway",
         lambda _runtime: pytest.fail("unmanaged gateway must not be attached"),
     )
 
@@ -2520,12 +2481,12 @@ def test_webui_foreground_refuses_occupied_webui_port(monkeypatch, tmp_path: Pat
     config_file = tmp_path / "config.json"
     config_file.write_text("{}")
     _patch_webui_provider_ready(monkeypatch)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
-    monkeypatch.setattr("nanobot.cli.commands._gateway_health_ready", lambda *_args, **_kwargs: False)
-    monkeypatch.setattr("nanobot.cli.commands._webui_endpoint_reachable", lambda *_args, **_kwargs: True)
-    monkeypatch.setattr("nanobot.cli.commands._tcp_endpoint_reachable", lambda *_args, **_kwargs: False)
+    monkeypatch.setattr("nanobot.cli.webui.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.webui._gateway_health_ready", lambda *_args, **_kwargs: False)
+    monkeypatch.setattr("nanobot.cli.webui._webui_endpoint_reachable", lambda *_args, **_kwargs: True)
+    monkeypatch.setattr("nanobot.cli.webui._tcp_endpoint_reachable", lambda *_args, **_kwargs: False)
     monkeypatch.setattr(
-        "nanobot.cli.commands._run_gateway",
+        "nanobot.cli.webui._run_gateway",
         lambda *_args, **_kwargs: pytest.fail("gateway should not start on occupied ports"),
     )
 
@@ -2539,8 +2500,6 @@ def test_webui_foreground_refuses_occupied_webui_port(monkeypatch, tmp_path: Pat
 
 def _patch_serve_runtime(monkeypatch, config: Config, seen: dict[str, object]) -> None:
     pytest.importorskip("aiohttp")
-    resource_view = object()
-    seen["expected_resource_view"] = resource_view
 
     class _FakeApiApp:
         def __init__(self) -> None:
@@ -2553,7 +2512,6 @@ def _patch_serve_runtime(monkeypatch, config: Config, seen: dict[str, object]) -
             return cls(workspace=config.workspace_path, **extra)
         def __init__(self, **kwargs) -> None:
             seen["workspace"] = kwargs["workspace"]
-            seen["resource_view"] = kwargs["resource_view"]
 
         async def _connect_mcp(self) -> None:
             return None
@@ -2583,7 +2541,6 @@ def _patch_serve_runtime(monkeypatch, config: Config, seen: dict[str, object]) -
         config,
         message_bus=lambda: object(),
         session_manager=lambda _workspace: object(),
-        prepare_resource_view=lambda _config: resource_view,
     )
     monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
     monkeypatch.setattr("nanobot.api.server.create_app", _fake_create_app)
@@ -2676,9 +2633,9 @@ def test_gateway_unbound_agent_cron_is_skipped(
 
     monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
     monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.sync_workspace_templates", lambda _path: None)
     monkeypatch.setattr("nanobot.providers.factory.make_provider", lambda _config: provider)
-    monkeypatch.setattr("nanobot.cli.commands._provider_setup_error", lambda _config: None)
+    monkeypatch.setattr("nanobot.cli.webui_support._provider_setup_error", lambda _config: None)
     _patch_gateway_ports_free(monkeypatch)
     monkeypatch.setattr(
         "nanobot.providers.factory.build_provider_snapshot",
@@ -2752,10 +2709,10 @@ def test_gateway_unbound_agent_cron_is_skipped(
         raise AssertionError("unbound cron job must not be evaluated for delivery")
 
     monkeypatch.setattr("nanobot.cron.service.CronService", _FakeCron)
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.AgentLoop", _FakeAgentLoop)
     monkeypatch.setattr("nanobot.channels.manager.ChannelManager", _StopAfterCronSetup)
     monkeypatch.setattr(
-        "nanobot.cli.commands.evaluate_response",
+        "nanobot.cli.gateway_runtime.evaluate_response",
         _capture_evaluate_response,
     )
 
@@ -2804,9 +2761,9 @@ def test_gateway_bound_cron_runs_as_session_turn(
 
     monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
     monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
-    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.sync_workspace_templates", lambda _path: None)
     monkeypatch.setattr("nanobot.providers.factory.make_provider", lambda _config: provider)
-    monkeypatch.setattr("nanobot.cli.commands._provider_setup_error", lambda _config: None)
+    monkeypatch.setattr("nanobot.cli.webui_support._provider_setup_error", lambda _config: None)
     _patch_gateway_ports_free(monkeypatch)
     monkeypatch.setattr(
         "nanobot.providers.factory.build_provider_snapshot",
@@ -2868,9 +2825,9 @@ def test_gateway_bound_cron_runs_as_session_turn(
         raise AssertionError("bound cron must not use legacy response evaluator")
 
     monkeypatch.setattr("nanobot.cron.service.CronService", _FakeCron)
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.AgentLoop", _FakeAgentLoop)
     monkeypatch.setattr("nanobot.channels.manager.ChannelManager", _StopAfterCronSetup)
-    monkeypatch.setattr("nanobot.cli.commands.evaluate_response", _unexpected_evaluator)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.evaluate_response", _unexpected_evaluator)
 
     result = runner.invoke(app, ["gateway", "--config", str(config_file)])
     assert isinstance(result.exception, _StopGatewayError)
@@ -3003,7 +2960,6 @@ def test_gateway_local_trigger_queue_submits_agent_turns(
     config.gateway.heartbeat.enabled = False
     bus = MagicMock()
     seen: dict[str, object] = {}
-    resource_view = object()
 
     _patch_cli_command_runtime(
         monkeypatch,
@@ -3011,7 +2967,6 @@ def test_gateway_local_trigger_queue_submits_agent_turns(
         message_bus=lambda: bus,
         session_manager=lambda _workspace: _FakeSessionManager(),
         cron_service=lambda _store_path: _FakeCronService(),
-        prepare_resource_view=lambda _config: resource_view,
     )
 
     class _FakeMemory:
@@ -3066,7 +3021,7 @@ def test_gateway_local_trigger_queue_submits_agent_turns(
             self.runtime_resolver = MagicMock()
             seen["agent"] = self
 
-        def _schedule_background(self, _coro) -> None:
+        def schedule_background(self, _coro) -> None:
             return None
 
         async def run(self) -> None:
@@ -3098,7 +3053,7 @@ def test_gateway_local_trigger_queue_submits_agent_turns(
         seen["local_trigger_queue_kwargs"] = kwargs
         raise _StopGatewayError("stop")
 
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.AgentLoop", _FakeAgentLoop)
     monkeypatch.setattr("nanobot.channels.manager.ChannelManager", _FakeChannelManager)
     monkeypatch.setattr(
         "nanobot.triggers.local_runner.run_local_trigger_queue",
@@ -3115,7 +3070,6 @@ def test_gateway_local_trigger_queue_submits_agent_turns(
     agent_kwargs = seen["agent_from_config_kwargs"]
     kwargs = seen["local_trigger_queue_kwargs"]
     assert isinstance(agent_kwargs["provider"], UnconfiguredProvider) is bool(setup_error)
-    assert agent_kwargs["resource_view"] is resource_view
     refreshed_snapshot = agent_kwargs["provider_snapshot_loader"]()
     assert not isinstance(refreshed_snapshot.provider, UnconfiguredProvider)
     assert "local_trigger_store" in agent_kwargs
@@ -3207,7 +3161,7 @@ def test_gateway_custom_config_workspace_does_not_migrate_legacy_cron(
 
 def test_migrate_cron_store_moves_legacy_file(tmp_path: Path) -> None:
     """Legacy global jobs.json is moved into the workspace on first run."""
-    from nanobot.cli.commands import _migrate_cron_store
+    from nanobot.cli.runtime_config import _migrate_cron_store
 
     legacy_dir = tmp_path / "global" / "cron"
     legacy_dir.mkdir(parents=True)
@@ -3228,7 +3182,7 @@ def test_migrate_cron_store_moves_legacy_file(tmp_path: Path) -> None:
 
 def test_migrate_cron_store_skips_when_workspace_file_exists(tmp_path: Path) -> None:
     """Migration does not overwrite an existing workspace cron store."""
-    from nanobot.cli.commands import _migrate_cron_store
+    from nanobot.cli.runtime_config import _migrate_cron_store
 
     legacy_dir = tmp_path / "global" / "cron"
     legacy_dir.mkdir(parents=True)
@@ -3395,7 +3349,7 @@ def test_gateway_health_endpoint_binds_and_serves_expected_responses(
         message_bus=lambda: object(),
         session_manager=lambda _workspace: object(),
     )
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.AgentLoop", _FakeAgentLoop)
     monkeypatch.setattr("nanobot.channels.manager.ChannelManager", _FakeChannelManager)
     monkeypatch.setattr("nanobot.cron.service.CronService", _FakeCronService)
     monkeypatch.setattr("asyncio.start_server", _fake_start_server)
@@ -3446,13 +3400,14 @@ def test_gateway_health_endpoint_binds_and_serves_expected_responses(
                 async def read(self, _size: int) -> bytes:
                     nonlocal started
                     started += 1
-                    if started == cli_commands._GATEWAY_HEALTH_MAX_CONNECTIONS:
+                    if started == cli_gateway_runtime._GATEWAY_HEALTH_MAX_CONNECTIONS:
                         all_started.set()
                     await release.wait()
                     return b"GET /health HTTP/1.1\r\n\r\n"
 
             active_writers = [
-                _FakeWriter() for _ in range(cli_commands._GATEWAY_HEALTH_MAX_CONNECTIONS)
+                _FakeWriter()
+                for _ in range(cli_gateway_runtime._GATEWAY_HEALTH_MAX_CONNECTIONS)
             ]
             active_tasks = [
                 asyncio.create_task(health_handler(_BlockingReader(), writer))
@@ -3477,7 +3432,11 @@ def test_gateway_health_endpoint_binds_and_serves_expected_responses(
             async def read(self, _size: int) -> bytes:
                 await asyncio.Event().wait()
 
-        monkeypatch.setattr(cli_commands, "_GATEWAY_HEALTH_READ_TIMEOUT_SECONDS", 0.01)
+        monkeypatch.setattr(
+            cli_gateway_runtime,
+            "_GATEWAY_HEALTH_READ_TIMEOUT_SECONDS",
+            0.01,
+        )
         timed_out_writer = _FakeWriter()
         asyncio.run(health_handler(_NeverRespondingReader(), timed_out_writer))
         assert timed_out_writer.closed is True
@@ -3568,7 +3527,7 @@ def test_gateway_shutdown_lets_agent_task_own_mcp_cleanup(
         message_bus=lambda: object(),
         session_manager=lambda _workspace: object(),
     )
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.AgentLoop", _FakeAgentLoop)
     monkeypatch.setattr("nanobot.channels.manager.ChannelManager", _FakeChannelManager)
     monkeypatch.setattr("nanobot.cron.service.CronService", _FakeCronService)
     monkeypatch.setattr("asyncio.start_server", _fake_start_server)
@@ -3684,12 +3643,12 @@ def test_gateway_shutdown_event_exits_forever_runtime_tasks(
         message_bus=lambda: object(),
         session_manager=lambda _workspace: object(),
     )
-    monkeypatch.setattr("nanobot.cli.commands.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.gateway_runtime.AgentLoop", _FakeAgentLoop)
     monkeypatch.setattr("nanobot.channels.manager.ChannelManager", _FakeChannelManager)
     monkeypatch.setattr("nanobot.cron.service.CronService", _FakeCronService)
     monkeypatch.setattr("asyncio.start_server", _fake_start_server)
     monkeypatch.setattr(
-        "nanobot.cli.commands._install_gateway_shutdown_handlers",
+        "nanobot.cli.gateway_runtime._install_gateway_shutdown_handlers",
         _fake_install_shutdown_handlers,
     )
 
@@ -3729,7 +3688,6 @@ def test_serve_uses_api_config_defaults_and_workspace_override(
 
     assert result.exit_code == 0
     assert seen["workspace"] == override_workspace
-    assert seen["resource_view"] is seen["expected_resource_view"]
     assert seen["host"] == "127.0.0.2"
     assert seen["port"] == 18900
     assert seen["request_timeout"] == 45.0

tests/cli/test_config_diagnostics.py

@@ -413,7 +413,7 @@ def test_gateway_missing_provider_managed_start_for_webui_setup(
     monkeypatch.setattr(GatewayRuntime, "start_background", fake_start_background)
     monkeypatch.setattr(GatewayRuntime, "restart", fake_restart)
     monkeypatch.setattr(
-        "nanobot.cli.commands.ensure_webui_bundle",
+        "nanobot.cli.webui_support.ensure_webui_bundle",
         lambda **_kwargs: None,
     )
 

tests/cli/test_interactive_retry_wait.py

@@ -4,7 +4,7 @@ from unittest.mock import patch
 import pytest
 
 from nanobot.bus.outbound_events import ProgressEvent, RetryWaitEvent
-from nanobot.cli import commands
+from nanobot.cli import terminal
 
 
 @pytest.mark.asyncio
@@ -22,8 +22,8 @@ async def test_interactive_retry_wait_is_rendered_as_progress_even_when_progress
     async def fake_print(text: str, active_thinking: object | None, renderer=None) -> None:
         calls.append((text, active_thinking))
 
-    with patch("nanobot.cli.commands._print_interactive_progress_line", side_effect=fake_print):
-        handled = await commands._maybe_print_interactive_progress(
+    with patch("nanobot.cli.terminal._print_interactive_progress_line", side_effect=fake_print):
+        handled = await terminal._maybe_print_interactive_progress(
             msg,
             thinking,
             channels_config,
@@ -46,8 +46,8 @@ async def test_reasoning_displayed_when_show_reasoning_enabled():
         metadata={},
     )
 
-    with patch("nanobot.cli.commands._print_cli_reasoning", side_effect=lambda t, th, r=None: calls.append(t)):
-        handled = await commands._maybe_print_interactive_progress(msg, None, channels_config)
+    with patch("nanobot.cli.terminal._print_cli_reasoning", side_effect=lambda t, th, r=None: calls.append(t)):
+        handled = await terminal._maybe_print_interactive_progress(msg, None, channels_config)
 
     assert handled is True
     assert calls == ["Let me think about this..."]
@@ -66,8 +66,8 @@ async def test_reasoning_delta_displayed_when_show_reasoning_enabled():
         metadata={},
     )
 
-    with patch("nanobot.cli.commands._print_cli_reasoning", side_effect=lambda t, th, r=None: calls.append(t)):
-        handled = await commands._maybe_print_interactive_progress(msg, None, channels_config)
+    with patch("nanobot.cli.terminal._print_cli_reasoning", side_effect=lambda t, th, r=None: calls.append(t)):
+        handled = await terminal._maybe_print_interactive_progress(msg, None, channels_config)
 
     assert handled is True
     assert calls == ["I should search first."]
@@ -79,10 +79,10 @@ async def test_reasoning_delta_buffers_until_sentence_boundary():
     channels_config = SimpleNamespace(
         send_progress=True, send_tool_hints=False, show_reasoning=True,
     )
-    reasoning_buffer = commands._ReasoningBuffer()
+    reasoning_buffer = terminal._ReasoningBuffer()
 
-    with patch("nanobot.cli.commands._print_cli_reasoning", side_effect=lambda t, th, r=None: calls.append(t)):
-        first = await commands._maybe_print_interactive_progress(
+    with patch("nanobot.cli.terminal._print_cli_reasoning", side_effect=lambda t, th, r=None: calls.append(t)):
+        first = await terminal._maybe_print_interactive_progress(
             SimpleNamespace(
                 content="The",
                 event=ProgressEvent(content="The", reasoning_delta=True),
@@ -92,7 +92,7 @@ async def test_reasoning_delta_buffers_until_sentence_boundary():
             channels_config,
             reasoning_buffer=reasoning_buffer,
         )
-        second = await commands._maybe_print_interactive_progress(
+        second = await terminal._maybe_print_interactive_progress(
             SimpleNamespace(
                 content=" user asked.",
                 event=ProgressEvent(content=" user asked.", reasoning_delta=True),
@@ -114,10 +114,10 @@ async def test_reasoning_end_flushes_buffered_delta():
     channels_config = SimpleNamespace(
         send_progress=True, send_tool_hints=False, show_reasoning=True,
     )
-    reasoning_buffer = commands._ReasoningBuffer()
+    reasoning_buffer = terminal._ReasoningBuffer()
 
-    with patch("nanobot.cli.commands._print_cli_reasoning", side_effect=lambda t, th, r=None: calls.append(t)):
-        delta = await commands._maybe_print_interactive_progress(
+    with patch("nanobot.cli.terminal._print_cli_reasoning", side_effect=lambda t, th, r=None: calls.append(t)):
+        delta = await terminal._maybe_print_interactive_progress(
             SimpleNamespace(
                 content="The user asked",
                 event=ProgressEvent(content="The user asked", reasoning_delta=True),
@@ -127,7 +127,7 @@ async def test_reasoning_end_flushes_buffered_delta():
             channels_config,
             reasoning_buffer=reasoning_buffer,
         )
-        end = await commands._maybe_print_interactive_progress(
+        end = await terminal._maybe_print_interactive_progress(
             SimpleNamespace(
                 content="",
                 event=ProgressEvent(reasoning_end=True),
@@ -155,8 +155,8 @@ async def test_reasoning_hidden_when_show_reasoning_disabled():
         metadata={},
     )
 
-    with patch("nanobot.cli.commands._print_cli_reasoning") as mock_reasoning:
-        handled = await commands._maybe_print_interactive_progress(msg, None, channels_config)
+    with patch("nanobot.cli.terminal._print_cli_reasoning") as mock_reasoning:
+        handled = await terminal._maybe_print_interactive_progress(msg, None, channels_config)
 
     assert handled is True
     mock_reasoning.assert_not_called()
@@ -178,8 +178,8 @@ async def test_non_reasoning_progress_not_affected_by_show_reasoning():
     async def fake_print(text: str, thinking=None, renderer=None):
         calls.append(text)
 
-    with patch("nanobot.cli.commands._print_interactive_progress_line", side_effect=fake_print):
-        handled = await commands._maybe_print_interactive_progress(msg, None, channels_config)
+    with patch("nanobot.cli.terminal._print_interactive_progress_line", side_effect=fake_print):
+        handled = await terminal._maybe_print_interactive_progress(msg, None, channels_config)
 
     assert handled is True
     assert calls == ["working on it..."]
@@ -200,10 +200,10 @@ async def test_reasoning_shown_when_send_progress_disabled():
     )
 
     with patch(
-        "nanobot.cli.commands._print_cli_reasoning",
+        "nanobot.cli.terminal._print_cli_reasoning",
         side_effect=lambda t, th, r=None: calls.append(t),
     ):
-        handled = await commands._maybe_print_interactive_progress(msg, None, channels_config)
+        handled = await terminal._maybe_print_interactive_progress(msg, None, channels_config)
 
     assert handled is True
     assert calls == ["Let me think about this..."]

tests/cli/test_safe_file_history.py

@@ -3,7 +3,12 @@
 Surrogate characters in CLI input must not crash history file writes.
 """
 
-from nanobot.cli.commands import SafeFileHistory, _sanitize_surrogates
+from nanobot.cli.commands import SafeFileHistory as LegacySafeFileHistory
+from nanobot.cli.terminal import SafeFileHistory, _sanitize_surrogates
+
+
+def test_commands_keeps_safe_file_history_import_compatible() -> None:
+    assert LegacySafeFileHistory is SafeFileHistory
 
 
 class TestSanitizeSurrogates:

tests/command/test_router_dispatchable.py

@@ -108,7 +108,7 @@ class TestMidTurnCommandDispatchedDirectly:
         ))
         loop.sessions.save = MagicMock()
         loop.sessions.invalidate = MagicMock()
-        loop._schedule_background = MagicMock()
+        loop.schedule_background = MagicMock()
         loop._cancel_active_tasks = AsyncMock(return_value=0)
         return loop
 

tests/pairing/test_store.py

@@ -323,3 +323,66 @@ def test_pending_gc_drops_malformed_entries(tmp_path, monkeypatch):
     )
     monkeypatch.setattr(store, "_store_path", lambda: path)
     assert store.list_pending() == []
+
+
+def _fail_reads_of(monkeypatch, path):
+    """Make reads of *path* raise like a transiently locked/busy file."""
+    import builtins
+    from pathlib import Path
+
+    real_open = builtins.open
+
+    def flaky_open(file, mode="r", *args, **kwargs):
+        try:
+            same = Path(file) == path
+        except TypeError:
+            same = False
+        if same and "r" in mode and "+" not in mode:
+            raise PermissionError(13, "temporarily locked", str(path))
+        return real_open(file, mode, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "open", flaky_open)
+
+
+class TestTransientReadFailure:
+    """A transient I/O failure is not corruption and must never wipe the store."""
+
+    def test_generate_code_does_not_wipe_approvals(self, tmp_path, monkeypatch):
+        """An unapproved DM during a read blip previously erased every approval.
+
+        _load treated OSError like corruption and returned an empty store;
+        generate_code then unconditionally saved it, overwriting pairing.json
+        with no approved senders.
+        """
+        code = store.generate_code("telegram", "123")
+        store.approve_code(code)
+
+        with monkeypatch.context() as m:
+            _fail_reads_of(m, store._store_path())
+            with pytest.raises(OSError):
+                store.generate_code("telegram", "stranger")
+
+        assert store.is_approved("telegram", "123") is True
+
+    def test_reads_fail_closed_without_crashing(self, tmp_path, monkeypatch):
+        code = store.generate_code("telegram", "123")
+        store.approve_code(code)
+
+        with monkeypatch.context() as m:
+            _fail_reads_of(m, store._store_path())
+            assert store.is_approved("telegram", "123") is False
+            assert store.list_pending() == []
+            assert store.get_approved("telegram") == []
+
+        assert store.is_approved("telegram", "123") is True
+
+    def test_approve_command_reports_store_unavailable(self, tmp_path, monkeypatch):
+        """/pairing approve must fail loudly instead of claiming the code is invalid."""
+        code = store.generate_code("telegram", "123")
+
+        with monkeypatch.context() as m:
+            _fail_reads_of(m, store._store_path())
+            reply = store.handle_pairing_command("telegram", f"approve {code}")
+
+        assert "unavailable" in reply.lower()
+        assert store.approve_code(code) == ("telegram", "123")

tests/providers/test_azure_openai_provider.py

@@ -11,7 +11,7 @@ from nanobot.providers.azure_openai_provider import (
     AzureOpenAIProvider,
     _AzureTokenProvider,
 )
-from nanobot.providers.base import LLMResponse
+from nanobot.providers.base import LLMResponse, ProviderCallContext
 
 # ---------------------------------------------------------------------------
 # Init & validation
@@ -234,6 +234,7 @@ def test_build_body_basic():
     assert body["max_output_tokens"] == 4096
     assert body["store"] is False
     assert "reasoning" not in body
+    assert "include" not in body
     # input should contain the converted user message only (system extracted)
     assert any(
         item.get("role") == "user"
@@ -241,6 +242,30 @@ def test_build_body_basic():
     )
 
 
+def test_build_body_enables_server_compaction():
+    provider = AzureOpenAIProvider(
+        api_key="k",
+        api_base="https://res.openai.azure.com",
+        default_model="gpt-5.6",
+    )
+
+    body = provider._build_body(
+        [{"role": "user", "content": "hello"}],
+        None,
+        None,
+        10_000,
+        0.1,
+        "high",
+        None,
+        provider_context=ProviderCallContext(context_window_tokens=200_000),
+    )
+
+    assert body["context_management"] == [{
+        "type": "compaction",
+        "compact_threshold": 180_000,
+    }]
+
+
 def test_build_body_max_tokens_minimum():
     """max_output_tokens should never be less than 1."""
     provider = AzureOpenAIProvider(api_key="k", api_base="https://r.com", default_model="gpt-4o")
@@ -358,6 +383,38 @@ async def test_chat_success():
     assert result.usage["prompt_tokens"] == 10
 
 
+@pytest.mark.asyncio
+async def test_chat_retries_without_unsupported_server_compaction():
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test.openai.azure.com",
+        default_model="gpt-5.6",
+    )
+
+    class UnsupportedCompactionError(Exception):
+        status_code = 400
+        body = {"error": {"message": "Unknown parameter: context_management"}}
+
+    provider._client.responses = MagicMock()
+    provider._client.responses.create = AsyncMock(side_effect=[
+        UnsupportedCompactionError(),
+        _make_sdk_response(content="compaction fallback"),
+    ])
+
+    result = await provider.chat(
+        [{"role": "user", "content": "Hi"}],
+        provider_context=ProviderCallContext(context_window_tokens=200_000),
+    )
+
+    create = provider._client.responses.create
+    assert result.content == "compaction fallback"
+    assert result.provider_state is not None
+    assert create.await_count == 2
+    assert "context_management" in create.call_args_list[0].kwargs
+    assert "context_management" not in create.call_args_list[1].kwargs
+    assert provider.supports_native_compaction() is False
+
+
 @pytest.mark.asyncio
 async def test_chat_uses_default_model():
     provider = AzureOpenAIProvider(
@@ -411,6 +468,7 @@ async def test_chat_with_tool_calls():
     assert len(result.tool_calls) == 1
     assert result.tool_calls[0].name == "get_weather"
     assert result.tool_calls[0].arguments == {"location": "SF"}
+    assert result.provider_state is not None
 
 
 @pytest.mark.asyncio
@@ -510,6 +568,7 @@ async def test_chat_stream_with_tool_calls():
     item_done.name = "get_weather"
     ev_item_done = MagicMock(type="response.output_item.done", item=item_done)
     resp_obj = MagicMock(status="completed")
+    resp_obj.model_dump.return_value = {"status": "completed", "output": []}
     ev_completed = MagicMock(type="response.completed", response=resp_obj)
 
     async def mock_stream():
@@ -527,6 +586,7 @@ async def test_chat_stream_with_tool_calls():
     assert len(result.tool_calls) == 1
     assert result.tool_calls[0].name == "get_weather"
     assert result.tool_calls[0].arguments == {"location": "SF"}
+    assert result.provider_state is not None
 
 
 @pytest.mark.asyncio

tests/providers/test_conversation_state.py

@@ -0,0 +1,291 @@
+"""Tests for provider-owned conversation-state lifecycle coordination."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from nanobot.providers.base import (
+    LLMProvider,
+    LLMResponse,
+    ProviderConversationState,
+    ToolCallRequest,
+)
+from nanobot.providers.conversation_state import (
+    ProviderConversationStateController,
+    allows_conversation_message_merge,
+)
+
+
+def _provider(*, resumable: bool = True, compact: bool = False) -> MagicMock:
+    provider = MagicMock(spec=LLMProvider)
+    provider.can_resume_conversation_state.return_value = resumable
+    provider.supports_native_compaction.return_value = compact
+    return provider
+
+
+def _state(label: str, *, pending: list[dict] | None = None) -> ProviderConversationState:
+    return ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={"items": [{"type": "reasoning", "encrypted_content": label}]},
+        pending_messages=pending or [],
+    )
+
+
+def test_controller_replays_only_messages_after_provider_output() -> None:
+    provider = _provider()
+    messages = [
+        {"role": "system", "content": "system"},
+        {"role": "user", "content": "run a tool"},
+    ]
+    controller = ProviderConversationStateController(
+        provider=provider,
+        model="gpt-5.6",
+        messages=messages,
+    )
+    state = _state("first")
+
+    controller.prepare_request(messages, context_window_tokens=200_000)
+    response = LLMResponse(content=None, provider_state=state)
+    controller.observe_response(response, messages)
+    assert allows_conversation_message_merge(messages[-1]) is False
+
+    messages.append(controller.project_response_message(
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [{"id": "call_1", "type": "function"}],
+        },
+        response,
+    ))
+    tool_message = {
+        "role": "tool",
+        "tool_call_id": "call_1",
+        "content": "tool result",
+    }
+    messages.append(tool_message)
+
+    provider_context = controller.prepare_request(
+        messages,
+        context_window_tokens=200_000,
+    )
+
+    assert provider_context is not None
+    assert provider_context.conversation_state is not None
+    assert provider_context.conversation_state.payload == state.payload
+    assert provider_context.conversation_state.pending_messages == [tool_message]
+    assert controller.checkpoint(messages).pending_messages == [tool_message]
+
+
+def test_controller_uses_governed_messages_for_provider_state_delta() -> None:
+    provider = _provider()
+    messages = [
+        {"role": "user", "content": "run a tool"},
+    ]
+    controller = ProviderConversationStateController(
+        provider=provider,
+        model="gpt-5.6",
+        messages=messages,
+    )
+    state = _state("first")
+
+    controller.prepare_request(messages, context_window_tokens=200_000)
+    response = LLMResponse(content=None, provider_state=state)
+    controller.observe_response(response, messages)
+    messages.extend([
+        controller.project_response_message(
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [{"id": "call_1", "type": "function"}],
+            },
+            response,
+        ),
+        {
+            "role": "tool",
+            "tool_call_id": "call_1",
+            "content": "raw oversized result",
+        },
+    ])
+    governed_messages = [
+        messages[0],
+        messages[1],
+        {
+            "role": "tool",
+            "tool_call_id": "call_1",
+            "content": "compacted result",
+        },
+    ]
+
+    provider_context = controller.prepare_request(
+        messages,
+        context_window_tokens=200_000,
+        model_messages=governed_messages,
+    )
+
+    assert provider_context is not None
+    assert provider_context.conversation_state is not None
+    assert provider_context.conversation_state.pending_messages == [{
+        "role": "tool",
+        "tool_call_id": "call_1",
+        "content": "compacted result",
+    }]
+    assert controller.checkpoint(messages).pending_messages[-1]["content"] == (
+        "raw oversized result"
+    )
+    governed_checkpoint = controller.checkpoint(
+        messages,
+        model_messages=governed_messages,
+    )
+    assert governed_checkpoint is not None
+    assert governed_checkpoint.pending_messages[-1]["content"] == "compacted result"
+
+
+def test_transient_response_preserves_only_durable_request_messages() -> None:
+    provider = _provider()
+    current_message = {"role": "user", "content": "continue"}
+    supplemental = {"role": "user", "content": "internal finalization retry"}
+    messages = [{"role": "system", "content": "system"}, current_message]
+    controller = ProviderConversationStateController(
+        provider=provider,
+        model="gpt-5.6",
+        messages=messages,
+        state=_state("saved", pending=[
+            {"role": "tool", "content": "prior"},
+            current_message,
+        ]),
+    )
+
+    provider_context = controller.prepare_request(
+        messages,
+        context_window_tokens=200_000,
+        supplemental_messages=[supplemental],
+    )
+    assert provider_context is not None
+    assert provider_context.conversation_state is not None
+    assert provider_context.conversation_state.pending_messages == [
+        {"role": "tool", "content": "prior"},
+        current_message,
+        supplemental,
+    ]
+
+    controller.observe_response(
+        LLMResponse(
+            content="temporary failure",
+            finish_reason="error",
+            error_kind="timeout",
+        ),
+        messages,
+    )
+    placeholder = {"role": "assistant", "content": "model error"}
+    messages.append(placeholder)
+
+    state = controller.finish(messages)
+    assert state is not None
+    assert state.pending_messages == [
+        {"role": "tool", "content": "prior"},
+        current_message,
+        placeholder,
+    ]
+
+
+def test_non_retryable_response_discards_saved_state() -> None:
+    provider = _provider()
+    messages = [{"role": "user", "content": "continue"}]
+    controller = ProviderConversationStateController(
+        provider=provider,
+        model="gpt-5.6",
+        messages=messages,
+        state=_state("saved"),
+    )
+
+    controller.prepare_request(messages, context_window_tokens=200_000)
+    controller.observe_response(
+        LLMResponse(
+            content="invalid request",
+            finish_reason="error",
+            error_status_code=400,
+            error_should_retry=False,
+        ),
+        messages,
+    )
+
+    assert controller.finish(messages) is None
+
+
+@pytest.mark.parametrize(
+    ("finish_reason", "exposes_tool_call"),
+    [
+        ("length", False),
+        ("length", True),
+        ("refusal", True),
+        ("content_filter", True),
+    ],
+)
+def test_terminal_response_discards_candidate_state(
+    finish_reason: str,
+    exposes_tool_call: bool,
+) -> None:
+    provider = _provider()
+    messages = [{"role": "user", "content": "continue"}]
+    controller = ProviderConversationStateController(
+        provider=provider,
+        model="gpt-5.6",
+        messages=messages,
+        state=_state("saved"),
+    )
+
+    controller.prepare_request(messages, context_window_tokens=200_000)
+    candidate = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload={
+            "items": [{
+                "type": "function_call",
+                "call_id": "call_1",
+                "name": "exec",
+                "arguments": "{}",
+            }],
+        },
+    )
+    response = LLMResponse(
+        content="terminal response",
+        tool_calls=(
+            [ToolCallRequest(id="call_1", name="exec", arguments={})]
+            if exposes_tool_call
+            else []
+        ),
+        finish_reason=finish_reason,
+        provider_state=candidate,
+    )
+    assert response.has_tool_calls is exposes_tool_call
+    assert response.should_execute_tools is False
+
+    controller.observe_response(response, messages)
+
+    assert controller.finish(messages) is None
+
+
+def test_independent_request_exposes_context_without_capability_check() -> None:
+    provider = _provider(compact=False)
+    messages = [{"role": "user", "content": "hello"}]
+    controller = ProviderConversationStateController(
+        provider=provider,
+        model="gpt-5.6",
+        messages=messages,
+        state=_state("saved"),
+    )
+
+    provider_context = controller.independent_request_context(
+        context_window_tokens=200_000,
+    )
+    assert provider_context is not None
+    assert provider_context.conversation_state is None
+    assert provider_context.context_window_tokens == 200_000
+    provider.supports_native_compaction.assert_not_called()

tests/providers/test_github_copilot_routing.py

@@ -10,6 +10,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
+from nanobot.providers.base import ProviderCallContext
 from nanobot.providers.openai_compat_provider import OpenAICompatProvider
 from nanobot.providers.registry import find_by_name
 
@@ -44,8 +45,10 @@ def test_build_responses_body_strips_github_copilot_prefix():
         temperature=0.1,
         reasoning_effort=None,
         tool_choice=None,
+        provider_context=ProviderCallContext(context_window_tokens=128_000),
     )
     assert body["model"] == "gpt-5.4-mini"
+    assert "context_management" not in body
 
 
 @pytest.mark.asyncio

tests/providers/test_litellm_kwargs.py

@@ -14,6 +14,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
+from nanobot.providers.base import ProviderCallContext
 from nanobot.providers.openai_compat_provider import OpenAICompatProvider
 from nanobot.providers.registry import find_by_name
 
@@ -679,6 +680,7 @@ async def test_direct_openai_gpt5_uses_responses_api() -> None:
     assert call_kwargs["max_output_tokens"] == 4096
     assert "input" in call_kwargs
     assert "messages" not in call_kwargs
+    assert call_kwargs["include"] == ["reasoning.encrypted_content"]
 
 
 @pytest.mark.asyncio
@@ -710,6 +712,40 @@ async def test_direct_openai_reasoning_prefers_responses_api() -> None:
     assert call_kwargs["include"] == ["reasoning.encrypted_content"]
 
 
+@pytest.mark.asyncio
+async def test_direct_openai_retries_without_unsupported_server_compaction() -> None:
+    mock_chat = AsyncMock(return_value=_fake_chat_response())
+    mock_responses = AsyncMock(side_effect=[
+        _FakeResponsesError(400, "Unknown parameter: context_management"),
+        _fake_responses_response("compaction fallback"),
+    ])
+    spec = find_by_name("openai")
+
+    with patch("nanobot.providers.openai_compat_provider.AsyncOpenAI") as mock_client_class:
+        client_instance = mock_client_class.return_value
+        client_instance.chat.completions.create = mock_chat
+        client_instance.responses.create = mock_responses
+        provider = OpenAICompatProvider(
+            api_key="sk-test-key",
+            default_model="gpt-5.6",
+            spec=spec,
+        )
+
+        result = await provider.chat_with_context(
+            messages=[{"role": "user", "content": "hello"}],
+            model="gpt-5.6",
+            provider_context=ProviderCallContext(context_window_tokens=200_000),
+        )
+
+    assert result.content == "compaction fallback"
+    assert result.provider_state is not None
+    assert mock_responses.await_count == 2
+    assert "context_management" in mock_responses.call_args_list[0].kwargs
+    assert "context_management" not in mock_responses.call_args_list[1].kwargs
+    assert provider.supports_native_compaction("gpt-5.6") is False
+    mock_chat.assert_not_awaited()
+
+
 @pytest.mark.asyncio
 async def test_direct_openai_gpt4o_stays_on_chat_completions() -> None:
     mock_chat = AsyncMock(return_value=_fake_chat_response())

tests/providers/test_openai_codex_oauth.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from urllib.parse import parse_qs, urlencode, urlsplit
+
+import pytest
+from oauth_cli_kit.models import OAuthToken
+
+import nanobot.providers.openai_codex_oauth as codex_oauth
+from nanobot.providers.openai_codex_oauth import (
+    OpenAICodexOAuthError,
+    OpenAICodexOAuthInputError,
+    complete_openai_codex_oauth_login,
+    start_openai_codex_oauth_login,
+)
+
+
+def _authorization_url(state: str = "expected-state") -> str:
+    return f"{codex_oauth.OPENAI_CODEX_PROVIDER.authorize_url}?{urlencode({'state': state})}"
+
+
+def _wait_for_completion(flow) -> OAuthToken:
+    deadline = time.monotonic() + 1
+    while time.monotonic() < deadline:
+        token = complete_openai_codex_oauth_login(flow)
+        if token is not None:
+            return token
+        time.sleep(0.01)
+    pytest.fail("OAuth flow did not finish")
+
+
+def _fake_interactive_login(
+    captured: dict[str, object],
+    *,
+    error: Exception | None = None,
+) -> Callable[..., OAuthToken]:
+    def login(
+        *,
+        print_fn,
+        prompt_fn,
+        provider,
+        proxy,
+        open_browser,
+    ) -> OAuthToken:
+        captured.update(
+            provider=provider,
+            proxy=proxy,
+            open_browser=open_browser,
+        )
+        print_fn("Open this URL:")
+        print_fn(_authorization_url())
+        if not open_browser:
+            captured["callback_url"] = prompt_fn("Paste callback URL")
+        if error is not None:
+            raise error
+        return OAuthToken(
+            access="access-token",
+            refresh="refresh-token",
+            expires=2_000_000_000_000,
+            account_id="acct-test",
+        )
+
+    return login
+
+
+def test_authorization_url_comes_from_oauth_cli_kit() -> None:
+    flow = start_openai_codex_oauth_login(
+        timeout_s=2,
+        open_browser=False,
+    )
+    try:
+        params = parse_qs(urlsplit(flow.authorization_url).query)
+        assert params["response_type"] == ["code"]
+        assert params["client_id"] == [codex_oauth.OPENAI_CODEX_PROVIDER.client_id]
+        assert params["redirect_uri"] == [codex_oauth.OPENAI_CODEX_PROVIDER.redirect_uri]
+        assert params["code_challenge_method"] == ["S256"]
+        assert params["code_challenge"]
+        assert params["state"]
+    finally:
+        flow.cancel()
+
+
+def test_local_flow_delegates_browser_and_callback_to_public_oauth_cli_kit(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, object] = {}
+    monkeypatch.setattr(
+        codex_oauth,
+        "login_oauth_interactive",
+        _fake_interactive_login(captured),
+    )
+    flow = start_openai_codex_oauth_login(timeout_s=5)
+
+    try:
+        token = _wait_for_completion(flow)
+    finally:
+        flow.cancel()
+
+    assert token.account_id == "acct-test"
+    assert captured == {
+        "provider": codex_oauth.OPENAI_CODEX_PROVIDER,
+        "proxy": None,
+        "open_browser": True,
+    }
+
+
+def test_remote_flow_delegates_pasted_callback_to_public_oauth_cli_kit(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, object] = {}
+    monkeypatch.setattr(
+        codex_oauth,
+        "login_oauth_interactive",
+        _fake_interactive_login(captured),
+    )
+    flow = start_openai_codex_oauth_login(
+        proxy="http://127.0.0.1:7890",
+        timeout_s=5,
+        open_browser=False,
+    )
+    callback_url = (
+        "http://localhost:1455/auth/callback?"
+        + urlencode({"code": "authorization-code", "state": "expected-state"})
+    )
+    try:
+        assert complete_openai_codex_oauth_login(flow) is None
+        with pytest.raises(OpenAICodexOAuthInputError, match="full callback URL"):
+            complete_openai_codex_oauth_login(flow, "authorization-code")
+        token = complete_openai_codex_oauth_login(flow, callback_url)
+        if token is None:
+            token = _wait_for_completion(flow)
+    finally:
+        flow.cancel()
+
+    assert token is not None
+    assert token.account_id == "acct-test"
+    assert captured == {
+        "provider": codex_oauth.OPENAI_CODEX_PROVIDER,
+        "proxy": "http://127.0.0.1:7890",
+        "open_browser": False,
+        "callback_url": callback_url,
+    }
+
+
+def test_remote_flow_rejects_callback_from_another_login(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, object] = {}
+    monkeypatch.setattr(
+        codex_oauth,
+        "login_oauth_interactive",
+        _fake_interactive_login(captured),
+    )
+    flow = start_openai_codex_oauth_login(
+        timeout_s=5,
+        open_browser=False,
+    )
+    callback_url = (
+        "http://localhost:1455/auth/callback?"
+        + urlencode({"code": "authorization-code", "state": "wrong-state"})
+    )
+    try:
+        with pytest.raises(OpenAICodexOAuthInputError, match="does not belong"):
+            complete_openai_codex_oauth_login(flow, callback_url)
+        assert "callback_url" not in captured
+    finally:
+        flow.cancel()
+
+
+def test_remote_flow_reports_authorization_denial_without_exchanging_code(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, object] = {}
+    monkeypatch.setattr(
+        codex_oauth,
+        "login_oauth_interactive",
+        _fake_interactive_login(captured),
+    )
+    flow = start_openai_codex_oauth_login(
+        timeout_s=5,
+        open_browser=False,
+    )
+    callback_url = (
+        "http://localhost:1455/auth/callback?"
+        + urlencode({"error": "access_denied", "state": "expected-state"})
+    )
+    try:
+        with pytest.raises(OpenAICodexOAuthError, match="authorization server"):
+            complete_openai_codex_oauth_login(flow, callback_url)
+    finally:
+        flow.cancel()
+
+    assert "callback_url" not in captured
+
+
+def test_dependency_error_is_bounded_and_does_not_expose_callback(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: dict[str, object] = {}
+    monkeypatch.setattr(
+        codex_oauth,
+        "login_oauth_interactive",
+        _fake_interactive_login(
+            captured,
+            error=RuntimeError("Token exchange failed: 400 secret-code upstream-body"),
+        ),
+    )
+    flow = start_openai_codex_oauth_login(
+        timeout_s=5,
+        open_browser=False,
+    )
+    callback_url = (
+        "http://localhost:1455/auth/callback?"
+        + urlencode({"code": "secret-code", "state": "expected-state"})
+    )
+    try:
+        with pytest.raises(OpenAICodexOAuthError) as exc:
+            token = complete_openai_codex_oauth_login(flow, callback_url)
+            if token is None:
+                _wait_for_completion(flow)
+    finally:
+        flow.cancel()
+
+    assert str(exc.value) == "OpenAI Codex OAuth token exchange failed with HTTP 400."
+    assert "secret-code" not in str(exc.value)
+
+
+def test_remote_flow_expires_while_waiting_for_callback(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        codex_oauth,
+        "login_oauth_interactive",
+        _fake_interactive_login({}),
+    )
+    flow = start_openai_codex_oauth_login(
+        timeout_s=0.05,
+        open_browser=False,
+    )
+    try:
+        time.sleep(0.08)
+        with pytest.raises(OpenAICodexOAuthError, match="expired"):
+            complete_openai_codex_oauth_login(flow)
+    finally:
+        flow.cancel()

tests/providers/test_openai_codex_provider.py

@@ -20,6 +20,7 @@ from nanobot.providers.openai_codex_provider import (
     _request_codex,
     _should_retry_status,
 )
+from nanobot.providers.openai_responses import build_responses_state
 from nanobot.providers.registry import find_by_name
 
 
@@ -115,6 +116,48 @@ async def test_codex_request_non_200_populates_http_metadata(monkeypatch) -> Non
     assert error.should_retry is True
 
 
+@pytest.mark.asyncio
+async def test_codex_request_marks_rejected_compaction_without_retaining_raw_body(
+    monkeypatch,
+) -> None:
+    original_client = httpx.AsyncClient
+    secret = "PRIVATE PROMPT MUST NOT BE RETAINED"
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            400,
+            json={
+                "error": {
+                    "message": f"Unknown input type compaction_trigger; {secret}",
+                },
+            },
+            request=request,
+        )
+
+    def fake_client(
+        *,
+        timeout: int,
+        verify: bool,
+        **_kwargs: object,
+    ) -> httpx.AsyncClient:
+        return original_client(transport=httpx.MockTransport(handler), timeout=timeout)
+
+    monkeypatch.setattr("nanobot.providers.openai_codex_provider.httpx.AsyncClient", fake_client)
+
+    with pytest.raises(_CodexHTTPError) as caught:
+        await _request_codex(
+            "https://codex.example/responses",
+            {},
+            {"input": [{"type": "compaction_trigger"}]},
+            verify=True,
+        )
+
+    error = caught.value
+    assert error.compaction_unsupported is True
+    assert secret not in str(error)
+    assert not hasattr(error, "body")
+
+
 @pytest.mark.asyncio
 async def test_codex_request_honors_stream_idle_timeout_env(monkeypatch) -> None:
     """NANOBOT_STREAM_IDLE_TIMEOUT_S overrides the default Codex stream timeout."""
@@ -192,7 +235,7 @@ async def test_codex_prompt_cache_key_uses_stable_conversation_prefix(monkeypatc
     ):
         _ = proxy, on_thinking_delta, on_tool_call_delta
         bodies.append(body)
-        return "ok", [], "stop", {}, None
+        return provider_base.LLMResponse(content="ok")
 
     monkeypatch.setattr("nanobot.providers.openai_codex_provider._request_codex", fake_request)
 
@@ -232,7 +275,7 @@ async def test_codex_provider_applies_extra_body_from_config(monkeypatch) -> Non
 
     async def fake_request(_url, _headers, body, **_kwargs):
         bodies.append(body)
-        return "ok", [], "stop", {}, None
+        return provider_base.LLMResponse(content="ok")
 
     monkeypatch.setattr("nanobot.providers.openai_codex_provider._request_codex", fake_request)
     config = Config.model_validate({
@@ -297,7 +340,7 @@ async def test_codex_provider_passes_proxy_to_oauth_and_response_request(monkeyp
     ):
         _ = url, headers, body, verify, on_content_delta, on_thinking_delta, on_tool_call_delta
         seen["request_proxy"] = proxy
-        return "ok", [], "stop", {}, None
+        return provider_base.LLMResponse(content="ok")
 
     monkeypatch.setattr("nanobot.providers.openai_codex_provider.get_codex_token", fake_token)
     monkeypatch.setattr("nanobot.providers.openai_codex_provider._request_codex", fake_request)
@@ -384,7 +427,7 @@ async def test_codex_retry_uses_structured_timeout_metadata(monkeypatch) -> None
         calls += 1
         if calls == 1:
             raise httpx.ReadTimeout("")
-        return "ok", [], "stop", {}, None
+        return provider_base.LLMResponse(content="ok")
 
     async def fake_sleep(delay: float) -> None:
         delays.append(delay)
@@ -533,6 +576,254 @@ def test_codex_reasoning_options_request_summary_without_forcing_effort() -> Non
     assert _build_reasoning_options("none") == {"effort": "none"}
 
 
+@pytest.mark.asyncio
+async def test_codex_replayed_tool_turn_omits_server_item_ids(monkeypatch) -> None:
+    _mock_codex_token(monkeypatch)
+    provider = OpenAICodexProvider(default_model="openai-codex/gpt-5.6-sol")
+    state = build_responses_state(
+        provider=provider._responses_state_provider(),
+        model="gpt-5.6-sol",
+        input_items=[{
+            "id": "msg_user",
+            "type": "message",
+            "role": "user",
+            "content": [{"type": "input_text", "text": "Check the weather"}],
+        }],
+        output_items=[
+            {
+                "id": "rs_reasoning",
+                "type": "reasoning",
+                "encrypted_content": "opaque reasoning",
+                "summary": [],
+            },
+            {
+                "id": "fc_read",
+                "type": "function_call",
+                "call_id": "call_read",
+                "name": "read_file",
+                "arguments": '{"path":"weather/SKILL.md"}',
+                "status": "completed",
+            },
+        ],
+    )
+    bodies: list[dict[str, Any]] = []
+
+    async def fake_request(
+        url,
+        headers,
+        body,
+        verify,
+        proxy=None,
+        on_content_delta=None,
+        on_thinking_delta=None,
+        on_tool_call_delta=None,
+    ):
+        bodies.append(body)
+        return provider_base.LLMResponse(content="done")
+
+    monkeypatch.setattr(
+        "nanobot.providers.openai_codex_provider._request_codex",
+        fake_request,
+    )
+
+    response = await provider.chat(
+        [{"role": "user", "content": "Check the weather"}],
+        provider_context=provider_base.ProviderCallContext(
+            conversation_state=state.with_pending_messages([{
+                "role": "tool",
+                "tool_call_id": "call_read|fc_read",
+                "content": "weather skill contents",
+            }]),
+        ),
+    )
+
+    assert response.content == "done"
+    assert len(bodies) == 1
+    input_items = bodies[0]["input"]
+    assert [item.get("type") for item in input_items] == [
+        "message",
+        "reasoning",
+        "function_call",
+        "function_call_output",
+    ]
+    assert all("id" not in item for item in input_items)
+    assert input_items[1]["encrypted_content"] == "opaque reasoning"
+    assert input_items[2]["call_id"] == "call_read"
+    assert input_items[3]["call_id"] == "call_read"
+
+
+@pytest.mark.asyncio
+async def test_codex_compacts_state_at_ninety_percent_before_next_request(
+    monkeypatch,
+) -> None:
+    _mock_codex_token(monkeypatch)
+    provider = OpenAICodexProvider(default_model="openai-codex/gpt-5.6-sol")
+    state_provider = provider._responses_state_provider()
+    state = build_responses_state(
+        provider=state_provider,
+        model="gpt-5.6-sol",
+        input_items=[{"type": "message", "role": "user", "content": "old question"}],
+        output_items=[
+            {"type": "reasoning", "encrypted_content": "old opaque reasoning"},
+            {
+                "type": "message",
+                "role": "assistant",
+                "content": [{"type": "output_text", "text": "old answer"}],
+            },
+        ],
+        usage={
+            "prompt_tokens": 90,
+            "completion_tokens": 5,
+            "total_tokens": 95,
+        },
+    )
+    bodies: list[dict[str, Any]] = []
+
+    async def fake_request(
+        url,
+        headers,
+        body,
+        verify,
+        proxy=None,
+        on_content_delta=None,
+        on_thinking_delta=None,
+        on_tool_call_delta=None,
+    ):
+        _ = (
+            url,
+            headers,
+            verify,
+            proxy,
+            on_content_delta,
+            on_thinking_delta,
+            on_tool_call_delta,
+        )
+        bodies.append(body)
+        if body["input"][-1].get("type") == "compaction_trigger":
+            compact_item = {
+                "type": "compaction",
+                "encrypted_content": "compacted opaque state",
+            }
+            return provider_base.LLMResponse(
+                content=None,
+                provider_state=build_responses_state(
+                    provider=state_provider,
+                    model="gpt-5.6-sol",
+                    input_items=body["input"],
+                    output_items=[compact_item],
+                    usage={
+                        "prompt_tokens": 95,
+                        "completion_tokens": 2,
+                        "total_tokens": 97,
+                    },
+                ),
+            )
+        return provider_base.LLMResponse(content="done")
+
+    monkeypatch.setattr(
+        "nanobot.providers.openai_codex_provider._request_codex",
+        fake_request,
+    )
+
+    response = await provider.chat_with_retry(
+        [
+            {"role": "system", "content": "system"},
+            {"role": "user", "content": "new question"},
+        ],
+        max_tokens=5,
+        provider_context=provider_base.ProviderCallContext(
+            conversation_state=state.with_pending_messages([
+                {"role": "user", "content": "new question"},
+            ]),
+            context_window_tokens=100,
+        ),
+    )
+
+    assert response.content == "done"
+    assert len(bodies) == 2
+    assert bodies[0]["input"][-1] == {"type": "compaction_trigger"}
+    assert bodies[1]["input"][-1] == {
+        "type": "compaction",
+        "encrypted_content": "compacted opaque state",
+    }
+    assert not any(
+        item.get("type") == "reasoning"
+        for item in bodies[1]["input"]
+    )
+    assert any(
+        item.get("role") == "user"
+        and "new question" in str(item.get("content"))
+        for item in bodies[1]["input"]
+    )
+
+
+@pytest.mark.asyncio
+async def test_codex_disables_unsupported_native_compaction_and_continues(
+    monkeypatch,
+) -> None:
+    _mock_codex_token(monkeypatch)
+    provider = OpenAICodexProvider(default_model="openai-codex/gpt-5.6-sol")
+    state_provider = provider._responses_state_provider()
+    state = build_responses_state(
+        provider=state_provider,
+        model="gpt-5.6-sol",
+        input_items=[{"type": "message", "role": "user", "content": "old"}],
+        output_items=[{"type": "reasoning", "encrypted_content": "opaque"}],
+        usage={"prompt_tokens": 90, "completion_tokens": 5, "total_tokens": 95},
+    )
+    bodies: list[dict[str, Any]] = []
+
+    async def fake_request(
+        url,
+        headers,
+        body,
+        verify,
+        proxy=None,
+        on_content_delta=None,
+        on_thinking_delta=None,
+        on_tool_call_delta=None,
+    ):
+        _ = (
+            url,
+            headers,
+            verify,
+            proxy,
+            on_content_delta,
+            on_thinking_delta,
+            on_tool_call_delta,
+        )
+        bodies.append(body)
+        if body["input"][-1].get("type") == "compaction_trigger":
+            raise _CodexHTTPError(
+                "HTTP 400: Codex API request failed",
+                status_code=400,
+                compaction_unsupported=True,
+            )
+        return provider_base.LLMResponse(content="done")
+
+    monkeypatch.setattr(
+        "nanobot.providers.openai_codex_provider._request_codex",
+        fake_request,
+    )
+
+    response = await provider.chat(
+        [{"role": "user", "content": "new"}],
+        max_tokens=5,
+        provider_context=provider_base.ProviderCallContext(
+            conversation_state=state.with_pending_messages([
+                {"role": "user", "content": "new"},
+            ]),
+            context_window_tokens=100,
+        ),
+    )
+
+    assert response.content == "done"
+    assert len(bodies) == 2
+    assert bodies[0]["input"][-1] == {"type": "compaction_trigger"}
+    assert bodies[1]["input"][-1] != {"type": "compaction_trigger"}
+    assert provider.supports_native_compaction() is False
+
+
 @pytest.mark.asyncio
 async def test_codex_stream_surfaces_reasoning_summary(monkeypatch) -> None:
     def fake_token(**_kwargs):
@@ -559,7 +850,12 @@ async def test_codex_stream_surfaces_reasoning_summary(monkeypatch) -> None:
             await on_content_delta("answer")
         if on_thinking_delta:
             await on_thinking_delta("summary")
-        return "answer", [], "stop", {"prompt_tokens": 10, "completion_tokens": 5}, "summary"
+        return provider_base.LLMResponse(
+            content="answer",
+            finish_reason="stop",
+            usage={"prompt_tokens": 10, "completion_tokens": 5},
+            reasoning_content="summary",
+        )
 
     monkeypatch.setattr("nanobot.providers.openai_codex_provider._request_codex", fake_request)
 

tests/providers/test_openai_responses.py

@@ -1,9 +1,11 @@
 """Tests for the shared openai_responses converters and parsers."""
 
 import json
+from io import StringIO
 from unittest.mock import MagicMock, patch
 
 import pytest
+from loguru import logger
 
 from nanobot.providers.openai_responses.converters import (
     convert_messages,
@@ -12,12 +14,22 @@ from nanobot.providers.openai_responses.converters import (
     split_tool_call_id,
 )
 from nanobot.providers.openai_responses.parsing import (
+    ResponsesStreamCapture,
     consume_sdk_stream,
     consume_sse,
     consume_sse_with_reasoning,
+    is_replayable_finish_reason,
     map_finish_reason,
     parse_response_output,
 )
+from nanobot.providers.openai_responses.state import (
+    build_responses_state,
+    is_compaction_compatibility_error,
+    prepare_responses_input,
+    resolve_compact_threshold,
+    responses_state_context_tokens,
+    responses_state_items,
+)
 
 # ======================================================================
 # converters - split_tool_call_id
@@ -398,6 +410,17 @@ class TestMapFinishReason:
     def test_unknown_defaults_to_stop(self):
         assert map_finish_reason("some_new_status") == "stop"
 
+    @pytest.mark.parametrize("finish_reason", ["stop", "tool_calls", "function_call"])
+    def test_replayable_finish_reasons(self, finish_reason):
+        assert is_replayable_finish_reason(finish_reason) is True
+
+    @pytest.mark.parametrize(
+        "finish_reason",
+        ["length", "refusal", "content_filter", "error"],
+    )
+    def test_non_replayable_finish_reasons(self, finish_reason):
+        assert is_replayable_finish_reason(finish_reason) is False
+
 
 # ======================================================================
 # parsing - parse_response_output
@@ -418,6 +441,29 @@ class TestParseResponseOutput:
         assert result.usage == {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}
         assert result.tool_calls == []
 
+    def test_refusal_response_surfaces_text_without_advancing_state(self):
+        refusal = "I can’t help with that request."
+        resp = {
+            "output": [{
+                "type": "message",
+                "role": "assistant",
+                "content": [{"type": "refusal", "refusal": refusal}],
+            }],
+            "status": "completed",
+            "usage": {},
+        }
+
+        result = parse_response_output(
+            resp,
+            state_provider="openai:test",
+            state_model="gpt-5.6",
+            state_input_items=[{"role": "user", "content": "request"}],
+        )
+
+        assert result.content == refusal
+        assert result.finish_reason == "refusal"
+        assert result.provider_state is None
+
     def test_tool_call_response(self):
         resp = {
             "output": [{
@@ -429,12 +475,18 @@ class TestParseResponseOutput:
             "status": "completed",
             "usage": {},
         }
-        result = parse_response_output(resp)
+        result = parse_response_output(
+            resp,
+            state_provider="openai:test",
+            state_model="gpt-5.6",
+            state_input_items=[{"role": "user", "content": "weather?"}],
+        )
         assert result.content is None
         assert len(result.tool_calls) == 1
         assert result.tool_calls[0].name == "get_weather"
         assert result.tool_calls[0].arguments == {"city": "SF"}
         assert result.tool_calls[0].id == "call_1|fc_1"
+        assert result.provider_state is not None
 
     def test_malformed_tool_arguments_logged(self):
         """Malformed JSON arguments should log a warning and remain non-object."""
@@ -493,10 +545,39 @@ class TestParseResponseOutput:
         assert result.content is None
         assert result.tool_calls == []
 
-    def test_incomplete_status(self):
-        resp = {"output": [], "status": "incomplete", "usage": {}}
-        result = parse_response_output(resp)
-        assert result.finish_reason == "length"
+    @pytest.mark.parametrize(
+        ("reason", "expected_finish_reason"),
+        [
+            ("max_output_tokens", "length"),
+            ("content_filter", "content_filter"),
+        ],
+    )
+    def test_incomplete_status(self, reason, expected_finish_reason):
+        resp = {
+            "output": [],
+            "status": "incomplete",
+            "incomplete_details": {"reason": reason},
+            "usage": {},
+        }
+        result = parse_response_output(
+            resp,
+            state_provider="openai:test",
+            state_model="gpt-5.6",
+            state_input_items=[{"role": "user", "content": "prompt"}],
+        )
+        assert result.finish_reason == expected_finish_reason
+        assert result.provider_state is None
+
+    def test_unknown_status_does_not_advance_provider_state(self):
+        result = parse_response_output(
+            {"output": [], "status": "future_terminal_status", "usage": {}},
+            state_provider="openai:test",
+            state_model="gpt-5.6",
+            state_input_items=[{"role": "user", "content": "prompt"}],
+        )
+
+        assert result.finish_reason == "stop"
+        assert result.provider_state is None
 
     def test_sdk_model_object(self):
         """parse_response_output should handle SDK objects with model_dump()."""
@@ -523,6 +604,194 @@ class TestParseResponseOutput:
         assert result.usage["completion_tokens"] == 50
         assert result.usage["total_tokens"] == 150
 
+    def test_preserves_every_output_item_as_opaque_state(self):
+        input_items = [{"role": "user", "content": "inspect the repo"}]
+        output = [
+            {
+                "id": "rs_1",
+                "type": "reasoning",
+                "encrypted_content": "opaque-secret",
+                "summary": [],
+            },
+            {
+                "id": "future_1",
+                "type": "future_item_type",
+                "provider_field": {"nested": True},
+            },
+            {
+                "id": "msg_1",
+                "type": "message",
+                "role": "assistant",
+                "status": "completed",
+                "content": [{"type": "output_text", "text": "done"}],
+            },
+        ]
+
+        result = parse_response_output(
+            {"output": output, "status": "completed", "usage": {}},
+            state_provider="openai:test",
+            state_model="gpt-5.6",
+            state_input_items=input_items,
+        )
+
+        assert result.provider_state is not None
+        assert responses_state_items(result.provider_state) == [*input_items, *output]
+
+
+class TestResponsesConversationState:
+    def test_server_compaction_prunes_superseded_prefix(self):
+        state = build_responses_state(
+            provider="openai:test",
+            model="gpt-5.6",
+            input_items=[
+                {"type": "message", "role": "user", "content": "old"},
+                {"type": "reasoning", "encrypted_content": "old-reasoning"},
+            ],
+            output_items=[
+                {"type": "compaction", "encrypted_content": "compact"},
+                {"type": "message", "role": "assistant", "content": "new"},
+            ],
+            usage={
+                "prompt_tokens": 90,
+                "completion_tokens": 10,
+                "total_tokens": 100,
+            },
+        )
+
+        assert responses_state_items(state) == [
+            {"type": "compaction", "encrypted_content": "compact"},
+            {"type": "message", "role": "assistant", "content": "new"},
+        ]
+        assert responses_state_context_tokens(state) == 100
+
+    def test_existing_compaction_keeps_canonical_retained_prefix(self):
+        canonical_input = [
+            {"type": "message", "role": "user", "content": "retained"},
+            {"type": "compaction", "encrypted_content": "compact"},
+        ]
+        output = [{"type": "message", "role": "assistant", "content": "new"}]
+
+        state = build_responses_state(
+            provider="openai:test",
+            model="gpt-5.6",
+            input_items=canonical_input,
+            output_items=output,
+        )
+
+        assert responses_state_items(state) == [*canonical_input, *output]
+
+    @pytest.mark.parametrize(
+        ("context_window", "max_output", "expected"),
+        [
+            (200_000, 20_000, 180_000),
+            (100_000, 30_000, 70_000),
+            (0, 4_096, None),
+        ],
+    )
+    def test_compact_threshold_reserves_codex_style_headroom(
+        self,
+        context_window,
+        max_output,
+        expected,
+    ):
+        assert resolve_compact_threshold(context_window, max_output) == expected
+
+    def test_compaction_compatibility_recognizes_old_sdk_signature_error(self):
+        error = TypeError("create() got an unexpected keyword argument 'context_management'")
+        assert is_compaction_compatibility_error(error) is True
+        assert is_compaction_compatibility_error(TypeError("unrelated argument")) is False
+
+    def test_state_observability_logs_counts_without_opaque_content(self):
+        secret = "opaque-secret-that-must-not-be-logged"
+        state = build_responses_state(
+            provider=f"openai:https://example.test/?key={secret}",
+            model=f"secret-model-{secret}",
+            input_items=[{"role": "user", "content": secret}],
+            output_items=[{"type": "reasoning", "encrypted_content": secret}],
+        ).with_pending_messages([{"role": "user", "content": secret}])
+        sink = StringIO()
+        sink_id = logger.add(sink, level="DEBUG", format="{message}")
+        try:
+            prepare_responses_input(
+                [{"role": "user", "content": secret}],
+                state=state,
+                provider=state.provider,
+                model=state.model,
+            )
+            build_responses_state(
+                provider=state.provider,
+                model=state.model,
+                input_items=[
+                    {"role": "user", "content": secret},
+                    {"type": "reasoning", "encrypted_content": secret},
+                ],
+                output_items=[
+                    {"type": "compaction", "encrypted_content": secret},
+                ],
+            )
+        finally:
+            logger.remove(sink_id)
+
+        log_text = sink.getvalue()
+        assert "prior_items=2" in log_text
+        assert "pending_messages=1" in log_text
+        assert "dropped_items=2" in log_text
+        assert secret not in log_text
+
+    def test_replays_exact_items_then_only_pending_and_new_messages(self):
+        prior_items = [
+            {"role": "user", "content": "first"},
+            {
+                "type": "reasoning",
+                "id": "rs_1",
+                "encrypted_content": "opaque-secret",
+            },
+            {
+                "type": "function_call",
+                "id": "fc_1",
+                "call_id": "call_1",
+                "name": "read_file",
+                "arguments": '{"path":"a.py"}',
+            },
+        ]
+        state = build_responses_state(
+            provider="openai:test",
+            model="gpt-5.6",
+            input_items=prior_items[:1],
+            output_items=prior_items[1:],
+        ).with_pending_messages([
+            {
+                "role": "tool",
+                "tool_call_id": "call_1|fc_1",
+                "content": "file contents",
+            },
+            {"role": "user", "content": "continue"},
+        ])
+
+        instructions, items, replayed = prepare_responses_input(
+            [
+                {"role": "system", "content": "current instructions"},
+                {"role": "user", "content": "a lossy public transcript"},
+            ],
+            state=state,
+            provider="openai:test",
+            model="gpt-5.6",
+        )
+
+        assert instructions == "current instructions"
+        assert replayed is True
+        assert items[:3] == prior_items
+        assert items[3] == {
+            "type": "function_call_output",
+            "call_id": "call_1",
+            "output": "file contents",
+        }
+        assert items[4] == {
+            "role": "user",
+            "content": [{"type": "input_text", "text": "continue"}],
+        }
+        assert "lossy public transcript" not in str(items)
+
 
 # ======================================================================
 # parsing - consume_sse
@@ -553,6 +822,122 @@ class TestConsumeSse:
         assert tool_calls == []
         assert finish_reason == "stop"
 
+    @pytest.mark.asyncio
+    async def test_refusal_events_reconcile_parts_and_terminal_output(self):
+        refusal = "First and second sentence. Done-only. Terminal suffix."
+        terminal_response = {
+            "status": "completed",
+            "output": [{
+                "type": "message",
+                "id": "msg_2",
+                "role": "assistant",
+                "content": [{"type": "refusal", "refusal": refusal}],
+            }],
+        }
+        response = _SseResponse([
+            {
+                "type": "response.refusal.delta",
+                "item_id": "msg_1",
+                "content_index": 0,
+                "delta": "First",
+            },
+            {
+                "type": "response.refusal.delta",
+                "item_id": "msg_1",
+                "content_index": 1,
+                "delta": " and second",
+            },
+            {
+                "type": "response.refusal.done",
+                "item_id": "msg_1",
+                "content_index": 0,
+                "refusal": "First",
+            },
+            {
+                "type": "response.refusal.done",
+                "item_id": "msg_1",
+                "content_index": 1,
+                "refusal": " and second sentence.",
+            },
+            {
+                "type": "response.refusal.done",
+                "item_id": "msg_2",
+                "content_index": 0,
+                "refusal": " Done-only.",
+            },
+            {
+                "type": "response.refusal.delta",
+                "item_id": "msg_2",
+                "content_index": 1,
+                "delta": " Terminal",
+            },
+            {"type": "response.completed", "response": terminal_response},
+        ])
+        capture = ResponsesStreamCapture()
+        deltas: list[str] = []
+
+        async def on_content(delta: str) -> None:
+            deltas.append(delta)
+
+        content, _, finish_reason, _, _ = await consume_sse_with_reasoning(
+            response,
+            on_content_delta=on_content,
+            capture=capture,
+        )
+
+        assert content == refusal
+        assert deltas == [
+            "First",
+            " and second",
+            " sentence.",
+            " Done-only.",
+            " Terminal",
+            " suffix.",
+        ]
+        assert finish_reason == "refusal"
+        assert capture.completed is True
+        assert is_replayable_finish_reason(finish_reason) is False
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("source", ["events", "terminal"])
+    async def test_refusal_without_deltas_has_non_replayable_finish(self, source: str):
+        refusal = "I can’t help with that request."
+        terminal_response = {
+            "status": "completed",
+            "output": [{
+                "type": "message",
+                "id": "msg_1",
+                "role": "assistant",
+                "content": [{"type": "refusal", "refusal": refusal}],
+            }],
+        }
+        events = (
+            [
+                {"type": "response.refusal.done", "refusal": refusal},
+                {"type": "response.completed", "response": {"status": "completed"}},
+            ]
+            if source == "events"
+            else [{"type": "response.completed", "response": terminal_response}]
+        )
+        response = _SseResponse(events)
+        capture = ResponsesStreamCapture()
+        deltas: list[str] = []
+
+        async def on_content(delta: str) -> None:
+            deltas.append(delta)
+
+        content, _, finish_reason, _, _ = await consume_sse_with_reasoning(
+            response,
+            on_content_delta=on_content,
+            capture=capture,
+        )
+
+        assert content == refusal
+        assert deltas == [refusal]
+        assert finish_reason == "refusal"
+        assert capture.completed is True
+        assert is_replayable_finish_reason(finish_reason) is False
+
     @pytest.mark.asyncio
     async def test_reasoning_summary_delta_extracted(self):
         response = _SseResponse([
@@ -599,6 +984,139 @@ class TestConsumeSse:
 
         assert reasoning == "cached summary"
 
+    @pytest.mark.asyncio
+    async def test_capture_commits_exact_items_only_after_completed_event(self):
+        output = [
+            {
+                "type": "reasoning",
+                "id": "rs_1",
+                "encrypted_content": "opaque-secret",
+            },
+            {"type": "future_item_type", "id": "future_1", "value": 7},
+        ]
+        capture = ResponsesStreamCapture()
+        response = _SseResponse([
+            {
+                "type": "response.output_item.done",
+                "output_index": 0,
+                "item": output[0],
+            },
+            {
+                "type": "response.output_item.done",
+                "output_index": 1,
+                "item": output[1],
+            },
+            {
+                "type": "response.completed",
+                "response": {"status": "completed", "output": output},
+            },
+        ])
+
+        await consume_sse_with_reasoning(response, capture=capture)
+
+        assert capture.completed is True
+        assert capture.output_items == output
+
+    @pytest.mark.asyncio
+    async def test_capture_keeps_done_items_when_completed_output_is_empty(self):
+        output = [
+            {
+                "type": "reasoning",
+                "id": "rs_1",
+                "encrypted_content": "opaque-secret",
+                "summary": [],
+            },
+            {
+                "type": "function_call",
+                "id": "fc_1",
+                "call_id": "call_1",
+                "name": "read_file",
+                "arguments": '{"path":"weather/SKILL.md"}',
+            },
+        ]
+        capture = ResponsesStreamCapture()
+        response = _SseResponse([
+            {
+                "type": "response.output_item.done",
+                "output_index": index,
+                "item": item,
+            }
+            for index, item in enumerate(output)
+        ] + [{
+            "type": "response.completed",
+            "response": {"status": "completed", "output": []},
+        }])
+
+        await consume_sse_with_reasoning(response, capture=capture)
+
+        assert capture.completed is True
+        assert capture.output_items == output
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        ("reason", "expected_finish_reason"),
+        [
+            ("max_output_tokens", "length"),
+            ("content_filter", "content_filter"),
+        ],
+    )
+    async def test_incomplete_event_commits_capture_usage(
+        self,
+        reason,
+        expected_finish_reason,
+    ):
+        output = [
+            {
+                "type": "message",
+                "id": "msg_1",
+                "status": "incomplete",
+                "content": [{"type": "output_text", "text": "partial"}],
+            },
+        ]
+        terminal_response = {
+            "id": "resp_1",
+            "status": "incomplete",
+            "incomplete_details": {"reason": reason},
+            "output": output,
+            "usage": {"input_tokens": 10, "output_tokens": 5, "total_tokens": 15},
+        }
+        capture = ResponsesStreamCapture()
+        response = _SseResponse([
+            {"type": "response.output_text.delta", "delta": "partial"},
+            {"type": "response.incomplete", "response": terminal_response},
+        ])
+
+        content, _, finish_reason, usage, _ = await consume_sse_with_reasoning(
+            response,
+            capture=capture,
+        )
+
+        assert content == "partial"
+        assert finish_reason == expected_finish_reason
+        assert usage == {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}
+        assert capture.completed is True
+        assert capture.response == terminal_response
+        assert capture.output_items == output
+
+    @pytest.mark.asyncio
+    async def test_capture_does_not_commit_interrupted_stream(self):
+        capture = ResponsesStreamCapture()
+        response = _SseResponse([
+            {
+                "type": "response.output_item.done",
+                "output_index": 0,
+                "item": {
+                    "type": "reasoning",
+                    "id": "rs_1",
+                    "encrypted_content": "opaque-secret",
+                },
+            },
+        ])
+
+        await consume_sse_with_reasoning(response, capture=capture)
+
+        assert capture.completed is False
+
     @pytest.mark.asyncio
     async def test_reasoning_summary_from_done_item(self):
         response = _SseResponse([
@@ -755,6 +1273,131 @@ class TestConsumeSdkStream:
         assert tool_calls == []
         assert finish_reason == "stop"
 
+    @pytest.mark.asyncio
+    async def test_refusal_events_reconcile_parts_and_terminal_output(self):
+        refusal = "First and second sentence. Done-only. Terminal suffix."
+        terminal_response = {
+            "status": "completed",
+            "output": [{
+                "type": "message",
+                "id": "msg_2",
+                "role": "assistant",
+                "content": [{"type": "refusal", "refusal": refusal}],
+            }],
+        }
+        resp_obj = MagicMock(status="completed", usage=None, output=[])
+        resp_obj.model_dump.return_value = terminal_response
+        events = [
+            MagicMock(
+                type="response.refusal.delta",
+                item_id="msg_1",
+                content_index=0,
+                delta="First",
+            ),
+            MagicMock(
+                type="response.refusal.delta",
+                item_id="msg_1",
+                content_index=1,
+                delta=" and second",
+            ),
+            MagicMock(
+                type="response.refusal.done",
+                item_id="msg_1",
+                content_index=0,
+                refusal="First",
+            ),
+            MagicMock(
+                type="response.refusal.done",
+                item_id="msg_1",
+                content_index=1,
+                refusal=" and second sentence.",
+            ),
+            MagicMock(
+                type="response.refusal.done",
+                item_id="msg_2",
+                content_index=0,
+                refusal=" Done-only.",
+            ),
+            MagicMock(
+                type="response.refusal.delta",
+                item_id="msg_2",
+                content_index=1,
+                delta=" Terminal",
+            ),
+            MagicMock(type="response.completed", response=resp_obj),
+        ]
+        capture = ResponsesStreamCapture()
+        deltas: list[str] = []
+
+        async def on_content(delta: str) -> None:
+            deltas.append(delta)
+
+        async def stream():
+            for event in events:
+                yield event
+
+        content, _, finish_reason, _, _ = await consume_sdk_stream(
+            stream(),
+            on_content_delta=on_content,
+            capture=capture,
+        )
+
+        assert content == refusal
+        assert deltas == [
+            "First",
+            " and second",
+            " sentence.",
+            " Done-only.",
+            " Terminal",
+            " suffix.",
+        ]
+        assert finish_reason == "refusal"
+        assert capture.completed is True
+        assert is_replayable_finish_reason(finish_reason) is False
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("source", ["events", "terminal"])
+    async def test_refusal_without_deltas_has_non_replayable_finish(self, source: str):
+        refusal = "I can’t help with that request."
+        terminal_response = {
+            "status": "completed",
+            "output": [{
+                "type": "message",
+                "id": "msg_1",
+                "role": "assistant",
+                "content": [{"type": "refusal", "refusal": refusal}],
+            }],
+        }
+        resp_obj = MagicMock(status="completed", usage=None, output=[])
+        resp_obj.model_dump.return_value = terminal_response
+        capture = ResponsesStreamCapture()
+        deltas: list[str] = []
+
+        async def on_content(delta: str) -> None:
+            deltas.append(delta)
+
+        async def stream():
+            if source == "events":
+                yield MagicMock(type="response.refusal.done", refusal=refusal)
+                yield MagicMock(
+                    type="response.completed",
+                    response={"status": "completed"},
+                )
+            else:
+                yield MagicMock(type="response.completed", response=resp_obj)
+
+        content, _, finish_reason, _, _ = await consume_sdk_stream(
+            stream(),
+            on_content_delta=on_content,
+            capture=capture,
+        )
+
+        assert content == refusal
+        assert deltas == [refusal]
+        assert finish_reason == "refusal"
+        assert capture.completed is True
+        assert is_replayable_finish_reason(finish_reason) is False
+
     @pytest.mark.asyncio
     async def test_on_content_delta_called(self):
         ev1 = MagicMock(type="response.output_text.delta", delta="hi")
@@ -919,6 +1562,64 @@ class TestConsumeSdkStream:
         _, _, _, usage, _ = await consume_sdk_stream(stream())
         assert usage == {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        ("reason", "expected_finish_reason"),
+        [
+            ("max_output_tokens", "length"),
+            ("content_filter", "content_filter"),
+        ],
+    )
+    async def test_incomplete_event_commits_capture_usage(
+        self,
+        reason,
+        expected_finish_reason,
+    ):
+        output = [
+            {
+                "type": "message",
+                "id": "msg_1",
+                "status": "incomplete",
+                "content": [{"type": "output_text", "text": "partial"}],
+            },
+        ]
+        usage_obj = MagicMock(input_tokens=10, output_tokens=5, total_tokens=15)
+        output_item = MagicMock(type="message")
+        terminal_response = {
+            "id": "resp_1",
+            "status": "incomplete",
+            "incomplete_details": {"reason": reason},
+            "output": output,
+            "usage": {"input_tokens": 10, "output_tokens": 5, "total_tokens": 15},
+        }
+        resp_obj = MagicMock(
+            status="incomplete",
+            usage=usage_obj,
+            output=[output_item],
+        )
+        resp_obj.model_dump.return_value = terminal_response
+        events = [
+            MagicMock(type="response.output_text.delta", delta="partial"),
+            MagicMock(type="response.incomplete", response=resp_obj),
+        ]
+        capture = ResponsesStreamCapture()
+
+        async def stream():
+            for event in events:
+                yield event
+
+        content, _, finish_reason, usage, _ = await consume_sdk_stream(
+            stream(),
+            capture=capture,
+        )
+
+        assert content == "partial"
+        assert finish_reason == expected_finish_reason
+        assert usage == {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}
+        assert capture.completed is True
+        assert capture.response == terminal_response
+        assert capture.output_items == output
+
     @pytest.mark.asyncio
     async def test_reasoning_extracted(self):
         summary_item = MagicMock(type="summary_text", text="thinking...")

tests/providers/test_provider_retry.py

@@ -3,7 +3,14 @@ import copy
 
 import pytest
 
-from nanobot.providers.base import RETRY_AFTER_BUFFER, GenerationSettings, LLMProvider, LLMResponse
+from nanobot.providers.base import (
+    RETRY_AFTER_BUFFER,
+    GenerationSettings,
+    LLMProvider,
+    LLMResponse,
+    ProviderCallContext,
+    ProviderConversationState,
+)
 
 
 class ScriptedProvider(LLMProvider):
@@ -330,6 +337,79 @@ async def test_successful_image_retry_mutates_original_messages_in_place() -> No
     assert any("not delivered" in (block.get("text") or "").lower() for block in content)
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("messages", "payload", "pending_messages"),
+    [
+        (_IMAGE_MSG, {}, _IMAGE_MSG),
+        (
+            [{"role": "user", "content": "continue"}],
+            {
+                "items": [
+                    {
+                        "type": "message",
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "input_image",
+                                "image_url": "data:image/png;base64,abc",
+                            }
+                        ],
+                    }
+                ]
+            },
+            [],
+        ),
+    ],
+    ids=["pending-image", "opaque-payload-image"],
+)
+async def test_image_retry_discards_provider_state_with_images(
+    messages,
+    payload,
+    pending_messages,
+) -> None:
+    class ContextScriptedProvider(ScriptedProvider):
+        def __init__(self, responses):
+            super().__init__(responses)
+            self.contexts: list[ProviderCallContext] = []
+
+        async def chat_with_context(
+            self,
+            *,
+            provider_context: ProviderCallContext,
+            **kwargs,
+        ) -> LLMResponse:
+            self.contexts.append(provider_context)
+            return await self.chat(**kwargs)
+
+    provider = ContextScriptedProvider([
+        LLMResponse(content="model does not support images", finish_reason="error"),
+        LLMResponse(content="ok, no image"),
+    ])
+    messages = copy.deepcopy(messages)
+    state = ProviderConversationState(
+        kind="openai_responses",
+        provider="openai:test",
+        model="gpt-5.6",
+        version=1,
+        payload=copy.deepcopy(payload),
+        pending_messages=copy.deepcopy(pending_messages),
+    )
+
+    response = await provider.chat_with_retry(
+        messages=messages,
+        provider_context=ProviderCallContext(conversation_state=state),
+    )
+
+    assert response.content == "ok, no image"
+    retry_context = provider.contexts[-1]
+    assert isinstance(retry_context, ProviderCallContext)
+    assert retry_context.conversation_state is None
+    public_content = messages[0]["content"]
+    if isinstance(public_content, list):
+        assert all(block.get("type") != "image_url" for block in public_content)
+
+
 @pytest.mark.asyncio
 async def test_non_transient_error_without_images_no_retry() -> None:
     """Non-transient errors without image content are returned immediately."""

tests/providers/test_responses_circuit_breaker.py

@@ -4,6 +4,7 @@ import time
 
 import pytest
 
+from nanobot.providers.base import ProviderCallContext
 from nanobot.providers.openai_compat_provider import (
     _RESPONSES_FAILURE_THRESHOLD,
     _RESPONSES_PROBE_INTERVAL_S,
@@ -28,6 +29,26 @@ def test_responses_api_available_by_default(provider):
     assert provider._should_use_responses_api("gpt-5", None) is True
 
 
+def test_direct_openai_enables_server_compaction(provider):
+    provider._extra_body = {}
+
+    body = provider._build_responses_body(
+        messages=[{"role": "user", "content": "hello"}],
+        tools=None,
+        model="gpt-5.6",
+        max_tokens=30_000,
+        temperature=0.1,
+        reasoning_effort="high",
+        tool_choice=None,
+        provider_context=ProviderCallContext(context_window_tokens=100_000),
+    )
+
+    assert body["context_management"] == [{
+        "type": "compaction",
+        "compact_threshold": 70_000,
+    }]
+
+
 def test_api_type_chat_completions_disables_responses(provider):
     provider._api_type = "chat_completions"
     assert provider._should_use_responses_api("gpt-5", None) is False

tests/security/test_resource_view_access.py

@@ -1,104 +0,0 @@
-from pathlib import Path
-
-import pytest
-
-from nanobot.resource_links import ensure_resource_view
-from nanobot.security.workspace_policy import WorkspaceBoundaryError, resolve_allowed_path
-
-
-@pytest.fixture
-def resource_targets(tmp_path: Path) -> tuple[Path, Path, Path, Path]:
-    data_dir = tmp_path / "data"
-    workspace = tmp_path / "agent"
-    package = tmp_path / "package" / "nanobot"
-    project = tmp_path / "project"
-    (workspace / "skills" / "custom").mkdir(parents=True)
-    (workspace / "memory").mkdir()
-    (package / "skills" / "builtin").mkdir(parents=True)
-    (package / "templates").mkdir()
-    project.mkdir()
-    (workspace / "skills" / "custom" / "SKILL.md").write_text("custom", encoding="utf-8")
-    (workspace / "memory" / "history.jsonl").write_text("{}\n", encoding="utf-8")
-    (package / "skills" / "builtin" / "SKILL.md").write_text("builtin", encoding="utf-8")
-    (package / "templates" / "identity.md").write_text("identity", encoding="utf-8")
-    return data_dir, workspace, package, project
-
-
-def _view_for(targets: tuple[Path, Path, Path, Path]):
-    data_dir, workspace, package, _ = targets
-    view = ensure_resource_view(
-        data_dir=data_dir,
-        config_path=data_dir / "config.json",
-        agent_workspace=workspace,
-        package_root=package,
-    )
-    if view.agent is None or view.media is None or view.package is None:
-        pytest.skip(f"directory links unavailable: {view.warnings}")
-    return view
-
-
-def test_restricted_access_follows_resource_alias_targets(
-    resource_targets: tuple[Path, Path, Path, Path],
-) -> None:
-    _, workspace, package, project = resource_targets
-    view = _view_for(resource_targets)
-
-    custom_skill = resolve_allowed_path(
-        view.agent / "skills" / "custom" / "SKILL.md",
-        workspace=project,
-        allowed_root=project,
-        extra_allowed_roots=[workspace / "skills", package / "skills"],
-        strict=True,
-    )
-    builtin_skill = resolve_allowed_path(
-        view.package / "skills" / "builtin" / "SKILL.md",
-        workspace=project,
-        allowed_root=project,
-        extra_allowed_roots=[workspace / "skills", package / "skills"],
-        strict=True,
-    )
-    media_root = resolve_allowed_path(
-        view.media,
-        workspace=project,
-        allowed_root=project,
-        extra_allowed_roots=[resource_targets[0] / "media"],
-        strict=True,
-    )
-
-    assert custom_skill == (workspace / "skills" / "custom" / "SKILL.md").resolve()
-    assert builtin_skill == (package / "skills" / "builtin" / "SKILL.md").resolve()
-    assert media_root == (resource_targets[0] / "media").resolve()
-
-
-def test_alias_does_not_expand_restricted_package_or_agent_access(
-    resource_targets: tuple[Path, Path, Path, Path],
-) -> None:
-    _, workspace, _, project = resource_targets
-    view = _view_for(resource_targets)
-
-    with pytest.raises(WorkspaceBoundaryError):
-        resolve_allowed_path(
-            view.package / "templates" / "identity.md",
-            workspace=project,
-            allowed_root=project,
-            extra_allowed_roots=[workspace / "skills"],
-            strict=True,
-        )
-
-    history = workspace / "memory" / "history.jsonl"
-    with pytest.raises(WorkspaceBoundaryError):
-        resolve_allowed_path(
-            view.agent / "memory" / "history.jsonl",
-            workspace=project,
-            allowed_root=project,
-            extra_allowed_files=[history],
-            strict=True,
-        )
-
-    assert resolve_allowed_path(
-        history,
-        workspace=project,
-        allowed_root=project,
-        extra_allowed_files=[history],
-        strict=True,
-    ) == history.resolve()

tests/session/test_session_store.py

@@ -0,0 +1,79 @@
+from unittest.mock import MagicMock
+
+import nanobot.session as session_api
+from nanobot.session import Session, SessionManager
+from nanobot.session.manager import FILE_MAX_MESSAGES, SessionStore
+
+
+def test_store_types_are_not_public_session_api() -> None:
+    assert not hasattr(session_api, "SessionStore")
+    assert not hasattr(session_api, "JsonlSessionStore")
+
+
+def test_manager_delegates_persistence_to_store(tmp_path) -> None:
+    stored = Session(key="cli:test")
+    stored.add_message("user", "hello")
+    payload = {
+        "key": stored.key,
+        "created_at": stored.created_at.isoformat(),
+        "updated_at": stored.updated_at.isoformat(),
+        "metadata": {},
+        "messages": stored.messages,
+    }
+    metadata = {
+        "key": stored.key,
+        "created_at": stored.created_at.isoformat(),
+        "updated_at": stored.updated_at.isoformat(),
+        "metadata": {},
+    }
+    listing = [
+        {
+            "key": stored.key,
+            "created_at": stored.created_at.isoformat(),
+            "updated_at": stored.updated_at.isoformat(),
+            "title": "",
+            "preview": "hello",
+            "path": "session.db",
+        }
+    ]
+    store = MagicMock(spec=SessionStore)
+    store.load.return_value = stored
+    store.read.return_value = payload
+    store.read_metadata.return_value = metadata
+    store.list_sessions.return_value = listing
+    store.delete.return_value = True
+    manager = SessionManager(tmp_path, store=store)
+
+    assert manager.get_or_create(stored.key) is stored
+    assert manager.get_or_create(stored.key) is stored
+    store.load.assert_called_once_with(stored.key)
+
+    manager.save(stored, fsync=True)
+    store.save.assert_called_once_with(stored, fsync=True)
+    assert manager.read_session_file(stored.key) == payload
+    assert manager.read_session_metadata(stored.key) == metadata
+    assert manager.list_sessions() == listing
+
+    assert manager.delete_session(stored.key) is True
+    store.delete.assert_called_once_with(stored.key)
+    assert manager.get_cached(stored.key) is None
+
+
+def test_manager_applies_file_cap_before_store_save(tmp_path) -> None:
+    store = MagicMock(spec=SessionStore)
+    archiver = MagicMock()
+    manager = SessionManager(tmp_path, store=store)
+    manager.set_file_cap_archiver(archiver)
+    session = Session(
+        key="cli:large",
+        messages=[
+            {"role": "user", "content": str(index)}
+            for index in range(FILE_MAX_MESSAGES + 1)
+        ],
+    )
+
+    manager.save(session)
+
+    assert len(session.messages) == FILE_MAX_MESSAGES
+    archiver.assert_called_once()
+    store.save.assert_called_once_with(session, fsync=False)

tests/test_nanobot_facade.py

@@ -10,7 +10,6 @@ from unittest.mock import ANY, AsyncMock, MagicMock, patch
 
 import pytest
 
-from nanobot.config.schema import Config
 from nanobot.nanobot import (
     STREAM_EVENT_REASONING_COMPLETED,
     STREAM_EVENT_REASONING_DELTA,
@@ -31,7 +30,6 @@ from nanobot.nanobot import (
     StreamEvent,
     StreamEventType,
 )
-from nanobot.nanobot import _prepare_resource_view as prepare_resource_view
 from nanobot.runtime_context import (
     RUNTIME_CONTEXT_HISTORY_META,
     RuntimeContextBlock,
@@ -41,15 +39,6 @@ from nanobot.session.manager import FILE_MAX_MESSAGES
 from nanobot.utils.llm_runtime import runtime_from_provider_snapshot
 
 
-@pytest.fixture(autouse=True)
-def _disable_sdk_resource_view_creation(monkeypatch) -> None:
-    """Keep facade tests from creating runtime links unless a test opts in."""
-    monkeypatch.setattr(
-        "nanobot.nanobot._prepare_resource_view",
-        lambda _config, _config_path: None,
-    )
-
-
 def _write_config(tmp_path: Path, overrides: dict | None = None) -> Path:
     data = {
         "providers": {"openrouter": {"apiKey": "sk-test-key"}},
@@ -169,72 +158,6 @@ def test_from_config_default_path():
         mock_load.assert_called_once_with(None)
 
 
-def test_from_config_scopes_resource_view_to_custom_config_without_global_mutation(
-    monkeypatch,
-    tmp_path: Path,
-) -> None:
-    from nanobot.config import loader
-
-    instance_dir = tmp_path / "instance"
-    instance_dir.mkdir()
-    config_path = _write_config(instance_dir)
-    workspace = tmp_path / "workspace"
-    unrelated_config = tmp_path / "other" / "config.json"
-    monkeypatch.setattr(loader, "_current_config_path", unrelated_config)
-    resource_view = object()
-
-    with patch(
-        "nanobot.nanobot._prepare_resource_view",
-        return_value=resource_view,
-    ) as mock_prepare, patch("nanobot.nanobot.AgentLoop.from_config") as mock_loop:
-        bot = Nanobot.from_config(config_path, workspace=workspace)
-
-    prepared_config, prepared_path = mock_prepare.call_args.args
-    assert prepared_path == config_path.resolve()
-    assert prepared_config.workspace_path == workspace.resolve()
-    assert mock_loop.call_args.kwargs["resource_view"] is resource_view
-    assert loader.get_config_path() == unrelated_config
-    assert bot._loop is mock_loop.return_value
-
-
-def test_sdk_resource_view_failure_is_non_fatal(
-    monkeypatch,
-    tmp_path: Path,
-) -> None:
-    from nanobot import resource_links
-
-    config = Config()
-    config.agents.defaults.workspace = str(tmp_path / "workspace")
-
-    def _fail(**_kwargs):
-        raise PermissionError("read-only")
-
-    monkeypatch.setattr(resource_links, "ensure_resource_view", _fail)
-
-    assert prepare_resource_view(config, tmp_path / "config.json") is None
-
-
-def test_sdk_resource_view_prepares_fresh_workspace_before_linking(
-    monkeypatch,
-    tmp_path: Path,
-) -> None:
-    from nanobot import resource_links
-
-    config = Config()
-    workspace = tmp_path / "fresh-workspace"
-    config.agents.defaults.workspace = str(workspace)
-    expected = SimpleNamespace(warnings=())
-
-    def _capture(**kwargs):
-        assert workspace.is_dir()
-        assert kwargs["agent_workspace"] == workspace
-        return expected
-
-    monkeypatch.setattr(resource_links, "ensure_resource_view", _capture)
-
-    assert prepare_resource_view(config, tmp_path / "config.json") is expected
-
-
 @pytest.mark.asyncio
 async def test_run_returns_result(tmp_path):
     config_path = _write_config(tmp_path)

tests/test_resource_links.py

@@ -1,332 +0,0 @@
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-from pathlib import Path
-
-import pytest
-from filelock import Timeout
-
-from nanobot import resource_links
-from nanobot.resource_links import ResourceView, ensure_resource_view
-
-
-def _targets(tmp_path: Path) -> tuple[Path, Path, Path, Path]:
-    data_dir = tmp_path / "state"
-    config_path = data_dir / "config.json"
-    agent_workspace = tmp_path / "agent"
-    package_root = tmp_path / "package"
-    agent_workspace.mkdir()
-    package_root.mkdir()
-    return data_dir, config_path, agent_workspace, package_root
-
-
-def _ensure(
-    data_dir: Path,
-    config_path: Path,
-    agent_workspace: Path,
-    package_root: Path,
-) -> ResourceView:
-    return ensure_resource_view(
-        data_dir=data_dir,
-        config_path=config_path,
-        agent_workspace=agent_workspace,
-        package_root=package_root,
-    )
-
-
-def _remove_directory_link(path: Path) -> None:
-    try:
-        path.unlink()
-    except OSError:
-        os.rmdir(path)
-
-
-def test_ensure_resource_view_is_stable_and_idempotent(tmp_path: Path) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-
-    first = _ensure(data_dir, config_path, agent_workspace, package_root)
-    second = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert first == second
-    assert first.warnings == ()
-    assert first.root is not None
-    assert len(first.root.name) == 16
-    assert first.agent is not None
-    assert first.agent.resolve(strict=True) == agent_workspace.resolve(strict=True)
-    assert first.media is not None
-    assert first.media.resolve(strict=True) == (data_dir / "media").resolve(strict=True)
-    assert first.package is not None
-    assert first.package.resolve(strict=True) == package_root.resolve(strict=True)
-
-
-def test_resource_view_id_isolated_by_config_workspace_and_package(tmp_path: Path) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    other_workspace = tmp_path / "other-agent"
-    other_package = tmp_path / "other-package"
-    other_workspace.mkdir()
-    other_package.mkdir()
-
-    baseline = _ensure(data_dir, config_path, agent_workspace, package_root)
-    config_variant = _ensure(
-        data_dir,
-        data_dir / "other-config.json",
-        agent_workspace,
-        package_root,
-    )
-    workspace_variant = _ensure(data_dir, config_path, other_workspace, package_root)
-    package_variant = _ensure(data_dir, config_path, agent_workspace, other_package)
-
-    roots = {
-        baseline.root,
-        config_variant.root,
-        workspace_variant.root,
-        package_variant.root,
-    }
-    assert None not in roots
-    assert len(roots) == 4
-
-
-def test_partial_link_failure_only_degrades_that_alias(
-    monkeypatch,
-    tmp_path: Path,
-) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    real_create = resource_links._create_directory_link
-
-    def fail_media(alias: Path, target: Path) -> None:
-        if alias.name == "media":
-            raise PermissionError("media denied")
-        real_create(alias, target)
-
-    monkeypatch.setattr(resource_links, "_create_directory_link", fail_media)
-
-    view = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert view.root is not None
-    assert view.agent is not None
-    assert view.media is None
-    assert view.package is not None
-    assert any("media denied" in warning for warning in view.warnings)
-
-
-def test_existing_alias_collision_is_never_replaced(tmp_path: Path) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    first = _ensure(data_dir, config_path, agent_workspace, package_root)
-    assert first.agent is not None
-    _remove_directory_link(first.agent)
-    first.agent.write_text("user-owned", encoding="utf-8")
-
-    second = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert second.root == first.root
-    assert second.agent is None
-    assert second.media is not None
-    assert second.package is not None
-    assert first.agent.read_text(encoding="utf-8") == "user-owned"
-    assert any("alias collision for agent" in warning for warning in second.warnings)
-
-
-def test_wrong_link_is_never_repointed(tmp_path: Path) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    wrong_target = tmp_path / "wrong-agent"
-    wrong_target.mkdir()
-    first = _ensure(data_dir, config_path, agent_workspace, package_root)
-    assert first.agent is not None
-    _remove_directory_link(first.agent)
-    resource_links._create_directory_link(first.agent, wrong_target)
-
-    second = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert second.agent is None
-    assert first.agent.resolve(strict=True) == wrong_target.resolve(strict=True)
-    assert any("alias collision for agent" in warning for warning in second.warnings)
-
-
-def test_unmanaged_namespace_collision_is_not_modified(tmp_path: Path) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    namespace = data_dir / "resources"
-    namespace.mkdir(parents=True)
-    user_file = namespace / "notes.txt"
-    user_file.write_text("keep me", encoding="utf-8")
-
-    view = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert view.root is None
-    assert view.agent is None
-    assert user_file.read_text(encoding="utf-8") == "keep me"
-    assert list(namespace.iterdir()) == [user_file]
-    assert any("ownership marker missing" in warning for warning in view.warnings)
-
-
-def test_mismatched_view_marker_is_not_repaired(tmp_path: Path) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    first = _ensure(data_dir, config_path, agent_workspace, package_root)
-    assert first.root is not None
-    marker = first.root / ".nanobot-resource-view.json"
-    payload = json.loads(marker.read_text(encoding="utf-8"))
-    payload["targets"]["agent"] = str(tmp_path / "someone-else")
-    marker.write_text(json.dumps(payload), encoding="utf-8")
-
-    second = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert second.root is None
-    assert second.agent is None
-    assert any("marker does not match" in warning for warning in second.warnings)
-
-
-def test_invalid_marker_encoding_degrades_without_raising(tmp_path: Path) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    first = _ensure(data_dir, config_path, agent_workspace, package_root)
-    assert first.root is not None
-    marker = first.root / ".nanobot-resource-view.json"
-    marker.write_bytes(b"\xff")
-
-    second = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert second.root is None
-    assert any("Could not read resource view marker" in warning for warning in second.warnings)
-
-
-def test_failed_marker_write_removes_only_new_empty_view_directory(
-    monkeypatch,
-    tmp_path: Path,
-) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    real_write_marker = resource_links._write_marker
-
-    def fail_view_marker(marker_path: Path, payload: dict) -> None:
-        if marker_path.name == resource_links._VIEW_MARKER:
-            raise PermissionError("view marker denied")
-        real_write_marker(marker_path, payload)
-
-    monkeypatch.setattr(resource_links, "_write_marker", fail_view_marker)
-
-    view = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    namespace = data_dir / "resources"
-    assert view.root is None
-    assert namespace.is_dir()
-    assert [entry.name for entry in namespace.iterdir()] == [
-        resource_links._NAMESPACE_MARKER
-    ]
-    assert any("view marker denied" in warning for warning in view.warnings)
-
-
-def test_view_inside_agent_target_is_fully_disabled_to_avoid_recursive_walk(
-    tmp_path: Path,
-) -> None:
-    agent_workspace = tmp_path / "agent"
-    data_dir = agent_workspace / ".nanobot"
-    config_path = data_dir / "config.json"
-    package_root = tmp_path / "package"
-    agent_workspace.mkdir()
-    package_root.mkdir()
-
-    view = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert view.root is None
-    assert view.agent is None
-    assert view.media is None
-    assert view.package is None
-    assert not (data_dir / "resources").exists()
-    assert any("recursive traversal unsafe" in warning for warning in view.warnings)
-
-
-def test_unverified_new_link_is_removed_without_touching_target(
-    monkeypatch,
-    tmp_path: Path,
-) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    real_points_to = resource_links._link_points_to
-
-    def fail_agent_verification(alias: Path, target: Path) -> bool:
-        if alias.name == "agent":
-            return False
-        return real_points_to(alias, target)
-
-    monkeypatch.setattr(resource_links, "_link_points_to", fail_agent_verification)
-
-    view = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert view.root is not None
-    assert view.agent is None
-    assert not os.path.lexists(view.root / "agent")
-    assert agent_workspace.is_dir()
-    assert view.media is not None
-    assert view.package is not None
-    assert any("could not be verified" in warning for warning in view.warnings)
-
-
-def test_lock_timeout_is_nonfatal_and_finite(monkeypatch, tmp_path: Path) -> None:
-    data_dir, config_path, agent_workspace, package_root = _targets(tmp_path)
-    observed_timeouts: list[float] = []
-
-    def fail_lock(lock_path: str, *, timeout: float):
-        observed_timeouts.append(timeout)
-        raise Timeout(lock_path)
-
-    monkeypatch.setattr(resource_links, "FileLock", fail_lock)
-
-    view = _ensure(data_dir, config_path, agent_workspace, package_root)
-
-    assert observed_timeouts == [resource_links._LOCK_TIMEOUT_SECONDS]
-    assert view == ResourceView(
-        warnings=(
-            f"Timed out waiting for resource view lock: "
-            f"{data_dir.resolve() / '.nanobot-resource-links.lock'}",
-        )
-    )
-
-
-def test_windows_symlink_failure_falls_back_to_junction(monkeypatch, tmp_path: Path) -> None:
-    alias = tmp_path / "alias"
-    target = tmp_path / "target"
-    target.mkdir()
-    junction_calls: list[tuple[Path, Path]] = []
-
-    def fail_symlink(self: Path, target: Path, *, target_is_directory: bool = False) -> None:
-        assert target_is_directory is True
-        raise PermissionError("symlinks unavailable")
-
-    def record_junction(link: Path, junction_target: Path) -> None:
-        junction_calls.append((link, junction_target))
-
-    monkeypatch.setattr(Path, "symlink_to", fail_symlink)
-    monkeypatch.setattr(resource_links, "_is_windows", lambda: True)
-    monkeypatch.setattr(resource_links, "_create_windows_junction", record_junction)
-
-    resource_links._create_directory_link(alias, target)
-
-    assert junction_calls == [(alias, target)]
-
-
-def test_windows_junction_command_timeout_is_bounded(monkeypatch, tmp_path: Path) -> None:
-    observed_timeouts: list[float] = []
-
-    def time_out(command: str, **kwargs):
-        observed_timeouts.append(kwargs["timeout"])
-        raise subprocess.TimeoutExpired(command, kwargs["timeout"])
-
-    monkeypatch.setattr(resource_links.subprocess, "run", time_out)
-
-    with pytest.raises(OSError, match="Timed out creating Windows junction"):
-        resource_links._create_windows_junction(tmp_path / "alias", tmp_path / "target")
-
-    assert observed_timeouts == [resource_links._JUNCTION_TIMEOUT_SECONDS]
-
-
-def test_default_package_root_points_to_installed_nanobot_package(tmp_path: Path) -> None:
-    data_dir = tmp_path / "state"
-    agent_workspace = tmp_path / "agent"
-    agent_workspace.mkdir()
-
-    view = ensure_resource_view(
-        data_dir=data_dir,
-        config_path=data_dir / "config.json",
-        agent_workspace=agent_workspace,
-    )
-
-    assert view.package is not None
-    assert view.package.resolve(strict=True) == Path(resource_links.__file__).parent.resolve(strict=True)

tests/tools/test_exec_session_tools.py

@@ -19,6 +19,8 @@ from nanobot.agent.tools.exec_session import (
     ExecSessionManager,
     ListExecSessionsTool,
     WriteStdinTool,
+    _BoundedOutputBuffer,
+    _SessionPoll,
 )
 from nanobot.agent.tools.registry import is_tool_error_result
 from nanobot.agent.tools.shell import ExecTool
@@ -143,6 +145,88 @@ def test_exec_session_accepts_max_output_tokens_alias(tmp_path):
     assert "Exit code: 0" in result
 
 
+def test_bounded_output_buffer_keeps_head_tail_and_exact_drop_count():
+    buffer = _BoundedOutputBuffer(10)
+
+    buffer.append("012345")
+    buffer.append("6789ABCDEF")
+
+    assert buffer.retained_chars == 10
+    assert buffer.drain() == ("01234BCDEF", 6)
+    assert buffer.retained_chars == 0
+
+
+def test_exec_session_bounds_unpolled_stdout_and_stderr(tmp_path):
+    async def run() -> tuple[int, int, str, int]:
+        manager = ExecSessionManager()
+        tool = ExecTool(working_dir=str(tmp_path), timeout=5, session_manager=manager)
+        command = _python_command(
+            "import sys,time; time.sleep(0.05); "
+            "sys.stdout.write('OUT_HEAD' + 'o' * 200000 + 'OUT_TAIL'); "
+            "sys.stderr.write('ERR_HEAD' + 'e' * 200000 + 'ERR_TAIL')"
+        )
+
+        initial = await tool.execute(
+            command=command,
+            yield_time_ms=0,
+            max_output_chars=1000,
+        )
+        sid = _session_id(initial)
+        session = manager._sessions[sid]
+        await asyncio.wait_for(session.process.wait(), timeout=5)
+        await asyncio.wait_for(
+            asyncio.gather(session._stdout_task, session._stderr_task),
+            timeout=5,
+        )
+        retained_stdout = session._stdout.retained_chars
+        retained_stderr = session._stderr.retained_chars
+        poll = await manager.write(
+            session_id=sid,
+            chars=None,
+            close_stdin=False,
+            terminate=False,
+            yield_time_ms=0,
+            max_output_chars=1000,
+        )
+        return retained_stdout, retained_stderr, poll.output, poll.truncated_chars
+
+    retained_stdout, retained_stderr, output, truncated_chars = asyncio.run(run())
+
+    assert retained_stdout == 50000
+    assert retained_stderr == 50000
+    assert output.startswith("OUT_HEAD")
+    assert output.endswith("ERR_TAIL")
+    assert truncated_chars > 390000
+
+
+def test_write_stdin_wait_for_keeps_aggregate_within_output_budget():
+    async def run() -> str:
+        manager = SimpleNamespace(
+            write=AsyncMock(side_effect=[
+                _SessionPoll(output="HEAD" + "a" * 596, done=False, exit_code=None),
+                _SessionPoll(output="b" * 600, done=False, exit_code=None),
+                _SessionPoll(output="c" * 590 + "TARGET", done=False, exit_code=None),
+            ])
+        )
+        tool = WriteStdinTool(manager=manager)
+        return await tool._wait_for_output(
+            session_id="session",
+            chars=None,
+            close_stdin=False,
+            terminate=False,
+            wait_for="TARGET",
+            wait_timeout_ms=1000,
+            max_output_chars=1000,
+        )
+
+    result = asyncio.run(run())
+
+    assert result.startswith("HEAD")
+    assert "TARGET" in result
+    assert "(796 chars truncated from output)" in result
+    assert len(result) < 1100
+
+
 def test_exec_one_shot_accepts_max_output_tokens_alias(tmp_path):
     async def run() -> str:
         tool = ExecTool(working_dir=str(tmp_path), timeout=5)