From 0e5d6ac36f0c44afe0461953a216254e7342bccd Mon Sep 17 00:00:00 2001
From: Texas-walker15 <noahwalker715@gmail.com>
Date: Thu, 3 Sep 2026 10:42:17 +0200
Subject: [PATCH 1/2] feat: add phase 2 chat foundation

---
 README.md                                     |  64 ++--
 docs/phase-2-chat-architecture.md             | 156 +++++++++
 src/main/secrets.ts                           |  29 +-
 src/renderer/App.tsx                          |  21 +-
 src/renderer/chat/Chat.tsx                    | 128 ++++++++
 src/renderer/chat/conversation-controller.ts  | 220 +++++++++++++
 src/renderer/chat/useConversation.ts          |  51 +++
 src/renderer/styles.css                       | 130 ++++++++
 src/shared/chat/index.ts                      |  19 ++
 src/shared/chat/mock-provider.ts              | 140 ++++++++
 src/shared/chat/provider.ts                   |  84 +++++
 src/shared/constants.ts                       |  69 ++++
 src/shared/schemas/chat.schema.ts             |  85 +++++
 src/shared/schemas/index.ts                   |   3 +
 tests/unit/main/secrets.test.ts               |  10 +
 .../renderer/conversation-controller.test.ts  | 310 ++++++++++++++++++
 tests/unit/shared/chat.schema.test.ts         | 176 ++++++++++
 tests/unit/shared/mock-provider.test.ts       | 151 +++++++++
 18 files changed, 1805 insertions(+), 41 deletions(-)
 create mode 100644 docs/phase-2-chat-architecture.md
 create mode 100644 src/renderer/chat/Chat.tsx
 create mode 100644 src/renderer/chat/conversation-controller.ts
 create mode 100644 src/renderer/chat/useConversation.ts
 create mode 100644 src/shared/chat/index.ts
 create mode 100644 src/shared/chat/mock-provider.ts
 create mode 100644 src/shared/chat/provider.ts
 create mode 100644 src/shared/schemas/chat.schema.ts
 create mode 100644 tests/unit/renderer/conversation-controller.test.ts
 create mode 100644 tests/unit/shared/chat.schema.test.ts
 create mode 100644 tests/unit/shared/mock-provider.test.ts

diff --git a/README.md b/README.md
index e790498..c02dc60 100644
--- a/README.md
+++ b/README.md
@@ -3,27 +3,25 @@
 A local-first, permission-controlled desktop assistant for Windows. The
 assistant is named **JARVIS** by default; the product is **Local Agent**.
 
-> **Status: Phase 1, Milestone 8 (final Phase 1 milestone).**
-> The repository contains project scaffolding, shared schemas, a hardened
-> Electron desktop shell, non-secret settings storage, an audit-log
-> foundation, the permission-policy runtime, persisted emergency-stop state,
-> the first-run onboarding interface, a provider-settings foundation, and an
-> encrypted secret store for API keys. The application registers its first
-> real, privileged IPC channels (settings and secrets), each gated by the
-> same permission engine, executor and audit log every action type uses, and
-> confirmed through a real native dialog for the sensitive ones. Milestone 8
-> adds a GitHub Actions CI workflow that runs the full verification pipeline
-> — type-check, lint, format check, unit tests, build, the Playwright/Electron
-> end-to-end smoke suite and `npm audit` — on `windows-latest`, and closes a
-> handful of documentation inaccuracies found during a full review (a stale
-> "asynchronous safeStorage" claim in `.env.example` and the ADR, and a stale
-> "audit log not yet called from the running application" claim that Milestone
-> 7 had already made untrue). There is still no model integration: no
-> provider is ever called, and no key is ever validated over the network.
-> Nothing in this repository makes a network request or performs an action on
-> your machine beyond writing your own settings and encrypted key locally —
-> the renderer's Content-Security-Policy blocks outbound network access
-> outright, which the end-to-end test suite asserts.
+> **Status: Phase 1 complete. Phase 2, Milestone 1 (chat foundation) in progress.**
+> Phase 1 delivered the hardened desktop shell, non-secret settings storage,
+> an audit-log foundation, the permission-policy runtime, persisted
+> emergency-stop state, first-run onboarding, an encrypted secret store, and
+> CI. Phase 2 Milestone 1 adds a **mock-only chat foundation**: a validated
+> chat message and conversation model, a provider-independent
+> `ChatProvider` interface, a deterministic mock provider, and a chat surface
+> in the renderer with empty, loading, error and retry states. **No real
+> model provider is called. No network request is made anywhere in this
+> milestone** — the mock provider lives entirely inside `src/shared`, where
+> the same lint boundary that blocks Electron and Node access also blocks
+> `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource` as globals. Chat
+> requires **no new IPC channel**: it never calls `window.localAgent`, so
+> nothing a chat message contains can reach a privileged API, a file, or the
+> permission engine. See
+> [docs/phase-2-chat-architecture.md](docs/phase-2-chat-architecture.md) for
+> the full design and for what remains explicitly deferred (real providers,
+> tool/action execution from model output, memory, and everything else Phase
+> 2 has not reached yet).
 
 All rights reserved. No licence has been granted for this project.
 
@@ -91,9 +89,17 @@ postponed.
 - `hasApiKey`, the only secret-related value the interface ever sees, is
   reconciled against the encrypted store on every read and write — the store
   is the source of truth, never the cached flag.
+- Chat (Phase 2, Milestone 1) makes no network request and adds no IPC
+  channel. The mock provider lives under `src/shared/chat`, where the same
+  lint boundary that keeps `src/shared` free of Electron and Node access also
+  blocks `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource` as globals.
+  Assistant text is rendered as plain JSX text, never as HTML, and is never
+  treated as authorization for anything — there is no action for it to
+  authorize, since chat never calls `window.localAgent`.
 
 Full detail, including known limitations, is in
-[docs/security-model.md](docs/security-model.md).
+[docs/security-model.md](docs/security-model.md); the chat-specific design is
+in [docs/phase-2-chat-architecture.md](docs/phase-2-chat-architecture.md).
 
 ## Where your data lives
 
@@ -158,8 +164,11 @@ platform this project does not ship on.
 ## Repository layout
 
 ```
-src/shared/     Pure schemas, types and constants. No I/O, no Electron.
-                Safe to import from any process, including the renderer.
+src/shared/     Pure schemas, types and constants, plus chat/ (the
+                provider-independent ChatProvider interface and the
+                deterministic mock provider). No I/O, no Electron, no
+                network — safe to import from any process, including the
+                renderer.
 src/main/       Privileged Electron main process. Owns the BrowserWindow,
                 the Content-Security-Policy, navigation/window-open/webview
                 hardening, non-secret settings storage (paths.ts,
@@ -178,8 +187,11 @@ src/preload/    The single contextBridge. Exposes a narrow, explicitly
                 invoke-any-channel function. Bundled into one file: a
                 sandboxed preload cannot require() local modules at runtime.
 src/renderer/   React interface: App.tsx gates on onboardingCompleted,
-                Onboarding.tsx is the first-run form. No Node, no Electron,
-                no filesystem access — only the bridge at window.localAgent.
+                Onboarding.tsx is the first-run form, chat/ is the Phase 2
+                chat surface (Chat.tsx, useConversation.ts and the
+                framework-independent conversation-controller.ts). No Node,
+                no Electron, no filesystem access — only the bridge at
+                window.localAgent, which chat never calls.
 tests/unit/     Unit tests. `npm test`.
 tests/e2e/      Playwright + Electron smoke test against the built app.
                 `npm run test:e2e`.
diff --git a/docs/phase-2-chat-architecture.md b/docs/phase-2-chat-architecture.md
new file mode 100644
index 0000000..952ed13
--- /dev/null
+++ b/docs/phase-2-chat-architecture.md
@@ -0,0 +1,156 @@
+# Phase 2 chat architecture
+
+> **Current state.** Phase 2, Milestone 1 implements a **mock-only chat
+> foundation**. Every control below marked **[implemented]** is real and
+> tested; everything marked **[deferred]** does not exist yet and this
+> milestone does not lay groundwork that quietly enables it. Nothing here
+> makes a network request, and nothing here can trigger a privileged action.
+
+---
+
+## Summary
+
+| Property                                             | State                                                                                                            |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Chat message and conversation model                  | **[implemented]**                                                                                                |
+| Deterministic mock provider                          | **[implemented]**                                                                                                |
+| Real model provider (GLM, OpenAI-compatible, Ollama) | **[deferred]** — no network call exists anywhere in this codebase                                                |
+| API-key retrieval for a provider call                | **[deferred]** — chat never reads the secret store                                                               |
+| Tool calls / action execution from model output      | **[deferred]** — there is no tool type a model can invoke, and no execution path from chat to `main/executor.ts` |
+| Model output treated as authorization                | **Never.** There is no mechanism by which it could be — chat has no IPC channel at all                           |
+| Network request in this milestone                    | **None.** See [Security boundary](#security-boundary)                                                            |
+| New privileged IPC channel                           | **None added.** Chat is entirely renderer-local                                                                  |
+
+---
+
+## Message model
+
+`src/shared/schemas/chat.schema.ts` defines `chatMessageSchema`:
+
+| Field       | Type                                          | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`        | UUID string                                   | Generated by `crypto.randomUUID()` in the renderer's `ConversationController`, never by the schema itself — the schema only validates the shape.                                                                                                                                                                                                                                                                                                                                                  |
+| `role`      | `'system' \| 'user' \| 'assistant' \| 'tool'` | `tool` is declared for forward compatibility with a later milestone's tool-call support and is never produced by anything in this milestone — the mock provider never returns one, and nothing constructs one.                                                                                                                                                                                                                                                                                    |
+| `content`   | bounded string                                | 1–8,000 characters. Rejects unsafe control characters (NUL and other C0/C1 controls) while allowing tab, newline and carriage return, since chat content is legitimately multi-line — unlike the single-line `displayString` used for settings identity fields. Also rejects Unicode bidirectional override/isolate characters, the same "Trojan Source" defence `settings.schema.ts` already applies to display strings, extended here because assistant output is untrusted text a human reads. |
+| `createdAt` | UTC ISO-8601, no offset                       | Supplied by the caller, exactly like every other timestamp in this codebase (`src/shared` has no clock access — see `docs/architecture.md`'s "Timestamps and clocks" section).                                                                                                                                                                                                                                                                                                                    |
+| `status`    | optional `'complete' \| 'error'`              | Declared on the schema now, **unused by this milestone's actual logic** — see [Conversation state](#conversation-state) for why a failed attempt does not become an `'error'`-status message. Exists so a later milestone (for example, a streaming provider marking a message `'streaming'` while it fills in) is a new enum member, not a new field requiring a schema-version bump.                                                                                                            |
+| `metadata`  | optional bounded JSON object                  | Reuses `auditParametersSchema` — the exact schema audit records already use — rather than a second implementation. Depth, breadth, size and key length are all bounded, and any field whose name looks capable of carrying a credential (`apiKey`, `token`, `secret`, …) is rejected unless its value is already `[REDACTED]`, the same redaction contract the audit log enforces. **A message can never carry a secret in its metadata**, structurally, not by convention.                       |
+
+`chatMessageSchema` is `z.strictObject` — an unrecognised field is rejected outright, matching every other persisted or validated shape in this codebase. `createChatMessage(input)` validates and returns a message, or throws; nothing downstream ever sees an unvalidated message.
+
+**Nothing about a message is persisted to disk in this milestone.** Conversation state lives only in renderer memory for the lifetime of the window. `CHAT_CONVERSATION_MAX_MESSAGES` (200, in `src/shared/constants.ts`) bounds memory growth, not a file format.
+
+---
+
+## Provider interface
+
+`src/shared/chat/provider.ts` defines `ChatProvider`:
+
+```ts
+interface ChatProvider {
+  readonly id: string;
+  send(
+    request: { readonly messages: readonly ChatMessage[] },
+    options?: { readonly signal?: AbortSignal },
+  ): Promise<{ readonly content: string }>;
+}
+```
+
+Deliberately minimal and provider-independent:
+
+- **No Electron dependency, no filesystem or shell access.** The type itself cannot express either — there is nothing in the interface a provider could use to reach one.
+- **No network access is possible from an implementation placed under `src/shared`.** `eslint.config.js`'s purity boundary — the same rule that blocks Electron and every Node built-in throughout `src/shared` — also blocks `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource` as bare globals. A future edit that tried to add a real network call to a provider living in this directory would fail lint, not merely fail review.
+- **Cancellation is a plain `AbortSignal`** — the standard, dependency-free mechanism. Nothing here starts a timer or a request that would need a bespoke cancellation channel; this is a real, exercised feature (see the mock provider's abort handling below), not a decorative type.
+- **No provider implemented here is real.** The only implementation in this codebase is the deterministic mock. Adding a real provider (GLM, an OpenAI-compatible endpoint, Ollama) is explicitly out of scope for this milestone and is not designed here beyond the interface shape — in particular, _how_ a future real provider would use an API key without a plaintext key ever reaching this layer is an open question for whichever milestone adds one, not answered by this one.
+
+## Mock provider
+
+`src/shared/chat/mock-provider.ts`'s `createMockChatProvider()` is the only `ChatProvider` in this codebase.
+
+- **Deterministic.** The reply is templated from the conversation alone — the latest user message, truncated to 200 characters and echoed into a fixed sentence. The same conversation always produces the same reply.
+- **No network request, no secret access.** It reads nothing from settings or the secret store; its only input is the `messages` array it is handed.
+- **Clearly marked.** Every reply begins with `[Mock provider]` and states plainly that no real model is connected and no network request was made.
+- **Simulated latency, not randomness.** `delayMs` (default 400ms) makes the loading state actually visible in the UI; tests pass `delayMs: 0` for an instant, still-deterministic result, or use fake timers to assert the loading state mid-delay.
+- **A documented, deterministic failure trigger.** Sending the exact message `/mock-fail` (`MOCK_CHAT_PROVIDER_FAILURE_TRIGGER`) makes the provider reject with a `ChatProviderError('PROVIDER_REQUEST_FAILED', …)` instead of responding. This exists so the failure and retry UI can be exercised — by tests and during manual review — without needing a real, flaky failure to occur.
+- **Injectable.** Tests construct their own `ChatProvider` implementations (see `tests/unit/renderer/conversation-controller.test.ts`) to control exactly when and how a response resolves, independent of the mock's own timing.
+
+---
+
+## Conversation state
+
+`src/renderer/chat/conversation-controller.ts`'s `ConversationController` is **framework-independent** — no React import, no DOM dependency beyond standard globals (`crypto.randomUUID`, `AbortController`, `setTimeout`) available in both a browser and Vitest's `node` test environment. This mirrors the pure-core-behind-a-thin-adapter split already used elsewhere in this codebase (`decidePermission`, `main/settings-service.ts`), and it is what makes every conversation behaviour unit-testable with plain Vitest — no React Testing Library, no jsdom, neither of which is part of this project's toolchain (see `docs/security-model.md`, known limitation 18).
+
+`useConversation.ts` is the thin React binding: it owns no logic, only a `useState`/`useEffect` subscription to the controller.
+
+**State shape:**
+
+```ts
+interface ConversationState {
+  readonly messages: readonly ChatMessage[];
+  readonly status: 'idle' | 'awaiting-response';
+  readonly error: { readonly message: string } | null;
+}
+```
+
+**The message list is append-only.** Once added, a message is never mutated or removed — on success, on failure, or on retry. Loading and error state live _outside_ the message array entirely, which is the design decision behind `ChatMessage.status` going unused in this milestone: a failed attempt never becomes an `'error'`-status message sitting in the transcript. Instead:
+
+- **Submit** trims the input, validates it through `createChatMessage`, appends the user message, sets `status: 'awaiting-response'`, and calls the provider. A no-op for a blank message, and a no-op while a response is already pending — the duplicate-submission guard.
+- **On success**, the assistant's reply is validated through the same `createChatMessage` and appended; `status` returns to `'idle'`.
+- **On failure** (a thrown `ChatProviderError` or any other exception), **no assistant message is added.** The user's message stays exactly where it was; `status` returns to `'idle'`; `error` is set to a generic, safe message. A raw `Error.message` from an unknown exception is never forwarded — an assistant reply is untrusted output, and symmetrically, so is whatever a provider implementation throws.
+- **Retry** re-sends the existing conversation without adding a second copy of the last user message, and is a no-op unless idle with a standing error.
+- **A conversation at `CHAT_CONVERSATION_MAX_MESSAGES`** refuses further submission with an explanatory error, without contacting the provider.
+- **Cancellation.** Each request gets its own `AbortController`; `dispose()` (called from `useConversation`'s unmount cleanup) aborts any in-flight request and stops delivering further state updates — the same purpose the `cancelled` boolean flag already serves around `App.tsx`'s async effects, backed here by a real signal since `ChatProvider.send` accepts one.
+
+---
+
+## UI
+
+`src/renderer/chat/Chat.tsx`, mounted from `App.tsx`'s `'ready'` phase, replacing the previous static welcome screen with the assistant's name and status line as a compact header above the chat surface.
+
+- **Empty state** — a friendly prompt when no messages exist yet, explicitly naming the mock provider.
+- **Message list** (`role="log"`, `aria-live="polite"`) — each message a bubble labelled by role.
+- **Loading state** — an `aria-live` "…is thinking" line while `status === 'awaiting-response'`; the composer is disabled for the same duration, which is the actual duplicate-submission prevention the user sees (the controller enforces it structurally regardless).
+- **Error state** (`role="alert"`) with a **Retry** button, shown only when `state.error` is set.
+- **Composer** — a `<textarea>` (multi-line, since content allows `\n`) with a visible `<label>`, Enter to send, Shift+Enter for a newline (via the textarea's owning `<form>`'s native `requestSubmit()`, not a hand-built event), and a submit button whose label changes while sending.
+
+**No unsafe HTML rendering.** `message.content` is rendered as a plain JSX text child — React escapes every string child by default, so no provider response, however hostile, can inject markup or execute a script. `dangerouslySetInnerHTML` appears nowhere in this milestone. Multi-line content is preserved visually with CSS `white-space: pre-wrap`, not by converting `\n` into `<br>` markup. **Markdown rendering does not exist in this milestone** — the simplest way to satisfy "never render Markdown as executable HTML unless safely sanitized and explicitly justified" is to not render Markdown at all yet, which sidesteps needing a sanitizer dependency or a justification for one.
+
+---
+
+## Security boundary
+
+- **No new IPC channel.** `src/preload/index.ts` is unmodified; the bridge still exposes exactly `health`, `settings.{get,update}` and `secrets.{status,write,clear}`, asserted by the unmodified end-to-end bridge-shape test. Chat never calls `window.localAgent` at all.
+- **No privileged action can be triggered by chat text.** There is no code path from a chat message — typed by the user or returned by a provider — to `main/executor.ts`, to `handleActionProposal`, or to any Electron or Node API. The entire chat feature runs inside the sandboxed, unprivileged renderer and the pure `src/shared` layer.
+- **No model output is treated as authorization for anything.** This is not a policy chat honours; it is a structural absence — there is no mechanism anywhere in this milestone by which text returned from a `ChatProvider` could reach the permission engine, the executor, or any action proposal.
+- **No secret reaches chat state.** The mock provider never imports `main/secrets.ts` (it cannot — it is not privileged code and has no path to it), never reads settings, and `chatMessageMetadataSchema` structurally rejects a secret-looking metadata field unless its value is already redacted.
+- **No network request is possible**, not merely absent by inspection: `src/shared/chat/*`'s network-capable globals are blocked by the same ESLint rule that has protected `src/shared` since Milestone 1. `tests/unit/shared/mock-provider.test.ts` additionally spies on `globalThis.fetch` at runtime and asserts it is never called, across a success and a failure.
+- **Every Phase 1 security boundary is unmodified.** `main/*`, `src/preload/index.ts`, `eslint.config.js`, the permission engine, the audit log, and the emergency-stop runtime have zero diff in this milestone. `tests/e2e/electron-smoke.test.ts` still passes unmodified, confirming the sandbox, the CSP, and the exact bridge shape all hold.
+
+---
+
+## Testing
+
+| Area                                                                                                                                                                                                                 | File                                                  |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Message schema validation (roles, bounds, control characters, bidi, metadata redaction, unknown fields)                                                                                                              | `tests/unit/shared/chat.schema.test.ts`               |
+| Mock provider (determinism, marking, echo/truncation, delay, the failure trigger, abort, no `fetch` call)                                                                                                            | `tests/unit/shared/mock-provider.test.ts`             |
+| Conversation behaviour (submit, loading, success, failure preserving prior state, retry without duplication, duplicate-submission prevention, oversized-message rejection, conversation-length bound, dispose/abort) | `tests/unit/renderer/conversation-controller.test.ts` |
+
+**No component-level render test exists for `Chat.tsx`**, for the same reason `Onboarding.tsx` and `App.tsx` have none (`docs/security-model.md`, known limitation 18): React Testing Library and jsdom are not part of this project's toolchain, and this milestone did not add them. This gap is substantially narrower than it would otherwise be, because every behaviour that matters — state transitions, validation, error handling, HTML-safety of stored content — is implemented in the framework-independent `ConversationController` and is fully covered there. What remains untested by an automated test is purely the JSX rendering and event wiring in `Chat.tsx` itself (for example, whether a click actually reaches `retry()`).
+
+---
+
+## What remains deferred
+
+Everything in the Phase 2, Milestone 1 task's "Do not implement" list remains genuinely absent, not merely unused:
+
+- Real cloud model calls; real Ollama, GLM, or OpenAI-compatible requests
+- API-key retrieval for a provider call
+- New privileged tools, filesystem access, shell execution, browser automation
+- Email, camera, microphone, voice
+- Autonomous actions, background agents, multi-agent runtime
+- Vector memory or RAG
+- Plugin marketplace, cloud sync, telemetry
+- Any action execution from model output
+
+A later Phase 2 milestone that adds a real provider, a tool, or persistence for conversation history is expected to extend this design (the `ChatProvider` interface, the message schema's `tool` role and `metadata` field) rather than replace it — but doing so is out of scope here and not started.
diff --git a/src/main/secrets.ts b/src/main/secrets.ts
index cfceac5..abb3b1c 100644
--- a/src/main/secrets.ts
+++ b/src/main/secrets.ts
@@ -49,14 +49,29 @@ import type { SecretStoreFile } from '../shared/schemas';
 const MAX_SECRET_STORE_JSON_DEPTH = 64;
 
 /**
- * Mirrors `main/settings.ts`'s retry budget exactly. A second, independent
- * copy rather than a shared import, consistent with `main/policy.ts` and
- * `main/emergency.ts`: this module should not gain a runtime dependency on an
- * already-reviewed module from an earlier milestone for one small,
- * self-contained, pure helper.
+ * Same mechanism as `main/settings.ts`'s and `main/emergency.ts`'s identical
+ * retry, for the same reason — a destination-file rename can transiently
+ * fail on Windows (`EPERM`, `EBUSY`, `EACCES`) when something else briefly
+ * holds the destination path open. A second, independent copy rather than a
+ * shared import, consistent with `main/policy.ts` and `main/emergency.ts`:
+ * this module should not gain a runtime dependency on an already-reviewed
+ * module from an earlier milestone for one small, self-contained, pure
+ * helper.
+ *
+ * The budget matches `main/emergency.ts`'s, not `main/settings.ts`'s
+ * smaller original: this repository now has three modules performing this
+ * same atomic-rename pattern, each with its own concurrent-write test, and
+ * running all of them together in one full suite run measurably increases
+ * how often a transient sharing violation needs more than 5 attempts to
+ * clear — reproduced directly against this module's own 8-way concurrency
+ * test failing intermittently only as part of the full suite, never in
+ * isolation, exactly the failure mode `main/emergency.ts`'s own comment
+ * already documents for the same underlying cause. Each attempt is still one
+ * whole-file rename, so a larger budget only ever risks a longer delay
+ * before giving up, never a partial write.
  */
-const RENAME_MAX_ATTEMPTS = 5;
-const RENAME_RETRY_DELAY_MS = 15;
+const RENAME_MAX_ATTEMPTS = 10;
+const RENAME_RETRY_DELAY_MS = 20;
 
 function isTransientRenameError(error: unknown): boolean {
   if (typeof error !== 'object' || error === null || !('code' in error)) return false;
diff --git a/src/renderer/App.tsx b/src/renderer/App.tsx
index 0de76cb..2199084 100644
--- a/src/renderer/App.tsx
+++ b/src/renderer/App.tsx
@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'react';
 
+import { Chat } from './chat/Chat';
 import { Onboarding } from './Onboarding';
 import { createDefaultSettings } from '../shared/schemas';
 import type { Settings } from '../shared/schemas';
@@ -64,15 +65,19 @@ export function App() {
     );
   }
 
+  const assistantName = settings?.assistant.name ?? 'JARVIS';
+
   return (
-    <main>
-      <p className="eyebrow">LOCAL-FIRST INTELLIGENCE</p>
-      <h1>{settings?.assistant.name ?? 'JARVIS'}</h1>
-      <p className="lede">A secure foundation for your personal AI assistant.</p>
-      {settings && settings.user.displayName.length > 0 && (
-        <p className="lede">Welcome back, {settings.user.displayName}.</p>
-      )}
-      <p className="status">Main process: {health}</p>
+    <main className="app-ready">
+      <header className="app-header">
+        <p className="eyebrow">LOCAL-FIRST INTELLIGENCE</p>
+        <h1>{assistantName}</h1>
+        {settings && settings.user.displayName.length > 0 && (
+          <p className="lede">Welcome back, {settings.user.displayName}.</p>
+        )}
+        <p className="status">Main process: {health}</p>
+      </header>
+      <Chat assistantName={assistantName} />
     </main>
   );
 }
diff --git a/src/renderer/chat/Chat.tsx b/src/renderer/chat/Chat.tsx
new file mode 100644
index 0000000..1b60ad7
--- /dev/null
+++ b/src/renderer/chat/Chat.tsx
@@ -0,0 +1,128 @@
+import { useMemo, useRef, useState, type FormEvent, type KeyboardEvent } from 'react';
+
+import { useConversation } from './useConversation';
+import { createMockChatProvider } from '../../shared/chat';
+import type { ChatMessage } from '../../shared/schemas';
+
+interface ChatProps {
+  readonly assistantName: string;
+}
+
+const ROLE_LABELS: Record<ChatMessage['role'], string> = {
+  system: 'System',
+  user: 'You',
+  assistant: 'Assistant',
+  tool: 'Tool',
+};
+
+/**
+ * One message bubble.
+ *
+ * `message.content` is rendered as plain JSX text — React escapes every
+ * string child by default, so this can never inject HTML or execute a
+ * script, no matter what a provider (mock today, real in a later phase)
+ * returns. `dangerouslySetInnerHTML` and Markdown-to-HTML rendering are
+ * deliberately absent from this milestone; see
+ * `docs/phase-2-chat-architecture.md`. `white-space: pre-wrap` (in
+ * `styles.css`) preserves line breaks without needing to turn `\n` into
+ * markup.
+ */
+function MessageBubble({ message }: { readonly message: ChatMessage }) {
+  return (
+    <div className={`chat-message chat-message--${message.role}`}>
+      <span className="chat-message__role">{ROLE_LABELS[message.role]}</span>
+      <p className="chat-message__content">{message.content}</p>
+    </div>
+  );
+}
+
+/**
+ * Chat surface for Phase 2, Milestone 1.
+ *
+ * Talks only to the deterministic mock provider, entirely inside the
+ * renderer — no IPC channel, no call to `window.localAgent`, so nothing
+ * typed here can reach a privileged API, a file, the network, or an action
+ * the permission engine would need to see. Assistant text is untrusted
+ * output: displayed, never executed, never treated as authorization for
+ * anything.
+ */
+export function Chat({ assistantName }: ChatProps) {
+  const provider = useMemo(() => createMockChatProvider(), []);
+  const { state, canSubmit, submit, retry } = useConversation(provider);
+  const [draft, setDraft] = useState('');
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>): Promise<void> {
+    event.preventDefault();
+    if (!canSubmit || draft.trim().length === 0) return;
+    const content = draft;
+    setDraft('');
+    await submit(content);
+    inputRef.current?.focus();
+  }
+
+  /**
+   * Enter sends; Shift+Enter inserts a newline, since chat content is
+   * multi-line-capable. Delegates to the real form submit rather than
+   * calling `handleSubmit` with a hand-built event, so the browser's native
+   * `HTMLFormElement.requestSubmit()` path — including any future native
+   * form validation — runs exactly as it would for a mouse click.
+   */
+  function handleKeyDown(event: KeyboardEvent<HTMLTextAreaElement>): void {
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault();
+      event.currentTarget.form?.requestSubmit();
+    }
+  }
+
+  return (
+    <section className="chat" aria-label={`Chat with ${assistantName}`}>
+      <div className="chat__transcript" role="log" aria-live="polite" aria-label="Conversation">
+        {state.messages.length === 0 ? (
+          <p className="chat__empty">
+            No messages yet. Say hello to {assistantName} — every reply right now comes from a local
+            mock provider, not a real model.
+          </p>
+        ) : (
+          state.messages.map((message) => <MessageBubble key={message.id} message={message} />)
+        )}
+        {state.status === 'awaiting-response' && (
+          <p className="chat__loading" aria-live="polite">
+            {assistantName} is thinking…
+          </p>
+        )}
+      </div>
+
+      {state.error && (
+        <div className="chat__error" role="alert">
+          <p>{state.error.message}</p>
+          <button type="button" onClick={() => void retry()} disabled={!canSubmit}>
+            Retry
+          </button>
+        </div>
+      )}
+
+      <form className="chat__composer" onSubmit={(event) => void handleSubmit(event)}>
+        <label htmlFor="chat-composer-input" className="chat__composer-label">
+          Message
+        </label>
+        <textarea
+          id="chat-composer-input"
+          ref={inputRef}
+          value={draft}
+          maxLength={8000}
+          rows={2}
+          placeholder={`Message ${assistantName}… (Enter to send, Shift+Enter for a new line)`}
+          disabled={!canSubmit}
+          onChange={(event) => {
+            setDraft(event.target.value);
+          }}
+          onKeyDown={handleKeyDown}
+        />
+        <button type="submit" disabled={!canSubmit || draft.trim().length === 0}>
+          {canSubmit ? 'Send' : 'Sending…'}
+        </button>
+      </form>
+    </section>
+  );
+}
diff --git a/src/renderer/chat/conversation-controller.ts b/src/renderer/chat/conversation-controller.ts
new file mode 100644
index 0000000..8ae0747
--- /dev/null
+++ b/src/renderer/chat/conversation-controller.ts
@@ -0,0 +1,220 @@
+/**
+ * Conversation state management (Phase 2, Milestone 1).
+ *
+ * Framework-independent on purpose: `ConversationController` holds no
+ * reference to React and imports nothing from `src/renderer` other than the
+ * shared chat schema and provider types. This is the same split the main
+ * process already uses elsewhere in this codebase — a pure core
+ * (`decidePermission`, `main/settings-service.ts`) behind a thin adapter that
+ * does the I/O or, here, the UI binding (`useConversation.ts`) — and it means
+ * every conversation behaviour below (submit, retry, loading, failure,
+ * duplicate-submission prevention) is unit-testable with plain Vitest, no
+ * React Testing Library or DOM required.
+ *
+ * The message list is append-only. Once a message is added, it is never
+ * mutated or removed — including on failure or retry, so prior conversation
+ * is never lost. Loading and error state live outside the message array
+ * entirely; see `CHAT_MESSAGE_STATUSES`'s doc comment in `src/shared/constants.ts`
+ * for why a failed attempt does not become an `'error'`-status message.
+ *
+ * This module never imports Electron, never touches `window.localAgent`,
+ * and never reaches the filesystem, the network, or any privileged API.
+ * Nothing a `ChatProvider` returns is ever treated as authorization for an
+ * action — there is no action to authorize here at all.
+ */
+
+import { createChatMessage, type ChatMessage } from '../../shared/schemas';
+import { CHAT_CONVERSATION_MAX_MESSAGES } from '../../shared/constants';
+import type { ChatProvider } from '../../shared/chat';
+
+export type ConversationStatus = 'idle' | 'awaiting-response';
+
+export interface ConversationError {
+  readonly message: string;
+}
+
+export interface ConversationState {
+  readonly messages: readonly ChatMessage[];
+  readonly status: ConversationStatus;
+  readonly error: ConversationError | null;
+}
+
+export type ConversationListener = (state: ConversationState) => void;
+
+export interface ConversationControllerDeps {
+  readonly provider: ChatProvider;
+  /** Injectable for deterministic tests. Defaults to the real clock. */
+  readonly now?: () => string;
+  /** Injectable for deterministic tests. Defaults to `crypto.randomUUID()`. */
+  readonly generateId?: () => string;
+}
+
+function initialState(): ConversationState {
+  return { messages: [], status: 'idle', error: null };
+}
+
+const GENERIC_SEND_ERROR =
+  'Your message could not be sent. It may be too long or contain characters that are not allowed.';
+const GENERIC_PROVIDER_ERROR =
+  'The assistant could not respond. Your message was not lost — you can try again.';
+const CONVERSATION_FULL_ERROR =
+  'This conversation has reached its maximum length. Start a new conversation to continue.';
+
+/**
+ * Turns a thrown provider or validation error into conversation-facing text.
+ *
+ * Deliberately never forwards a raw `Error.message`: an assistant reply is
+ * untrusted output, and so, symmetrically, is whatever a provider
+ * implementation throws — a raw message could describe an internal detail
+ * (a URL, a stack fragment) that has no reason to reach the interface. Every
+ * failure gets the same generic, safe message today; this function is the
+ * one place a later milestone would add provider-specific wording (a
+ * distinct message for a timeout versus a rejected key, say) without
+ * touching the state machine around it. The aborted case
+ * (`ChatProviderError` with code `'PROVIDER_ABORTED'`) never actually reaches
+ * here — `requestAssistantReply` returns before calling this function
+ * whenever its own `AbortSignal` fired — so there is nothing to special-case
+ * yet.
+ */
+function describeProviderFailure(_error: unknown): string {
+  return GENERIC_PROVIDER_ERROR;
+}
+
+/**
+ * Orchestrates one conversation against one `ChatProvider`.
+ *
+ * Not a React hook — see `useConversation.ts` for the thin binding that
+ * exposes this to a component via `useState`/`useEffect`.
+ */
+export class ConversationController {
+  private readonly provider: ChatProvider;
+  private readonly now: () => string;
+  private readonly generateId: () => string;
+  private readonly listeners = new Set<ConversationListener>();
+  private state: ConversationState = initialState();
+  private activeAbortController: AbortController | null = null;
+  private disposed = false;
+
+  constructor(deps: ConversationControllerDeps) {
+    this.provider = deps.provider;
+    this.now = deps.now ?? (() => new Date().toISOString());
+    this.generateId = deps.generateId ?? (() => crypto.randomUUID());
+  }
+
+  getState(): ConversationState {
+    return this.state;
+  }
+
+  /** True while idle and able to accept a new submission or a retry. */
+  get canSubmit(): boolean {
+    return this.state.status === 'idle';
+  }
+
+  subscribe(listener: ConversationListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private setState(next: ConversationState): void {
+    this.state = next;
+    if (this.disposed) return;
+    for (const listener of this.listeners) {
+      listener(next);
+    }
+  }
+
+  /**
+   * Adds the user's message and requests a reply.
+   *
+   * A no-op while a response is already pending — the duplicate-submission
+   * guard — and a no-op for a blank (whitespace-only) message. Content is
+   * trimmed before it becomes part of the conversation, matching the
+   * onboarding form's existing convention for user-typed fields.
+   */
+  async submit(rawContent: string): Promise<void> {
+    if (!this.canSubmit) return;
+
+    const trimmed = rawContent.trim();
+    if (trimmed.length === 0) return;
+
+    if (this.state.messages.length >= CHAT_CONVERSATION_MAX_MESSAGES) {
+      this.setState({ ...this.state, error: { message: CONVERSATION_FULL_ERROR } });
+      return;
+    }
+
+    let userMessage: ChatMessage;
+    try {
+      userMessage = createChatMessage({
+        id: this.generateId(),
+        role: 'user',
+        content: trimmed,
+        createdAt: this.now(),
+      });
+    } catch {
+      this.setState({ ...this.state, error: { message: GENERIC_SEND_ERROR } });
+      return;
+    }
+
+    const nextMessages = [...this.state.messages, userMessage];
+    this.setState({ messages: nextMessages, status: 'awaiting-response', error: null });
+    await this.requestAssistantReply(nextMessages);
+  }
+
+  /**
+   * Re-requests a reply for the current conversation after a failure.
+   *
+   * Adds no new user message — the one already in the transcript is reused
+   * exactly as submitted. A no-op unless idle with a standing error, so
+   * retry cannot fire concurrently with a submission or with itself.
+   */
+  async retry(): Promise<void> {
+    if (!this.canSubmit) return;
+    if (this.state.error === null) return;
+    if (this.state.messages.length === 0) return;
+
+    const messages = this.state.messages;
+    this.setState({ messages, status: 'awaiting-response', error: null });
+    await this.requestAssistantReply(messages);
+  }
+
+  private async requestAssistantReply(messages: readonly ChatMessage[]): Promise<void> {
+    this.activeAbortController?.abort();
+    const controller = new AbortController();
+    this.activeAbortController = controller;
+
+    try {
+      const result = await this.provider.send({ messages }, { signal: controller.signal });
+      if (controller.signal.aborted) return;
+
+      const assistantMessage = createChatMessage({
+        id: this.generateId(),
+        role: 'assistant',
+        content: result.content,
+        createdAt: this.now(),
+      });
+      this.setState({ messages: [...messages, assistantMessage], status: 'idle', error: null });
+    } catch (error) {
+      if (controller.signal.aborted) return;
+      this.setState({
+        messages,
+        status: 'idle',
+        error: { message: describeProviderFailure(error) },
+      });
+    }
+  }
+
+  /**
+   * Aborts any in-flight request and stops delivering further state updates.
+   *
+   * Called from `useConversation.ts`'s unmount cleanup, mirroring the
+   * `cancelled` flag `App.tsx` already uses around its own async effects —
+   * here backed by a real `AbortSignal` passed to the provider, rather than
+   * only a local flag, since {@link ChatProvider.send} accepts one.
+   */
+  dispose(): void {
+    this.disposed = true;
+    this.activeAbortController?.abort();
+  }
+}
diff --git a/src/renderer/chat/useConversation.ts b/src/renderer/chat/useConversation.ts
new file mode 100644
index 0000000..7275d24
--- /dev/null
+++ b/src/renderer/chat/useConversation.ts
@@ -0,0 +1,51 @@
+/**
+ * Thin React binding over `ConversationController` (Phase 2, Milestone 1).
+ *
+ * Deliberately minimal: this hook owns no conversation logic of its own —
+ * everything observable here is delegated to the controller, which is
+ * unit-tested directly in `tests/unit/renderer/conversation-controller.test.ts`
+ * without React. This hook exists only to subscribe a component to the
+ * controller's state and to give it stable `submit`/`retry` callbacks.
+ */
+
+import { useEffect, useMemo, useState } from 'react';
+
+import { ConversationController, type ConversationState } from './conversation-controller';
+import type { ChatProvider } from '../../shared/chat';
+
+export interface UseConversationResult {
+  readonly state: ConversationState;
+  readonly canSubmit: boolean;
+  readonly submit: (content: string) => Promise<void>;
+  readonly retry: () => Promise<void>;
+}
+
+/**
+ * One controller instance per mounted provider identity. Passing a new
+ * `provider` reference starts a fresh conversation — this milestone has
+ * exactly one call site (`Chat.tsx`) and it never swaps providers at
+ * runtime, so this is a deliberate simplicity choice, not an oversight.
+ */
+export function useConversation(provider: ChatProvider): UseConversationResult {
+  const controller = useMemo(() => new ConversationController({ provider }), [provider]);
+  const [state, setState] = useState<ConversationState>(() => controller.getState());
+
+  useEffect(() => {
+    setState(controller.getState());
+    const unsubscribe = controller.subscribe(setState);
+    return () => {
+      unsubscribe();
+      controller.dispose();
+    };
+  }, [controller]);
+
+  return {
+    state,
+    // Derived from the same `state` this hook re-renders on, not read
+    // imperatively from the controller, so it can never lag one render
+    // behind what is displayed.
+    canSubmit: state.status === 'idle',
+    submit: (content: string) => controller.submit(content),
+    retry: () => controller.retry(),
+  };
+}
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 32020c6..c2c7376 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -94,3 +94,133 @@ button.secondary {
   color: #e88;
   font-size: 0.9rem;
 }
+
+/* --------------------------------------------------------------------- */
+/* Chat (Phase 2, Milestone 1)                                           */
+/* --------------------------------------------------------------------- */
+
+main.app-ready {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  padding: 1.25rem 1.5rem 1.5rem;
+  box-sizing: border-box;
+  gap: 1rem;
+}
+.app-header {
+  flex: 0 0 auto;
+}
+.app-header h1 {
+  font-size: clamp(1.6rem, 4vw, 2.4rem);
+  margin: 0.15rem 0;
+}
+.app-header .status {
+  margin-top: 0.4rem;
+  font-size: 0.85rem;
+}
+
+.chat {
+  flex: 1 1 auto;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  gap: 0.75rem;
+}
+.chat__transcript {
+  flex: 1 1 auto;
+  min-height: 12rem;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+  padding: 0.75rem;
+  border: 1px solid #2a3750;
+  border-radius: 0.6rem;
+  background: #0c1626;
+}
+.chat__empty {
+  margin: auto;
+  max-width: 28rem;
+  text-align: center;
+  color: #aebbd0;
+}
+.chat-message {
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+  max-width: 80%;
+  padding: 0.5rem 0.75rem;
+  border-radius: 0.6rem;
+  background: #101a2c;
+}
+.chat-message--user {
+  align-self: flex-end;
+  background: #16324a;
+}
+.chat-message--assistant {
+  align-self: flex-start;
+}
+.chat-message--system,
+.chat-message--tool {
+  align-self: center;
+  background: transparent;
+  border: 1px dashed #2a3750;
+}
+.chat-message__role {
+  font-size: 0.7rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: #73d5c8;
+}
+.chat-message__content {
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: #e8edf5;
+}
+.chat__loading {
+  margin: 0;
+  color: #aebbd0;
+  font-style: italic;
+}
+.chat__error {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.6rem 0.8rem;
+  border-radius: 0.5rem;
+  border: 1px solid #6b2a2a;
+  background: #2a1414;
+  color: #e88;
+}
+.chat__error p {
+  margin: 0;
+}
+.chat__composer {
+  display: flex;
+  gap: 0.6rem;
+  align-items: flex-end;
+}
+.chat__composer-label {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
+.chat__composer textarea {
+  flex: 1 1 auto;
+  resize: vertical;
+  padding: 0.6rem 0.7rem;
+  border-radius: 0.5rem;
+  border: 1px solid #2a3750;
+  background: #101a2c;
+  color: #e8edf5;
+  font-family: inherit;
+  font-size: 1rem;
+}
+.chat__composer textarea:disabled {
+  opacity: 0.6;
+}
diff --git a/src/shared/chat/index.ts b/src/shared/chat/index.ts
new file mode 100644
index 0000000..408670d
--- /dev/null
+++ b/src/shared/chat/index.ts
@@ -0,0 +1,19 @@
+/**
+ * Barrel for the chat provider layer (Phase 2, Milestone 1).
+ *
+ * Everything exported here is pure, has no Electron or Node dependency, and
+ * makes no network request — see `provider.ts` and `mock-provider.ts` for
+ * why that is enforced structurally, not only by convention.
+ */
+
+export { CHAT_PROVIDER_ERROR_CODES, ChatProviderError } from './provider';
+export type {
+  ChatProvider,
+  ChatProviderErrorCode,
+  ChatProviderRequest,
+  ChatProviderRequestOptions,
+  ChatProviderResult,
+} from './provider';
+
+export { createMockChatProvider, MOCK_CHAT_PROVIDER_DEFAULT_DELAY_MS } from './mock-provider';
+export type { CreateMockChatProviderOptions } from './mock-provider';
diff --git a/src/shared/chat/mock-provider.ts b/src/shared/chat/mock-provider.ts
new file mode 100644
index 0000000..8d1fe4f
--- /dev/null
+++ b/src/shared/chat/mock-provider.ts
@@ -0,0 +1,140 @@
+/**
+ * Deterministic mock chat provider (Phase 2, Milestone 1).
+ *
+ * The only `ChatProvider` implementation in this codebase. It makes no
+ * network request — this file cannot: `fetch`, `XMLHttpRequest`, `WebSocket`
+ * and `EventSource` are blocked as globals throughout `src/shared` by
+ * `eslint.config.js`, the same boundary that keeps this layer free of
+ * Electron and Node built-ins. It reads no setting and no secret; its only
+ * input is the conversation it is handed.
+ *
+ * Every response is templated from the request alone, so the same
+ * conversation always produces the same reply — no randomness, no wall-clock
+ * dependency in the reply text itself (the artificial delay is timing, not
+ * content, and is fully controllable by a caller for tests).
+ */
+
+import {
+  ChatProviderError,
+  type ChatProvider,
+  type ChatProviderRequest,
+  type ChatProviderRequestOptions,
+  type ChatProviderResult,
+} from './provider';
+import { MOCK_CHAT_PROVIDER_FAILURE_TRIGGER, MOCK_CHAT_PROVIDER_ID } from '../constants';
+
+/** Default simulated latency, long enough that a UI's loading state is actually visible. */
+export const MOCK_CHAT_PROVIDER_DEFAULT_DELAY_MS = 400;
+
+/** Longest prefix of the triggering user message ever echoed back into a mock reply. */
+const ECHO_MAX_LENGTH = 200;
+
+export interface CreateMockChatProviderOptions {
+  /**
+   * Simulated latency in milliseconds before the reply resolves. Defaults to
+   * {@link MOCK_CHAT_PROVIDER_DEFAULT_DELAY_MS}. Tests pass `0` for an
+   * instant, still-deterministic response.
+   */
+  readonly delayMs?: number;
+}
+
+function lastUserContent(request: ChatProviderRequest): string | null {
+  for (let index = request.messages.length - 1; index >= 0; index -= 1) {
+    const message = request.messages[index];
+    if (message?.role === 'user') return message.content;
+  }
+  return null;
+}
+
+function buildReplyContent(request: ChatProviderRequest): string {
+  const latest = lastUserContent(request);
+  if (latest === null) {
+    return (
+      '[Mock provider] No real model is connected in this milestone. ' +
+      'This is a deterministic placeholder response — no network request was made.'
+    );
+  }
+
+  const truncated =
+    latest.length > ECHO_MAX_LENGTH ? `${latest.slice(0, ECHO_MAX_LENGTH)}…` : latest;
+
+  return (
+    `[Mock provider] I received your message: "${truncated}". ` +
+    'No real model is connected in this milestone — this is a deterministic ' +
+    'placeholder response and no network request was made.'
+  );
+}
+
+/**
+ * Waits `delayMs`, or rejects early with `PROVIDER_ABORTED` if `signal` fires
+ * first. `delayMs <= 0` resolves on the next microtask without starting a
+ * timer, so tests need no fake-timer setup to get an instant, deterministic
+ * result.
+ */
+async function delay(delayMs: number, signal: AbortSignal | undefined): Promise<void> {
+  if (signal?.aborted) {
+    throw new ChatProviderError(
+      'PROVIDER_ABORTED',
+      'The request was aborted before the mock provider responded.',
+    );
+  }
+  if (delayMs <= 0) {
+    await Promise.resolve();
+    if (signal?.aborted) {
+      throw new ChatProviderError(
+        'PROVIDER_ABORTED',
+        'The request was aborted before the mock provider responded.',
+      );
+    }
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const timer: ReturnType<typeof setTimeout> = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, delayMs);
+
+    function onAbort(): void {
+      clearTimeout(timer);
+      reject(
+        new ChatProviderError(
+          'PROVIDER_ABORTED',
+          'The request was aborted before the mock provider responded.',
+        ),
+      );
+    }
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * Creates the deterministic mock provider.
+ *
+ * `id` is {@link MOCK_CHAT_PROVIDER_ID} — the only provider identifier in
+ * use anywhere in this codebase today.
+ */
+export function createMockChatProvider(options: CreateMockChatProviderOptions = {}): ChatProvider {
+  const delayMs = options.delayMs ?? MOCK_CHAT_PROVIDER_DEFAULT_DELAY_MS;
+
+  return {
+    id: MOCK_CHAT_PROVIDER_ID,
+    async send(
+      request: ChatProviderRequest,
+      requestOptions?: ChatProviderRequestOptions,
+    ): Promise<ChatProviderResult> {
+      await delay(delayMs, requestOptions?.signal);
+
+      const latest = lastUserContent(request);
+      if (latest !== null && latest.trim() === MOCK_CHAT_PROVIDER_FAILURE_TRIGGER) {
+        throw new ChatProviderError(
+          'PROVIDER_REQUEST_FAILED',
+          'The mock provider was asked to simulate a failure.',
+        );
+      }
+
+      return { content: buildReplyContent(request) };
+    },
+  };
+}
diff --git a/src/shared/chat/provider.ts b/src/shared/chat/provider.ts
new file mode 100644
index 0000000..047fd2d
--- /dev/null
+++ b/src/shared/chat/provider.ts
@@ -0,0 +1,84 @@
+/**
+ * Chat provider abstraction (Phase 2, Milestone 1).
+ *
+ * A `ChatProvider` turns a validated conversation into assistant reply text.
+ * This module defines the shape only. The one implementation that exists in
+ * this milestone is the deterministic mock (`./mock-provider.ts`) — there is
+ * no real provider yet. A future phase adding a real provider (GLM, an
+ * OpenAI-compatible endpoint, Ollama) implements this same interface; nothing
+ * that consumes a `ChatProvider` needs to change when that happens.
+ *
+ * Deliberately provider-independent and inert:
+ *
+ *  - No Electron import, no Node built-in, no filesystem or shell access —
+ *    enforced the same way the rest of `src/shared` is, by
+ *    `eslint.config.js`'s purity boundary.
+ *  - No network access — the same boundary blocks `fetch`, `XMLHttpRequest`,
+ *    `WebSocket` and `EventSource` as globals, so a provider implementation
+ *    placed under `src/shared` cannot make a network request even if a
+ *    future edit tried to add one here by mistake.
+ *  - No secret access — a `ChatProvider` receives only conversation messages,
+ *    never settings, never the secret store. A real provider's API key, when
+ *    one exists, stays inside the main process exactly as it does for
+ *    `secrets.write` today; how a future real provider would reach it without
+ *    handing a plaintext key to this layer is an open design question for the
+ *    milestone that adds one, not answered here.
+ *  - Cancellation is an `AbortSignal`, the standard inert, dependency-free
+ *    mechanism — nothing here starts a timer or a network request that would
+ *    need a bespoke cancellation channel.
+ */
+
+import type { ChatMessage } from '../schemas/chat.schema';
+
+export interface ChatProviderRequest {
+  /** The conversation so far, oldest first, already schema-validated. */
+  readonly messages: readonly ChatMessage[];
+}
+
+export interface ChatProviderResult {
+  /**
+   * Assistant reply text. Untrusted output: a caller must render this as
+   * text only, never as HTML, and must never treat it as authorization for
+   * any action — see `docs/phase-2-chat-architecture.md`.
+   */
+  readonly content: string;
+}
+
+export const CHAT_PROVIDER_ERROR_CODES = ['PROVIDER_REQUEST_FAILED', 'PROVIDER_ABORTED'] as const;
+export type ChatProviderErrorCode = (typeof CHAT_PROVIDER_ERROR_CODES)[number];
+
+/**
+ * A structured provider failure.
+ *
+ * Mirrors `main/executor.ts`'s `ActionExecutionError` pattern: a stable code
+ * a caller can branch on, with `cause` reserved for local debugging only
+ * (never rendered, never sent anywhere) rather than surfacing a raw
+ * provider-internal message to the conversation UI.
+ */
+export class ChatProviderError extends Error {
+  readonly code: ChatProviderErrorCode;
+
+  constructor(code: ChatProviderErrorCode, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'ChatProviderError';
+    this.code = code;
+  }
+}
+
+export interface ChatProviderRequestOptions {
+  /** Abort an in-flight request. See the module doc comment. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * No real provider is implemented in this milestone. Every `ChatProvider` in
+ * this codebase today is the mock in `./mock-provider.ts`.
+ */
+export interface ChatProvider {
+  /** A short, stable identifier — `'mock'` for the only provider that exists yet. */
+  readonly id: string;
+  send(
+    request: ChatProviderRequest,
+    options?: ChatProviderRequestOptions,
+  ): Promise<ChatProviderResult>;
+}
diff --git a/src/shared/constants.ts b/src/shared/constants.ts
index 8836b04..7f55623 100644
--- a/src/shared/constants.ts
+++ b/src/shared/constants.ts
@@ -371,3 +371,72 @@ export const FORBIDDEN_OBJECT_KEYS: readonly string[] = [
   'constructor',
   'prototype',
 ] as const;
+
+// ---------------------------------------------------------------------------
+// Chat (Phase 2, Milestone 1)
+//
+// A mock-only chat foundation: message and conversation shapes, and the
+// bounds that keep a hostile or runaway conversation from producing an
+// unbounded amount of state. No model is called anywhere yet — see
+// docs/phase-2-chat-architecture.md.
+// ---------------------------------------------------------------------------
+
+/**
+ * `tool` is declared now, alongside the roles this milestone actually
+ * produces, so that adding real tool-call support later is a new code path,
+ * not a breaking schema change. Nothing in Phase 2 Milestone 1 constructs a
+ * `tool` message; the mock provider never returns one.
+ */
+export const CHAT_MESSAGE_ROLES = ['system', 'user', 'assistant', 'tool'] as const;
+export type ChatMessageRole = (typeof CHAT_MESSAGE_ROLES)[number];
+
+/**
+ * Optional per-message status metadata.
+ *
+ * Unused by this milestone's actual conversation logic — a failed provider
+ * call never becomes an `'error'`-status message; see
+ * `src/renderer/chat/conversation-controller.ts`, which keeps loading and
+ * error state at the conversation level instead, so the message list stays a
+ * clean, append-only transcript. Declared on the schema now so a later
+ * milestone (for example, a streaming provider marking a message
+ * `'streaming'` while it fills in) is a new enum member, not a new field.
+ */
+export const CHAT_MESSAGE_STATUSES = ['complete', 'error'] as const;
+export type ChatMessageStatus = (typeof CHAT_MESSAGE_STATUSES)[number];
+
+export const CHAT_MESSAGE_CONTENT_MIN_LENGTH = 1;
+/**
+ * Generous enough for a long pasted paragraph; tight enough that a hostile or
+ * accidental multi-megabyte payload cannot be carried as a single message.
+ */
+export const CHAT_MESSAGE_CONTENT_MAX_LENGTH = 8_000;
+
+/**
+ * Maximum number of messages a single conversation may hold in memory.
+ *
+ * Conversation state is not persisted to disk in this milestone — it lives
+ * only in the renderer for the lifetime of the window — so this bound exists
+ * to keep an unbounded chat session from growing memory use without limit,
+ * not to protect a file format.
+ */
+export const CHAT_CONVERSATION_MAX_MESSAGES = 200;
+
+/**
+ * Rejects control characters unsafe in chat content, while still allowing the
+ * tab, newline and carriage return a genuine multi-line message needs — the
+ * one difference from {@link CONTROL_CHARACTER_PATTERN}, which forbids all
+ * three because it guards single-line display strings, not free-form content.
+ */
+// eslint-disable-next-line no-control-regex
+export const CHAT_CONTROL_CHARACTER_PATTERN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/;
+
+/** The only provider implemented in this milestone. */
+export const MOCK_CHAT_PROVIDER_ID = 'mock';
+
+/**
+ * A deterministic, documented way to exercise the failure/retry path without
+ * a real provider to fail. Sending this exact trimmed message content makes
+ * {@link MOCK_CHAT_PROVIDER_ID} reject instead of responding — used by tests
+ * and available during manual review of the failure and retry UI.
+ */
+export const MOCK_CHAT_PROVIDER_FAILURE_TRIGGER = '/mock-fail';
diff --git a/src/shared/schemas/chat.schema.ts b/src/shared/schemas/chat.schema.ts
new file mode 100644
index 0000000..5c1b3eb
--- /dev/null
+++ b/src/shared/schemas/chat.schema.ts
@@ -0,0 +1,85 @@
+/**
+ * Chat message schema (Phase 2, Milestone 1).
+ *
+ * Describes one message in a conversation held only in renderer memory —
+ * nothing here is persisted to disk in this milestone. Every message,
+ * regardless of role, is validated the same way: a message is untrusted input
+ * the moment it did not originate from this module's own factory, whether it
+ * came from a user's keystrokes or from a provider (mock today, real in a
+ * later phase).
+ *
+ * Nothing here executes, interprets, or renders content as anything other
+ * than plain text — see `src/renderer/chat/Chat.tsx`, which never uses
+ * `dangerouslySetInnerHTML`.
+ */
+
+import { z } from 'zod';
+
+import {
+  BIDI_CONTROL_PATTERN,
+  CHAT_CONTROL_CHARACTER_PATTERN,
+  CHAT_MESSAGE_CONTENT_MAX_LENGTH,
+  CHAT_MESSAGE_CONTENT_MIN_LENGTH,
+  CHAT_MESSAGE_ROLES,
+  CHAT_MESSAGE_STATUSES,
+} from '../constants';
+import { auditParametersSchema } from './audit-parameters.schema';
+import type { AuditParameters } from './audit-parameters.schema';
+
+/**
+ * Reuses the audit-parameter schema for message metadata rather than
+ * defining a second bounded-JSON-object schema: the requirements are
+ * identical — plain JSON values only, bounded depth/breadth/size, and any
+ * secret-looking field name rejected unless its value is already the
+ * redaction placeholder. A message's `metadata` can therefore never carry a
+ * credential under a name such as `apiKey` or `token`, enforced the same way
+ * an audit record already is.
+ */
+export const chatMessageMetadataSchema = auditParametersSchema;
+export type ChatMessageMetadata = AuditParameters;
+
+export const chatMessageSchema = z.strictObject({
+  /** Stable, caller-supplied identifier — a UUID generated by the renderer. */
+  id: z.uuid(),
+  role: z.enum(CHAT_MESSAGE_ROLES),
+  content: z
+    .string()
+    .min(CHAT_MESSAGE_CONTENT_MIN_LENGTH)
+    .max(CHAT_MESSAGE_CONTENT_MAX_LENGTH)
+    .refine((value) => !CHAT_CONTROL_CHARACTER_PATTERN.test(value), {
+      message: 'must not contain unsafe control characters',
+    })
+    .refine((value) => !BIDI_CONTROL_PATTERN.test(value), {
+      message: 'must not contain bidirectional control characters',
+    }),
+  /** UTC ISO-8601. Offsets are rejected so every message is comparable and sortable. */
+  createdAt: z.iso.datetime(),
+  /** See {@link CHAT_MESSAGE_STATUSES}'s doc comment for why this is unused today. */
+  status: z.enum(CHAT_MESSAGE_STATUSES).optional(),
+  /** Bounded, JSON-safe, never a credential — see {@link chatMessageMetadataSchema}. */
+  metadata: chatMessageMetadataSchema.optional(),
+});
+
+export type ChatMessage = z.infer<typeof chatMessageSchema>;
+
+/**
+ * Validates and constructs one message.
+ *
+ * Every field the caller cannot vouch for as already-safe (`content`, and
+ * `metadata` if supplied) is untrusted input, so this always runs the full
+ * schema rather than trusting the shape of its argument. Throws a
+ * `z.ZodError` on invalid input — callers (see
+ * `src/renderer/chat/conversation-controller.ts`) catch it and turn it into
+ * conversation-level error state rather than letting it propagate as an
+ * unhandled exception.
+ */
+export function createChatMessage(input: {
+  readonly id: string;
+  readonly role: (typeof CHAT_MESSAGE_ROLES)[number];
+  readonly content: string;
+  readonly createdAt: string;
+  readonly status?: (typeof CHAT_MESSAGE_STATUSES)[number];
+  readonly metadata?: ChatMessageMetadata;
+}): ChatMessage {
+  return chatMessageSchema.parse(input);
+}
diff --git a/src/shared/schemas/index.ts b/src/shared/schemas/index.ts
index da773fe..17c361f 100644
--- a/src/shared/schemas/index.ts
+++ b/src/shared/schemas/index.ts
@@ -87,3 +87,6 @@ export type {
 
 export { createEmptySecretStoreFile, secretStoreFileSchema } from './secrets.schema';
 export type { SecretStoreFile } from './secrets.schema';
+
+export { chatMessageMetadataSchema, chatMessageSchema, createChatMessage } from './chat.schema';
+export type { ChatMessage, ChatMessageMetadata } from './chat.schema';
diff --git a/tests/unit/main/secrets.test.ts b/tests/unit/main/secrets.test.ts
index 25e900f..079a46a 100644
--- a/tests/unit/main/secrets.test.ts
+++ b/tests/unit/main/secrets.test.ts
@@ -300,6 +300,16 @@ describe('concurrency', () => {
   });
 
   it('leaves no orphaned temporary files after many concurrent writes', async () => {
+    // This test intermittently failed with EPERM on `rename` when run as
+    // part of the full suite (never in isolation) under the original
+    // 5-attempt/15ms retry budget — the same class of transient Windows
+    // sharing-violation contention `main/emergency.ts`'s own concurrency
+    // test previously surfaced for the identical atomic-rename pattern. The
+    // fix was widening `main/secrets.ts`'s `RENAME_MAX_ATTEMPTS`/
+    // `RENAME_RETRY_DELAY_MS` to match `main/emergency.ts`'s; see that
+    // module's constant declaration for the full rationale. This test is
+    // the regression guard for that budget — it should keep passing
+    // reliably as part of the full suite, not only alone.
     const safeStorage = createFakeSafeStorage(true);
     await Promise.all(
       Array.from({ length: 8 }, (_, index) =>
diff --git a/tests/unit/renderer/conversation-controller.test.ts b/tests/unit/renderer/conversation-controller.test.ts
new file mode 100644
index 0000000..f2b2813
--- /dev/null
+++ b/tests/unit/renderer/conversation-controller.test.ts
@@ -0,0 +1,310 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { ConversationController } from '../../../src/renderer/chat/conversation-controller';
+import { ChatProviderError } from '../../../src/shared/chat/provider';
+import type {
+  ChatProvider,
+  ChatProviderRequest,
+  ChatProviderResult,
+} from '../../../src/shared/chat/provider';
+import {
+  CHAT_CONVERSATION_MAX_MESSAGES,
+  CHAT_MESSAGE_CONTENT_MAX_LENGTH,
+} from '../../../src/shared/constants';
+
+/** A test clock and id source that never repeats and never depends on the wall clock. */
+function makeDeps() {
+  const baseMs = Date.parse('2026-01-01T00:00:00.000Z');
+  let tick = 0;
+  let idCounter = 0;
+  return {
+    // Adds whole seconds via real Date arithmetic rather than formatting the
+    // tick directly into the seconds field, so this stays a valid ISO-8601
+    // timestamp no matter how many messages a test creates (a naive
+    // `:${tick}` field overflows past 59 seconds and starts producing
+    // strings `z.iso.datetime()` correctly rejects).
+    now: () => {
+      tick += 1;
+      return new Date(baseMs + tick * 1000).toISOString();
+    },
+    generateId: () => {
+      idCounter += 1;
+      return `00000000-0000-4000-8000-${String(idCounter).padStart(12, '0')}`;
+    },
+  };
+}
+
+/** A provider whose resolution is controlled by the test, to inspect intermediate state. */
+function deferredProvider(): {
+  provider: ChatProvider;
+  resolve: (result: ChatProviderResult) => void;
+  reject: (error: unknown) => void;
+  calls: ChatProviderRequest[];
+} {
+  const calls: ChatProviderRequest[] = [];
+  let resolveFn: (result: ChatProviderResult) => void = () => undefined;
+  let rejectFn: (error: unknown) => void = () => undefined;
+
+  const provider: ChatProvider = {
+    id: 'deferred-test-provider',
+    send: (request) => {
+      calls.push(request);
+      return new Promise<ChatProviderResult>((resolve, reject) => {
+        resolveFn = resolve;
+        rejectFn = reject;
+      });
+    },
+  };
+
+  return {
+    provider,
+    resolve: (result) => {
+      resolveFn(result);
+    },
+    reject: (error) => {
+      rejectFn(error);
+    },
+    calls,
+  };
+}
+
+/** A provider that resolves or rejects on the next microtask, for straight-line async tests. */
+function instantProvider(
+  handler: (request: ChatProviderRequest) => ChatProviderResult,
+): ChatProvider {
+  return {
+    id: 'instant-test-provider',
+    send: (request) => Promise.resolve(handler(request)),
+  };
+}
+
+describe('ConversationController', () => {
+  it('starts empty, idle, with no error', () => {
+    const controller = new ConversationController({
+      provider: instantProvider(() => ({ content: 'unused' })),
+      ...makeDeps(),
+    });
+    expect(controller.getState()).toEqual({ messages: [], status: 'idle', error: null });
+    expect(controller.canSubmit).toBe(true);
+  });
+
+  it('adds the user message immediately and enters awaiting-response before the provider resolves', async () => {
+    const { provider, resolve, calls } = deferredProvider();
+    const controller = new ConversationController({ provider, ...makeDeps() });
+
+    const submitPromise = controller.submit('hello there');
+
+    // Synchronous portion of submit() has already run by the time this line
+    // executes, since nothing before the provider call awaits anything.
+    expect(controller.getState().status).toBe('awaiting-response');
+    expect(controller.getState().messages).toHaveLength(1);
+    expect(controller.getState().messages[0]).toMatchObject({
+      role: 'user',
+      content: 'hello there',
+    });
+    expect(calls).toHaveLength(1);
+
+    resolve({ content: 'a reply' });
+    await submitPromise;
+
+    expect(controller.getState().status).toBe('idle');
+    expect(controller.getState().messages).toHaveLength(2);
+    expect(controller.getState().messages[1]).toMatchObject({
+      role: 'assistant',
+      content: 'a reply',
+    });
+  });
+
+  it('trims whitespace before storing the user message', async () => {
+    const controller = new ConversationController({
+      provider: instantProvider(() => ({ content: 'ok' })),
+      ...makeDeps(),
+    });
+    await controller.submit('   hello with padding   ');
+    expect(controller.getState().messages[0]?.content).toBe('hello with padding');
+  });
+
+  it('is a no-op for a whitespace-only message', async () => {
+    const controller = new ConversationController({
+      provider: instantProvider(() => ({ content: 'ok' })),
+      ...makeDeps(),
+    });
+    await controller.submit('    ');
+    expect(controller.getState()).toEqual({ messages: [], status: 'idle', error: null });
+  });
+
+  it('prevents a second submission while a response is pending', async () => {
+    const { provider, resolve, calls } = deferredProvider();
+    const controller = new ConversationController({ provider, ...makeDeps() });
+
+    const first = controller.submit('first message');
+    await controller.submit('second message'); // should be a no-op: status is not idle
+
+    expect(controller.getState().messages).toHaveLength(1);
+    expect(controller.getState().messages[0]?.content).toBe('first message');
+    expect(calls).toHaveLength(1);
+
+    resolve({ content: 'reply' });
+    await first;
+  });
+
+  it('renders assistant output only as message content, never interpreted as markup or code', async () => {
+    const hostile = '<img src=x onerror=alert(1)>${process.exit(1)}';
+    const controller = new ConversationController({
+      provider: instantProvider(() => ({ content: hostile })),
+      ...makeDeps(),
+    });
+    await controller.submit('trigger');
+    expect(controller.getState().messages[1]?.content).toBe(hostile);
+    // The controller stores it as an inert string field; src/renderer/chat/Chat.tsx
+    // is responsible for rendering it as JSX text (verified by inspection: no
+    // dangerouslySetInnerHTML anywhere in that file) rather than markup.
+  });
+
+  it('keeps prior conversation intact after a provider failure', async () => {
+    const controller = new ConversationController({
+      provider: instantProvider(() => {
+        throw new ChatProviderError('PROVIDER_REQUEST_FAILED', 'simulated failure');
+      }),
+      ...makeDeps(),
+    });
+
+    await controller.submit('will fail');
+
+    const state = controller.getState();
+    expect(state.status).toBe('idle');
+    expect(state.error).not.toBeNull();
+    expect(state.messages).toHaveLength(1);
+    expect(state.messages[0]).toMatchObject({ role: 'user', content: 'will fail' });
+  });
+
+  it('never leaks a raw provider error message into conversation state', async () => {
+    const controller = new ConversationController({
+      provider: instantProvider(() => {
+        throw new Error('internal secret detail: connection string leaked here');
+      }),
+      ...makeDeps(),
+    });
+
+    await controller.submit('trigger');
+
+    expect(controller.getState().error?.message).not.toContain('connection string');
+  });
+
+  it('retries using the existing user message without adding a duplicate', async () => {
+    let attempt = 0;
+    const controller = new ConversationController({
+      provider: {
+        id: 'flaky',
+        send: (request) => {
+          attempt += 1;
+          if (attempt === 1) {
+            return Promise.reject(
+              new ChatProviderError('PROVIDER_REQUEST_FAILED', 'first attempt fails'),
+            );
+          }
+          return Promise.resolve({
+            content: `ok on attempt ${String(attempt)}, saw ${String(request.messages.length)} messages`,
+          });
+        },
+      },
+      ...makeDeps(),
+    });
+
+    await controller.submit('please retry me');
+    expect(controller.getState().error).not.toBeNull();
+    expect(controller.getState().messages).toHaveLength(1);
+
+    await controller.retry();
+
+    const state = controller.getState();
+    expect(state.error).toBeNull();
+    expect(state.status).toBe('idle');
+    // Exactly one user message and one assistant message — retry did not
+    // insert a second copy of the user's message.
+    expect(state.messages).toHaveLength(2);
+    expect(state.messages.filter((message) => message.role === 'user')).toHaveLength(1);
+    expect(state.messages[1]?.content).toContain('ok on attempt 2');
+  });
+
+  it('retry is a no-op when there is no standing error', async () => {
+    const send = vi.fn(() => Promise.resolve({ content: 'ok' }));
+    const controller = new ConversationController({
+      provider: { id: 'counting', send },
+      ...makeDeps(),
+    });
+
+    await controller.submit('hello');
+    expect(send).toHaveBeenCalledTimes(1);
+
+    await controller.retry(); // no error present — must not call the provider again
+    expect(send).toHaveBeenCalledTimes(1);
+  });
+
+  it('retry is a no-op while a response is already pending', async () => {
+    const { provider, resolve, calls } = deferredProvider();
+    const controller = new ConversationController({ provider, ...makeDeps() });
+
+    const submitPromise = controller.submit('hello');
+    await controller.retry(); // status is awaiting-response, not idle
+
+    expect(calls).toHaveLength(1);
+    resolve({ content: 'ok' });
+    await submitPromise;
+  });
+
+  it('rejects an oversized message without changing prior state or contacting the provider', async () => {
+    const send = vi.fn(() => Promise.resolve({ content: 'unused' }));
+    const controller = new ConversationController({
+      provider: { id: 'counting', send },
+      ...makeDeps(),
+    });
+
+    await controller.submit('a'.repeat(CHAT_MESSAGE_CONTENT_MAX_LENGTH + 1));
+
+    expect(send).not.toHaveBeenCalled();
+    const state = controller.getState();
+    expect(state.messages).toHaveLength(0);
+    expect(state.status).toBe('idle');
+    expect(state.error).not.toBeNull();
+  });
+
+  it('refuses to submit once the conversation reaches its maximum length', async () => {
+    const send = vi.fn(() => Promise.resolve({ content: 'ok' }));
+    const controller = new ConversationController({
+      provider: { id: 'counting', send },
+      ...makeDeps(),
+    });
+
+    const rounds = CHAT_CONVERSATION_MAX_MESSAGES / 2;
+    for (let i = 0; i < rounds; i += 1) {
+      await controller.submit(`message ${String(i)}`);
+    }
+
+    expect(controller.getState().messages).toHaveLength(CHAT_CONVERSATION_MAX_MESSAGES);
+    expect(send).toHaveBeenCalledTimes(rounds);
+
+    await controller.submit('one too many');
+
+    expect(controller.getState().messages).toHaveLength(CHAT_CONVERSATION_MAX_MESSAGES);
+    expect(controller.getState().error?.message).toMatch(/maximum length/i);
+    // The bound is enforced before the provider is ever contacted again.
+    expect(send).toHaveBeenCalledTimes(rounds);
+  }, 20_000);
+
+  it('stops delivering state updates to subscribers after dispose', async () => {
+    const { provider, resolve } = deferredProvider();
+    const controller = new ConversationController({ provider, ...makeDeps() });
+    const listener = vi.fn();
+    controller.subscribe(listener);
+
+    const submitPromise = controller.submit('hello');
+    listener.mockClear();
+
+    controller.dispose();
+    resolve({ content: 'too late' });
+    await submitPromise.catch(() => undefined);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/unit/shared/chat.schema.test.ts b/tests/unit/shared/chat.schema.test.ts
new file mode 100644
index 0000000..6a9de4d
--- /dev/null
+++ b/tests/unit/shared/chat.schema.test.ts
@@ -0,0 +1,176 @@
+import { describe, expect, it } from 'vitest';
+
+import { CHAT_MESSAGE_CONTENT_MAX_LENGTH, CHAT_MESSAGE_ROLES } from '../../../src/shared/constants';
+import { chatMessageSchema, createChatMessage } from '../../../src/shared/schemas/chat.schema';
+
+const VALID_ID = '11111111-1111-4111-8111-111111111111';
+const VALID_CREATED_AT = '2026-01-01T00:00:00.000Z';
+
+function validMessage(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: VALID_ID,
+    role: 'user',
+    content: 'Hello there',
+    createdAt: VALID_CREATED_AT,
+    ...overrides,
+  };
+}
+
+describe('chatMessageSchema', () => {
+  it('accepts a well-formed message', () => {
+    const result = chatMessageSchema.safeParse(validMessage());
+    expect(result.success).toBe(true);
+  });
+
+  it.each(CHAT_MESSAGE_ROLES)('accepts every declared role: %s', (role) => {
+    const result = chatMessageSchema.safeParse(validMessage({ role }));
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects an unrecognised role', () => {
+    const result = chatMessageSchema.safeParse(validMessage({ role: 'admin' }));
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an unknown top-level field', () => {
+    const result = chatMessageSchema.safeParse(validMessage({ apiKey: 'sk-not-real-test-only' }));
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a non-UUID id', () => {
+    const result = chatMessageSchema.safeParse(validMessage({ id: 'not-a-uuid' }));
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a createdAt with a UTC offset instead of Z', () => {
+    const result = chatMessageSchema.safeParse(
+      validMessage({ createdAt: '2026-01-01T00:00:00.000+02:00' }),
+    );
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an empty content string', () => {
+    const result = chatMessageSchema.safeParse(validMessage({ content: '' }));
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts content at exactly the maximum length', () => {
+    const content = 'a'.repeat(CHAT_MESSAGE_CONTENT_MAX_LENGTH);
+    const result = chatMessageSchema.safeParse(validMessage({ content }));
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects content one character past the maximum length', () => {
+    const content = 'a'.repeat(CHAT_MESSAGE_CONTENT_MAX_LENGTH + 1);
+    const result = chatMessageSchema.safeParse(validMessage({ content }));
+    expect(result.success).toBe(false);
+  });
+
+  it('allows tab, newline and carriage return inside content', () => {
+    const result = chatMessageSchema.safeParse(
+      validMessage({ content: 'line one\nline two\tindented\r\nline three' }),
+    );
+    expect(result.success).toBe(true);
+  });
+
+  it.each([
+    ['NUL', '\x00'],
+    ['BEL', '\x07'],
+    ['ESC', '\x1B'],
+    ['DEL', '\x7F'],
+  ])('rejects content containing a %s control character', (_label, char) => {
+    const result = chatMessageSchema.safeParse(validMessage({ content: `hello${char}world` }));
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects content containing a bidirectional override character', () => {
+    const result = chatMessageSchema.safeParse(validMessage({ content: 'safe looking ‮text' }));
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts an optional status of "complete" or "error"', () => {
+    expect(chatMessageSchema.safeParse(validMessage({ status: 'complete' })).success).toBe(true);
+    expect(chatMessageSchema.safeParse(validMessage({ status: 'error' })).success).toBe(true);
+  });
+
+  it('rejects an unrecognised status', () => {
+    const result = chatMessageSchema.safeParse(validMessage({ status: 'streaming' }));
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts a message with no status and no metadata at all', () => {
+    const result = chatMessageSchema.safeParse(validMessage());
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.status).toBeUndefined();
+      expect(result.data.metadata).toBeUndefined();
+    }
+  });
+
+  it('accepts safe, bounded metadata', () => {
+    const result = chatMessageSchema.safeParse(
+      validMessage({ metadata: { source: 'mock', turn: 1 } }),
+    );
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects metadata carrying a secret-looking field with a real-looking value', () => {
+    const result = chatMessageSchema.safeParse(
+      validMessage({ metadata: { apiKey: 'sk-not-real-test-only' } }),
+    );
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts metadata carrying a secret-looking field only when already redacted', () => {
+    const result = chatMessageSchema.safeParse(
+      validMessage({ metadata: { apiKey: '[REDACTED]' } }),
+    );
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects metadata containing a function or other non-JSON value', () => {
+    const result = chatMessageSchema.safeParse(
+      validMessage({ metadata: { handler: () => 'not json safe' } }),
+    );
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('createChatMessage', () => {
+  it('returns a validated message for valid input', () => {
+    const message = createChatMessage({
+      id: VALID_ID,
+      role: 'assistant',
+      content: 'a validated reply',
+      createdAt: VALID_CREATED_AT,
+    });
+    expect(message).toEqual({
+      id: VALID_ID,
+      role: 'assistant',
+      content: 'a validated reply',
+      createdAt: VALID_CREATED_AT,
+    });
+  });
+
+  it('throws for content that fails validation, rather than returning a partial message', () => {
+    expect(() =>
+      createChatMessage({
+        id: VALID_ID,
+        role: 'user',
+        content: '',
+        createdAt: VALID_CREATED_AT,
+      }),
+    ).toThrow();
+  });
+
+  it('throws for an oversized message', () => {
+    expect(() =>
+      createChatMessage({
+        id: VALID_ID,
+        role: 'user',
+        content: 'a'.repeat(CHAT_MESSAGE_CONTENT_MAX_LENGTH + 1),
+        createdAt: VALID_CREATED_AT,
+      }),
+    ).toThrow();
+  });
+});
diff --git a/tests/unit/shared/mock-provider.test.ts b/tests/unit/shared/mock-provider.test.ts
new file mode 100644
index 0000000..0975241
--- /dev/null
+++ b/tests/unit/shared/mock-provider.test.ts
@@ -0,0 +1,151 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { ChatProviderError } from '../../../src/shared/chat/provider';
+import { createMockChatProvider } from '../../../src/shared/chat/mock-provider';
+import { createChatMessage } from '../../../src/shared/schemas/chat.schema';
+import {
+  MOCK_CHAT_PROVIDER_FAILURE_TRIGGER,
+  MOCK_CHAT_PROVIDER_ID,
+} from '../../../src/shared/constants';
+
+const CREATED_AT = '2026-01-01T00:00:00.000Z';
+
+function userMessage(content: string, id = '11111111-1111-4111-8111-111111111111') {
+  return createChatMessage({ id, role: 'user', content, createdAt: CREATED_AT });
+}
+
+describe('createMockChatProvider', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('has the documented provider id', () => {
+    const provider = createMockChatProvider({ delayMs: 0 });
+    expect(provider.id).toBe(MOCK_CHAT_PROVIDER_ID);
+  });
+
+  it('is deterministic: the same conversation produces the same reply', async () => {
+    const provider = createMockChatProvider({ delayMs: 0 });
+    const request = { messages: [userMessage('hello there')] };
+
+    const first = await provider.send(request);
+    const second = await provider.send(request);
+
+    expect(first).toEqual(second);
+  });
+
+  it('marks the response clearly as a mock reply', async () => {
+    const provider = createMockChatProvider({ delayMs: 0 });
+    const result = await provider.send({ messages: [userMessage('hello')] });
+    expect(result.content).toContain('[Mock provider]');
+  });
+
+  it('echoes the latest user message content into the reply', async () => {
+    const provider = createMockChatProvider({ delayMs: 0 });
+    const result = await provider.send({ messages: [userMessage('a very specific phrase')] });
+    expect(result.content).toContain('a very specific phrase');
+  });
+
+  it('truncates a very long echoed message rather than reproducing it in full', async () => {
+    const provider = createMockChatProvider({ delayMs: 0 });
+    const longContent = 'x'.repeat(500);
+    const result = await provider.send({ messages: [userMessage(longContent)] });
+    expect(result.content.length).toBeLessThan(longContent.length);
+  });
+
+  it('handles a conversation with no user message yet without throwing', async () => {
+    const provider = createMockChatProvider({ delayMs: 0 });
+    const result = await provider.send({ messages: [] });
+    expect(result.content).toContain('[Mock provider]');
+  });
+
+  it('never returns oversized content', async () => {
+    const provider = createMockChatProvider({ delayMs: 0 });
+    const result = await provider.send({ messages: [userMessage('x'.repeat(7999))] });
+    expect(result.content.length).toBeLessThanOrEqual(8000);
+  });
+
+  it('resolves only after the configured delay', async () => {
+    vi.useFakeTimers();
+    try {
+      const provider = createMockChatProvider({ delayMs: 1000 });
+      let resolved = false;
+      const promise = provider.send({ messages: [userMessage('hi')] }).then((result) => {
+        resolved = true;
+        return result;
+      });
+
+      await vi.advanceTimersByTimeAsync(500);
+      expect(resolved).toBe(false);
+
+      await vi.advanceTimersByTimeAsync(600);
+      expect(resolved).toBe(true);
+      await promise;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('rejects deterministically when the message content is the documented failure trigger', async () => {
+    const provider = createMockChatProvider({ delayMs: 0 });
+    await expect(
+      provider.send({ messages: [userMessage(MOCK_CHAT_PROVIDER_FAILURE_TRIGGER)] }),
+    ).rejects.toBeInstanceOf(ChatProviderError);
+  });
+
+  it('reports PROVIDER_REQUEST_FAILED for the deliberate failure trigger', async () => {
+    const provider = createMockChatProvider({ delayMs: 0 });
+    await expect(
+      provider.send({ messages: [userMessage(MOCK_CHAT_PROVIDER_FAILURE_TRIGGER)] }),
+    ).rejects.toMatchObject({ code: 'PROVIDER_REQUEST_FAILED' });
+  });
+
+  it('rejects immediately with PROVIDER_ABORTED when the signal is already aborted', async () => {
+    const provider = createMockChatProvider({ delayMs: 1000 });
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(
+      provider.send({ messages: [userMessage('hi')] }, { signal: controller.signal }),
+    ).rejects.toMatchObject({ code: 'PROVIDER_ABORTED' });
+  });
+
+  it('rejects with PROVIDER_ABORTED when the signal fires mid-delay', async () => {
+    vi.useFakeTimers();
+    try {
+      const provider = createMockChatProvider({ delayMs: 1000 });
+      const controller = new AbortController();
+
+      const promise = provider.send(
+        { messages: [userMessage('hi')] },
+        { signal: controller.signal },
+      );
+      const assertion = expect(promise).rejects.toMatchObject({ code: 'PROVIDER_ABORTED' });
+
+      await vi.advanceTimersByTimeAsync(200);
+      controller.abort();
+
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('never calls the global fetch function', async () => {
+    if (typeof globalThis.fetch !== 'function') {
+      // Nothing to spy on in this runtime; the eslint boundary on
+      // src/shared already forbids referencing `fetch` at all, which is the
+      // stronger, always-on guarantee. See eslint.config.js.
+      return;
+    }
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    const provider = createMockChatProvider({ delayMs: 0 });
+
+    await provider.send({ messages: [userMessage('hello')] });
+    await provider
+      .send({ messages: [userMessage(MOCK_CHAT_PROVIDER_FAILURE_TRIGGER)] })
+      .catch(() => undefined);
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

From 44771080f0878d713df43acb01af5fa3f5806279 Mon Sep 17 00:00:00 2001
From: Texas-walker15 <noahwalker715@gmail.com>
Date: Thu, 3 Sep 2026 11:43:16 +0200
Subject: [PATCH 2/2] feat: add phase 2 provider adapter foundation

---
 README.md                                     |  73 ++--
 docs/phase-2-chat-architecture.md             |   8 +-
 docs/phase-2-provider-architecture.md         | 327 ++++++++++++++++++
 src/renderer/App.tsx                          |   3 +-
 src/renderer/chat/Chat.tsx                    |  37 +-
 src/renderer/chat/conversation-controller.ts  |  48 ++-
 src/renderer/chat/useActiveChatProvider.ts    |  46 +++
 src/renderer/chat/useConversation.ts          |  28 +-
 src/renderer/styles.css                       |   5 +
 src/shared/chat/index.ts                      |  20 +-
 src/shared/chat/provider.ts                   |  52 ++-
 src/shared/chat/registry.ts                   | 138 ++++++++
 src/shared/chat/timeout.ts                    | 101 ++++++
 src/shared/schemas/chat.schema.ts             |  61 +++-
 src/shared/schemas/index.ts                   |  15 +-
 .../renderer/conversation-controller.test.ts  | 106 ++++++
 tests/unit/shared/chat-boundary-scan.test.ts  |  92 +++++
 .../unit/shared/chat-provider-schema.test.ts  | 121 +++++++
 tests/unit/shared/chat-registry.test.ts       | 133 +++++++
 tests/unit/shared/provider-timeout.test.ts    | 143 ++++++++
 20 files changed, 1478 insertions(+), 79 deletions(-)
 create mode 100644 docs/phase-2-provider-architecture.md
 create mode 100644 src/renderer/chat/useActiveChatProvider.ts
 create mode 100644 src/shared/chat/registry.ts
 create mode 100644 src/shared/chat/timeout.ts
 create mode 100644 tests/unit/shared/chat-boundary-scan.test.ts
 create mode 100644 tests/unit/shared/chat-provider-schema.test.ts
 create mode 100644 tests/unit/shared/chat-registry.test.ts
 create mode 100644 tests/unit/shared/provider-timeout.test.ts

diff --git a/README.md b/README.md
index c02dc60..832579b 100644
--- a/README.md
+++ b/README.md
@@ -3,25 +3,33 @@
 A local-first, permission-controlled desktop assistant for Windows. The
 assistant is named **JARVIS** by default; the product is **Local Agent**.
 
-> **Status: Phase 1 complete. Phase 2, Milestone 1 (chat foundation) in progress.**
+> **Status: Phase 1 complete. Phase 2, Milestone 2 (provider-adapter
+> foundation) in progress.**
 > Phase 1 delivered the hardened desktop shell, non-secret settings storage,
 > an audit-log foundation, the permission-policy runtime, persisted
 > emergency-stop state, first-run onboarding, an encrypted secret store, and
-> CI. Phase 2 Milestone 1 adds a **mock-only chat foundation**: a validated
+> CI. Phase 2 Milestone 1 added a **mock-only chat foundation**: a validated
 > chat message and conversation model, a provider-independent
 > `ChatProvider` interface, a deterministic mock provider, and a chat surface
-> in the renderer with empty, loading, error and retry states. **No real
-> model provider is called. No network request is made anywhere in this
-> milestone** — the mock provider lives entirely inside `src/shared`, where
-> the same lint boundary that blocks Electron and Node access also blocks
-> `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource` as globals. Chat
-> requires **no new IPC channel**: it never calls `window.localAgent`, so
-> nothing a chat message contains can reach a privileged API, a file, or the
+> in the renderer with empty, loading, error and retry states. Milestone 2
+> adds the **provider-adapter foundation** on top of that: bounded provider
+> request/response schemas, a normalized five-category error vocabulary, an
+> approved-provider registry that **fails closed for every one of the four
+> approved identifiers** (`none`, `glm`, `openai-compatible`, `ollama` —
+> none of them makes a network request), a composable timeout decorator, and
+> safe provider-status display. **No real model provider is called. No
+> network request is made anywhere in this milestone** — the whole provider
+> layer lives inside `src/shared`, where the same lint boundary that blocks
+> Electron and Node access also blocks `fetch`, `XMLHttpRequest`,
+> `WebSocket` and `EventSource` as globals. Chat still requires **no new IPC
+> channel**: it never calls `window.localAgent`, so nothing a chat message or
+> a provider response contains can reach a privileged API, a file, or the
 > permission engine. See
-> [docs/phase-2-chat-architecture.md](docs/phase-2-chat-architecture.md) for
-> the full design and for what remains explicitly deferred (real providers,
-> tool/action execution from model output, memory, and everything else Phase
-> 2 has not reached yet).
+> [docs/phase-2-chat-architecture.md](docs/phase-2-chat-architecture.md) and
+> [docs/phase-2-provider-architecture.md](docs/phase-2-provider-architecture.md)
+> for the full design and for what remains explicitly deferred (real
+> providers, tool/action execution from model output, memory, and everything
+> else Phase 2 has not reached yet).
 
 All rights reserved. No licence has been granted for this project.
 
@@ -89,17 +97,21 @@ postponed.
 - `hasApiKey`, the only secret-related value the interface ever sees, is
   reconciled against the encrypted store on every read and write — the store
   is the source of truth, never the cached flag.
-- Chat (Phase 2, Milestone 1) makes no network request and adds no IPC
-  channel. The mock provider lives under `src/shared/chat`, where the same
-  lint boundary that keeps `src/shared` free of Electron and Node access also
-  blocks `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource` as globals.
-  Assistant text is rendered as plain JSX text, never as HTML, and is never
-  treated as authorization for anything — there is no action for it to
-  authorize, since chat never calls `window.localAgent`.
+- Chat and its provider layer (Phase 2, Milestones 1–2) make no network
+  request and add no IPC channel. Every provider file lives under
+  `src/shared/chat`, where the same lint boundary that keeps `src/shared`
+  free of Electron and Node access also blocks `fetch`, `XMLHttpRequest`,
+  `WebSocket` and `EventSource` as globals. The provider registry fails
+  closed for every one of the four approved identifiers — none of them, not
+  even `none`, ever resolves a `send()` call. Assistant text is rendered as
+  plain JSX text, never as HTML, and is never treated as authorization for
+  anything — there is no action for it to authorize, since chat never calls
+  `window.localAgent`.
 
 Full detail, including known limitations, is in
 [docs/security-model.md](docs/security-model.md); the chat-specific design is
-in [docs/phase-2-chat-architecture.md](docs/phase-2-chat-architecture.md).
+in [docs/phase-2-chat-architecture.md](docs/phase-2-chat-architecture.md) and
+[docs/phase-2-provider-architecture.md](docs/phase-2-provider-architecture.md).
 
 ## Where your data lives
 
@@ -165,10 +177,11 @@ platform this project does not ship on.
 
 ```
 src/shared/     Pure schemas, types and constants, plus chat/ (the
-                provider-independent ChatProvider interface and the
-                deterministic mock provider). No I/O, no Electron, no
-                network — safe to import from any process, including the
-                renderer.
+                provider-independent ChatProvider interface, the
+                deterministic mock provider, the approved-provider registry
+                with its fail-closed adapters, and the composable timeout
+                decorator). No I/O, no Electron, no network — safe to import
+                from any process, including the renderer.
 src/main/       Privileged Electron main process. Owns the BrowserWindow,
                 the Content-Security-Policy, navigation/window-open/webview
                 hardening, non-secret settings storage (paths.ts,
@@ -188,10 +201,12 @@ src/preload/    The single contextBridge. Exposes a narrow, explicitly
                 sandboxed preload cannot require() local modules at runtime.
 src/renderer/   React interface: App.tsx gates on onboardingCompleted,
                 Onboarding.tsx is the first-run form, chat/ is the Phase 2
-                chat surface (Chat.tsx, useConversation.ts and the
-                framework-independent conversation-controller.ts). No Node,
-                no Electron, no filesystem access — only the bridge at
-                window.localAgent, which chat never calls.
+                chat surface (Chat.tsx, useConversation.ts, the
+                framework-independent conversation-controller.ts, and
+                useActiveChatProvider.ts — the one place that resolves which
+                provider is active). No Node, no Electron, no filesystem
+                access — only the bridge at window.localAgent, which chat
+                never calls.
 tests/unit/     Unit tests. `npm test`.
 tests/e2e/      Playwright + Electron smoke test against the built app.
                 `npm run test:e2e`.
diff --git a/docs/phase-2-chat-architecture.md b/docs/phase-2-chat-architecture.md
index 952ed13..49ebaa7 100644
--- a/docs/phase-2-chat-architecture.md
+++ b/docs/phase-2-chat-architecture.md
@@ -5,6 +5,12 @@
 > tested; everything marked **[deferred]** does not exist yet and this
 > milestone does not lay groundwork that quietly enables it. Nothing here
 > makes a network request, and nothing here can trigger a privileged action.
+> Milestone 2 (see
+> [docs/phase-2-provider-architecture.md](phase-2-provider-architecture.md))
+> adds the provider registry, request/response schemas, a timeout decorator,
+> and provider-status display on top of this same foundation — this document
+> is kept as the record of what Milestone 1 built and is not rewritten to
+> describe Milestone 2's additions.
 
 ---
 
@@ -107,7 +113,7 @@ interface ConversationState {
 
 `src/renderer/chat/Chat.tsx`, mounted from `App.tsx`'s `'ready'` phase, replacing the previous static welcome screen with the assistant's name and status line as a compact header above the chat surface.
 
-- **Empty state** — a friendly prompt when no messages exist yet, explicitly naming the mock provider.
+- **Empty state** — a friendly prompt when no messages exist yet. (Milestone 2 moved the "which provider is actually answering" text out of this prompt and into its own status line — see `docs/phase-2-provider-architecture.md`.)
 - **Message list** (`role="log"`, `aria-live="polite"`) — each message a bubble labelled by role.
 - **Loading state** — an `aria-live` "…is thinking" line while `status === 'awaiting-response'`; the composer is disabled for the same duration, which is the actual duplicate-submission prevention the user sees (the controller enforces it structurally regardless).
 - **Error state** (`role="alert"`) with a **Retry** button, shown only when `state.error` is set.
diff --git a/docs/phase-2-provider-architecture.md b/docs/phase-2-provider-architecture.md
new file mode 100644
index 0000000..aceed85
--- /dev/null
+++ b/docs/phase-2-provider-architecture.md
@@ -0,0 +1,327 @@
+# Phase 2 provider architecture
+
+> **Current state.** Phase 2, Milestone 2 implements the **provider-adapter
+> foundation**: a registry, bounded request/response schemas, an expanded
+> normalized error vocabulary, a composable timeout decorator, and explicit
+> provider selection with safe status display. It builds directly on
+> [docs/phase-2-chat-architecture.md](phase-2-chat-architecture.md)'s message
+> model and `ConversationController`, both unchanged in shape. **No real
+> provider is implemented. No network request is made anywhere in this
+> milestone, in tests or in normal execution.**
+
+---
+
+## Summary
+
+| Property                                                            | State                                                                            |
+| ------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Provider request/response schemas                                   | **[implemented]** — `chatProviderRequestSchema`, `chatProviderResultSchema`      |
+| Provider capability metadata                                        | **[implemented]** — `getChatProviderCapabilities`                                |
+| Approved-provider registry                                          | **[implemented]** — `createChatProviderForSelection`, fails closed               |
+| Timeout decorator                                                   | **[implemented]** — `withProviderTimeout`, composable, provider-neutral          |
+| Real GLM / OpenAI-compatible / Ollama network adapters              | **[deferred]** — no HTTP client, no SDK, no network call exists in this codebase |
+| API-key retrieval for a provider call                               | **[deferred]** — no provider adapter imports `main/secrets.ts` or settings       |
+| Model output treated as authorization                               | **Never.** No mechanism exists by which it could be                              |
+| Disapproved identifiers (`anthropic`, `openai`, `claude`, `gemini`) | **Absent.** Not referenced anywhere in source (verified by scan — see Testing)   |
+
+---
+
+## Why `none` and every real identifier still power a working chat
+
+This is the one genuinely ambiguous design decision in this milestone, so it
+is stated explicitly rather than left implicit.
+
+The task's registry requirement reads: _"`none` must always produce a safe
+'provider unavailable/not configured' result."_ Taken completely literally,
+asking the registry to actually `send()` through `none` — or through `glm`,
+`openai-compatible`, or `ollama`, none of which has a real implementation
+either — **must** fail closed. `createChatProviderForSelection` does exactly
+that for all four approved identifiers: every one of them rejects with
+`ChatProviderError('PROVIDER_UNAVAILABLE', …)`, unconditionally, verified by
+`tests/unit/shared/chat-registry.test.ts`.
+
+Separately, the milestone's scope explicitly includes "mock provider
+integration with the existing chat system" and requires the chat UI to
+"show mock/not-configured state clearly" — implying chat keeps functioning,
+not that it goes inert for the default, unconfigured case every fresh
+install starts in.
+
+**Resolution:** these are two different questions, answered by two different
+functions, deliberately kept apart:
+
+- `createChatProviderForSelection(id)` (`src/shared/chat/registry.ts`)
+  answers _"what happens if you literally invoke the provider the user
+  selected?"_ — and fails closed for all four, honestly, with no silent
+  substitution.
+- `useActiveChatProvider` (`src/renderer/chat/useActiveChatProvider.ts`)
+  answers _"what does the chat UI actually talk to right now?"_ — and, since
+  no real adapter exists for any selection in this phase, that is always the
+  deterministic mock, paired with `describeChatProviderStatus(selected)`'s
+  honest, safe status text ("GLM is selected but not connected yet. Chat is
+  running on the local mock provider.").
+
+Nothing conflates the two: the mock's own replies are always prefixed
+`[Mock provider]` (Milestone 1), and the status line never claims a
+connection that does not exist. A future milestone adding a real adapter
+changes `useActiveChatProvider` to prefer it once `getChatProviderCapabilities(id).implemented`
+is `true`, and changes nothing about `ConversationController` or `Chat.tsx`.
+
+If this reading turns out not to match what was intended, the fix is
+narrow: change `useActiveChatProvider`'s single call to
+`createChatProviderForSelection` instead of always constructing the mock. That
+one function is the entire seam.
+
+---
+
+## Provider request/response schemas
+
+`src/shared/schemas/chat.schema.ts` adds two schemas, validated at the exact
+point a conversation crosses into a provider and the exact point a raw
+result crosses back — a stricter, independent boundary layered on top of
+Milestone 1's per-message validation, not a replacement for it:
+
+- **`chatProviderRequestSchema`** — `{ messages: ChatMessage[] }`, the array
+  bounded to `CHAT_CONVERSATION_MAX_MESSAGES`. Before this milestone, that
+  bound was enforced only by `ConversationController.submit()`'s own runtime
+  `if` check; it is now also a schema-level invariant re-checked at the
+  provider boundary. `strictObject` rejects any extra field (a stray
+  `apiKey`, say) outright.
+- **`chatProviderResultSchema`** — `{ content: string }`, using the same
+  bounded, control-character- and bidi-safe string schema a message's own
+  `content` uses (factored into a shared `chatContentSchema`). `strictObject`
+  means a provider cannot smuggle extra data — a confidence score, a raw
+  upstream error object — past this boundary; only `content` is accepted.
+
+`ConversationController.requestAssistantReply` runs both: the request is
+validated immediately before `provider.send()` is called, and the raw result
+is validated immediately after it resolves, before any of it is trusted
+enough to become a `ChatMessage`. Either failing is treated exactly like any
+other provider failure — caught, turned into safe conversation-level error
+state, prior messages untouched.
+
+---
+
+## Normalized provider errors
+
+`src/shared/chat/provider.ts`'s `CHAT_PROVIDER_ERROR_CODES` now covers the
+five categories the milestone requires be distinguishable:
+
+| Code                             | Meaning                                                             | Produced by                                                                 |
+| -------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `PROVIDER_UNAVAILABLE`           | Not configured, or configured but not implemented yet               | Every entry in the registry (`registry.ts`)                                 |
+| `PROVIDER_INVALID_CONFIGURATION` | Configured but unusable (e.g. a real HTTP adapter with no base URL) | Declared for a future real adapter; nothing constructs it in this milestone |
+| `PROVIDER_TIMEOUT`               | Did not settle within a caller's configured budget                  | `withProviderTimeout` (`timeout.ts`)                                        |
+| `PROVIDER_ABORTED`               | Cancelled via `AbortSignal`                                         | The mock provider; `withProviderTimeout` forwarding an external abort       |
+| `PROVIDER_REQUEST_FAILED`        | A generic failure fitting none of the above                         | The mock provider's deliberate failure trigger                              |
+
+Every code is a `ChatProviderError` with a stable `.code` a caller can branch
+on and a safe, fixed `.message` — never a raw provider error, a URL, a
+header, or a credential. `ConversationController`'s `describeProviderFailure`
+still never forwards a raw `Error.message` to the UI regardless of code,
+matching Milestone 1's rule that a thrown error is exactly as untrusted as a
+returned reply.
+
+---
+
+## Provider capability metadata
+
+`getChatProviderCapabilities(id)` (`registry.ts`) returns, for each of the
+four approved identifiers:
+
+```ts
+interface ChatProviderCapabilities {
+  readonly id: ModelProvider;
+  readonly label: string; // safe to show in the UI
+  readonly requiresApiKey: boolean; // derived from PROVIDERS_REQUIRING_API_KEY
+  readonly implemented: boolean; // always false in Phase 2
+}
+```
+
+`requiresApiKey` is **derived** from the same `PROVIDERS_REQUIRING_API_KEY`
+constant `main/settings-service.ts`'s `hasApiKey` reconciliation already
+uses, not a second hand-maintained table that could silently drift from it.
+Nothing in this structure, or in `ChatProviderStatus`'s `summary` text built
+from it, ever carries a key, a header, a URL, or `hasApiKey` itself — every
+field is either a fixed label or a boolean, verified by
+`tests/unit/shared/chat-registry.test.ts`.
+
+---
+
+## Timeout decorator
+
+`src/shared/chat/timeout.ts`'s `withProviderTimeout(provider, timeoutMs)`
+wraps any `ChatProvider` so a request that does not settle within
+`timeoutMs` is aborted and rejected with `PROVIDER_TIMEOUT`, instead of
+hanging indefinitely. Composable and provider-neutral — it will wrap a real
+adapter identically to the mock, once one exists, without either
+implementation writing its own timer.
+
+Design notes:
+
+- Timeout is **not** a field on `ChatProviderRequestOptions`. Every provider
+  already accepts a `signal`; a caller wanting a timeout composes this
+  decorator once rather than every adapter reimplementing a timer and every
+  call site remembering to pass a budget.
+- A single fresh `AbortController` is created per call and passed to the
+  wrapped provider — never the caller's own signal directly — so the
+  decorator can distinguish its own timer firing from an external
+  cancellation via `AbortSignal.abort(reason)`'s `reason`, forwarding the
+  external signal's `reason` (or nothing) when relaying an outside abort, and
+  a private `Symbol` sentinel for its own timer.
+- **An already-aborted external signal is rejected immediately**, before the
+  wrapped provider's `send()` is ever called — deliberately not relying on
+  every future provider implementation correctly checking `signal.aborted`
+  up front the way the mock happens to (see `mock-provider.ts`'s `delay()`).
+  This was a real gap found while testing: an early version of the decorator
+  depended on the wrapped provider's own abort-event handling to notice a
+  pre-aborted signal, which a test provider that only listened for the
+  `'abort'` _event_ (rather than also checking `.aborted` synchronously)
+  never fired for, hanging the test. Fixed by short-circuiting in the
+  decorator itself, which is correct regardless of how any given wrapped
+  provider behaves.
+
+Not wired into `useActiveChatProvider`'s default path in this milestone —
+the mock resolves in well under a second and has no need of one. The
+decorator exists, is real, and is fully tested
+(`tests/unit/shared/provider-timeout.test.ts`), ready for whichever future
+adapter needs it.
+
+---
+
+## Provider registry and selection
+
+`src/shared/chat/registry.ts`:
+
+- **`getChatProviderCapabilities(id)`** — safe metadata, above.
+- **`describeChatProviderStatus(selected)`** — `not-configured` for `none`,
+  `not-implemented` for the other three, each with a fixed, safe summary
+  string. Never takes free-text input, so its output space is exactly four
+  known, reviewed strings.
+- **`createChatProviderForSelection(id)`** — fails closed for all four
+  approved identifiers and for anything outside `MODEL_PROVIDERS`
+  (`anthropic`, `openai`, `claude`, `gemini` included, should one ever reach
+  this function through an untrusted boundary that bypassed
+  `settingsSchema`). No branch here can resolve successfully; every path
+  returns a `ChatProvider` whose `send()` always rejects.
+
+`src/renderer/chat/useActiveChatProvider.ts` is the one place chat decides
+which adapter is actually active — see
+["Why `none` and every real identifier still power a working chat"](#why-none-and-every-real-identifier-still-power-a-working-chat)
+above. The mock instance is created once (`useRef`, stable for the
+component's lifetime) independent of `status`, which is recomputed from
+`modelProvider.provider` on every render — so a settings change alone never
+resets the conversation.
+
+---
+
+## Chat integration
+
+- **Chat uses the provider interface, not a direct mock import.** `Chat.tsx`
+  no longer imports `createMockChatProvider` at all; it calls
+  `useActiveChatProvider(modelProvider)` and receives back a `ChatProvider`
+  plus a `ChatProviderStatus`.
+- **Provider selection is explicit.** One named function
+  (`useActiveChatProvider`) is the single decision point, not a hardcoded
+  call buried inside a component.
+- **Switching provider does not lose conversation state — genuinely, not by
+  accident.** Before this milestone, `useConversation`'s controller was
+  recreated (`useMemo(() => new ConversationController(...), [provider])`)
+  whenever the `provider` reference changed, which would have silently
+  discarded the conversation the first time a provider identity actually
+  changed at runtime. `ConversationController` now has a `setProvider(provider)`
+  method — reassigns the active provider, aborts any in-flight request
+  against the old one, returns `status` to `'idle'`, and **touches no
+  message** — and `useConversation` keeps one controller for the component's
+  whole lifetime (`useRef`, not `useMemo`, since only `useRef` is documented
+  as a correctness guarantee rather than a performance hint), forwarding a
+  new `provider` prop into `setProvider` instead of discarding the
+  controller. Covered by dedicated tests in
+  `tests/unit/renderer/conversation-controller.test.ts`'s `setProvider`
+  suite.
+- **Pending requests are handled safely; stale responses cannot overwrite
+  newer state.** Each request already got its own `AbortController` in
+  Milestone 1; `setProvider` reuses that same mechanism — aborting the
+  in-flight controller means `requestAssistantReply`'s
+  `if (controller.signal.aborted) return;` guard discards whatever a
+  now-superseded provider eventually answers, even if that provider's fake
+  implementation ignores its own signal entirely (verified by a test using
+  exactly such an implementation: the stale response, resolved deliberately
+  late, never appears in the conversation, including after a different,
+  successful exchange with the new provider has already completed).
+- **Assistant output remains text-only and untrusted**, unchanged from
+  Milestone 1 — see that document's UI section.
+
+---
+
+## UI: provider status
+
+`Chat.tsx` renders `status.summary` as a fixed line above the transcript —
+built entirely from `describeChatProviderStatus`'s four known templates,
+never from settings input directly. It never displays an API key, a header,
+a URL, or `hasApiKey`; `Chat.tsx` does not even receive a value that could
+contain one — `ModelProviderSettings` carries only `provider`, `model`,
+`baseUrl` and the boolean `hasApiKey`, and only `provider` is read here.
+
+---
+
+## Security boundary
+
+Everything Milestone 1 established holds unchanged — see
+`phase-2-chat-architecture.md`'s own Security boundary section — plus, new in
+this milestone:
+
+- **The registry fails closed for every approved identifier**, verified by
+  `tests/unit/shared/chat-registry.test.ts`: `send()` never resolves for
+  `none`, `glm`, `openai-compatible`, or `ollama`, and never for an
+  identifier outside that set either.
+- **No disapproved identifier is referenced anywhere in source.**
+  `anthropic`, `openai`, `claude` and `gemini` do not appear in
+  `src/shared/chat/registry.ts` or anywhere else added this milestone.
+- **`src/main`, `src/preload/index.ts`, `eslint.config.js`, `package.json`
+  and `package-lock.json` all have zero diff in this milestone** — no new
+  IPC channel, no new dependency, no privileged code touched. Confirmed by
+  `git diff --stat` and by the unmodified e2e bridge-shape test still
+  passing.
+- **A source-scan test** (`tests/unit/shared/chat-boundary-scan.test.ts`)
+  reads the actual, comment-stripped source of every file under
+  `src/shared/chat/` and `src/renderer/chat/` and asserts none of them
+  reference `ipcRenderer`, `window.localAgent`, `electron`, `child_process`,
+  `node:fs`, `fetch(`, `XMLHttpRequest`, `WebSocket`, `eval(`,
+  `new Function(`, `dangerouslySetInnerHTML`, or `ActionProposal` — a
+  regression guard against a future contributor introducing any of these,
+  independent of `eslint.config.js` staying correctly configured.
+
+---
+
+## Testing
+
+| Area                                                                                                                                                                        | File                                                                        |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Provider request/response schema validation, bounds, secret rejection                                                                                                       | `tests/unit/shared/chat-provider-schema.test.ts`                            |
+| Registry: capabilities, status text, fail-closed for every approved and disapproved identifier, no network call                                                             | `tests/unit/shared/chat-registry.test.ts`                                   |
+| Timeout decorator: success, timeout, external abort, pre-aborted signal, no network call                                                                                    | `tests/unit/shared/provider-timeout.test.ts`                                |
+| Source-scan boundary (no privileged API, no network, no unsafe HTML, no action authorization)                                                                               | `tests/unit/shared/chat-boundary-scan.test.ts`                              |
+| Provider switching: preserves state while idle, aborts a stale in-flight request, a late-resolving stale response cannot land, retry stays a no-op without a standing error | `tests/unit/renderer/conversation-controller.test.ts` (`setProvider` suite) |
+
+Same toolchain limitation as Milestone 1: no component-level render test for
+`Chat.tsx` (no React Testing Library / jsdom). `useActiveChatProvider.ts` is
+a thin hook with no branching logic of its own (`describeChatProviderStatus`,
+the function that actually decides what to say, is tested directly and
+extensively), so the gap this leaves is narrow.
+
+---
+
+## What remains deferred
+
+Unchanged from Milestone 1's list, plus the specific items this milestone
+was explicitly told not to add:
+
+- Real network calls of any kind; HTTP clients; provider SDKs
+- API-key retrieval, or any provider adapter reading settings or the secret
+  store
+- Filesystem tools, shell execution, browser automation
+- Model-generated tool execution — there is no tool a model can invoke, and
+  no path from a `ChatProviderResult` to `main/executor.ts`
+- Vector memory, RAG, plugin runtime, telemetry, cloud sync
+- Any relaxation of the approved-identifier list (`anthropic`, `openai`,
+  `claude`, `gemini` remain absent)
diff --git a/src/renderer/App.tsx b/src/renderer/App.tsx
index 2199084..4d4eb02 100644
--- a/src/renderer/App.tsx
+++ b/src/renderer/App.tsx
@@ -66,6 +66,7 @@ export function App() {
   }
 
   const assistantName = settings?.assistant.name ?? 'JARVIS';
+  const modelProvider = settings?.modelProvider ?? fallbackSettings().modelProvider;
 
   return (
     <main className="app-ready">
@@ -77,7 +78,7 @@ export function App() {
         )}
         <p className="status">Main process: {health}</p>
       </header>
-      <Chat assistantName={assistantName} />
+      <Chat assistantName={assistantName} modelProvider={modelProvider} />
     </main>
   );
 }
diff --git a/src/renderer/chat/Chat.tsx b/src/renderer/chat/Chat.tsx
index 1b60ad7..df9fa49 100644
--- a/src/renderer/chat/Chat.tsx
+++ b/src/renderer/chat/Chat.tsx
@@ -1,11 +1,12 @@
-import { useMemo, useRef, useState, type FormEvent, type KeyboardEvent } from 'react';
+import { useRef, useState, type FormEvent, type KeyboardEvent } from 'react';
 
+import { useActiveChatProvider } from './useActiveChatProvider';
 import { useConversation } from './useConversation';
-import { createMockChatProvider } from '../../shared/chat';
-import type { ChatMessage } from '../../shared/schemas';
+import type { ChatMessage, ModelProviderSettings } from '../../shared/schemas';
 
 interface ChatProps {
   readonly assistantName: string;
+  readonly modelProvider: ModelProviderSettings;
 }
 
 const ROLE_LABELS: Record<ChatMessage['role'], string> = {
@@ -37,17 +38,17 @@ function MessageBubble({ message }: { readonly message: ChatMessage }) {
 }
 
 /**
- * Chat surface for Phase 2, Milestone 1.
+ * Chat surface for Phase 2, Milestones 1–2.
  *
- * Talks only to the deterministic mock provider, entirely inside the
- * renderer — no IPC channel, no call to `window.localAgent`, so nothing
- * typed here can reach a privileged API, a file, the network, or an action
- * the permission engine would need to see. Assistant text is untrusted
- * output: displayed, never executed, never treated as authorization for
- * anything.
+ * Resolves its provider through `useActiveChatProvider` — never imports the
+ * mock directly — entirely inside the renderer: no IPC channel, no call to
+ * `window.localAgent`, so nothing typed here can reach a privileged API, a
+ * file, the network, or an action the permission engine would need to see.
+ * Assistant text is untrusted output: displayed, never executed, never
+ * treated as authorization for anything.
  */
-export function Chat({ assistantName }: ChatProps) {
-  const provider = useMemo(() => createMockChatProvider(), []);
+export function Chat({ assistantName, modelProvider }: ChatProps) {
+  const { provider, status } = useActiveChatProvider(modelProvider);
   const { state, canSubmit, submit, retry } = useConversation(provider);
   const [draft, setDraft] = useState('');
   const inputRef = useRef<HTMLTextAreaElement>(null);
@@ -77,12 +78,16 @@ export function Chat({ assistantName }: ChatProps) {
 
   return (
     <section className="chat" aria-label={`Chat with ${assistantName}`}>
+      {/*
+        Safe provider status only: a fixed label plus a fixed template
+        string built from it (see `describeChatProviderStatus`) — never a
+        key, a header, a URL, or `hasApiKey`. `Chat.tsx` never even receives
+        a value that could contain one.
+      */}
+      <p className="chat__provider-status">{status.summary}</p>
       <div className="chat__transcript" role="log" aria-live="polite" aria-label="Conversation">
         {state.messages.length === 0 ? (
-          <p className="chat__empty">
-            No messages yet. Say hello to {assistantName} — every reply right now comes from a local
-            mock provider, not a real model.
-          </p>
+          <p className="chat__empty">No messages yet. Say hello to {assistantName}.</p>
         ) : (
           state.messages.map((message) => <MessageBubble key={message.id} message={message} />)
         )}
diff --git a/src/renderer/chat/conversation-controller.ts b/src/renderer/chat/conversation-controller.ts
index 8ae0747..87f1b04 100644
--- a/src/renderer/chat/conversation-controller.ts
+++ b/src/renderer/chat/conversation-controller.ts
@@ -23,7 +23,12 @@
  * action — there is no action to authorize here at all.
  */
 
-import { createChatMessage, type ChatMessage } from '../../shared/schemas';
+import {
+  chatProviderRequestSchema,
+  chatProviderResultSchema,
+  createChatMessage,
+  type ChatMessage,
+} from '../../shared/schemas';
 import { CHAT_CONVERSATION_MAX_MESSAGES } from '../../shared/constants';
 import type { ChatProvider } from '../../shared/chat';
 
@@ -87,7 +92,7 @@ function describeProviderFailure(_error: unknown): string {
  * exposes this to a component via `useState`/`useEffect`.
  */
 export class ConversationController {
-  private readonly provider: ChatProvider;
+  private provider: ChatProvider;
   private readonly now: () => string;
   private readonly generateId: () => string;
   private readonly listeners = new Set<ConversationListener>();
@@ -110,6 +115,29 @@ export class ConversationController {
     return this.state.status === 'idle';
   }
 
+  /**
+   * Switches which `ChatProvider` this conversation talks to, without
+   * losing any prior message. A no-op when `provider` is the same reference
+   * already in use.
+   *
+   * Any request already in flight against the previous provider is aborted
+   * first — its `AbortSignal` fires, so `requestAssistantReply`'s own
+   * `if (controller.signal.aborted) return;` guard discards whatever it was
+   * waiting for, and that stale response can never be appended to the
+   * conversation the new provider is now serving. `status` returns to
+   * `'idle'` so the composer is usable again immediately, rather than left
+   * showing "awaiting response" for a request that will never resolve into
+   * this conversation.
+   */
+  setProvider(provider: ChatProvider): void {
+    if (provider === this.provider) return;
+    this.provider = provider;
+    this.activeAbortController?.abort();
+    if (this.state.status === 'awaiting-response') {
+      this.setState({ ...this.state, status: 'idle' });
+    }
+  }
+
   subscribe(listener: ConversationListener): () => void {
     this.listeners.add(listener);
     return () => {
@@ -185,9 +213,23 @@ export class ConversationController {
     this.activeAbortController = controller;
 
     try {
-      const result = await this.provider.send({ messages }, { signal: controller.signal });
+      // Defence in depth: `messages` is already every element individually
+      // validated by `createChatMessage`, and `submit()`'s own runtime check
+      // already keeps the array at or under `CHAT_CONVERSATION_MAX_MESSAGES`
+      // before this is ever reached — but this is the schema-level backstop
+      // for that same bound at the exact boundary a request crosses into a
+      // provider, so a future bug in either caller does not silently send an
+      // unbounded request. Never expected to reject in normal operation.
+      const request = chatProviderRequestSchema.parse({ messages });
+      const rawResult = await this.provider.send(request, { signal: controller.signal });
       if (controller.signal.aborted) return;
 
+      // The provider's raw result is untrusted the moment it returns —
+      // whether that is the deterministic mock today or a real adapter in a
+      // later phase — so it is validated here, before any of it is trusted
+      // enough to become part of the conversation.
+      const result = chatProviderResultSchema.parse(rawResult);
+
       const assistantMessage = createChatMessage({
         id: this.generateId(),
         role: 'assistant',
diff --git a/src/renderer/chat/useActiveChatProvider.ts b/src/renderer/chat/useActiveChatProvider.ts
new file mode 100644
index 0000000..701271c
--- /dev/null
+++ b/src/renderer/chat/useActiveChatProvider.ts
@@ -0,0 +1,46 @@
+/**
+ * Resolves the active `ChatProvider` and its display status (Phase 2,
+ * Milestone 2).
+ *
+ * This is the one, explicit place that decides which adapter powers chat —
+ * `Chat.tsx` no longer imports `createMockChatProvider` itself. In this
+ * milestone the answer is always the deterministic mock, for every one of
+ * the four approved `ModelProvider` selections, because it is the only
+ * adapter that actually works: `createChatProviderForSelection` (the
+ * registry) returns a fail-closed placeholder for all four, by design — see
+ * `docs/phase-2-provider-architecture.md` for why chat still functions
+ * through the mock rather than going inert whenever no provider is
+ * configured, while `describeChatProviderStatus` still reports honestly on
+ * what the user actually selected.
+ *
+ * The provider instance is stable for the component's lifetime (`useRef`,
+ * not re-created per render), independent of `status`, which does change
+ * with `modelProvider.provider` — so a settings change never itself resets
+ * the conversation, even before `ConversationController.setProvider`'s own
+ * same-reference no-op guard is considered.
+ */
+
+import { useRef } from 'react';
+
+import {
+  createMockChatProvider,
+  describeChatProviderStatus,
+  type ChatProvider,
+  type ChatProviderStatus,
+} from '../../shared/chat';
+import type { ModelProviderSettings } from '../../shared/schemas';
+
+export interface ActiveChatProvider {
+  readonly provider: ChatProvider;
+  readonly status: ChatProviderStatus;
+}
+
+export function useActiveChatProvider(modelProvider: ModelProviderSettings): ActiveChatProvider {
+  const providerRef = useRef<ChatProvider | null>(null);
+  providerRef.current ??= createMockChatProvider();
+
+  return {
+    provider: providerRef.current,
+    status: describeChatProviderStatus(modelProvider.provider),
+  };
+}
diff --git a/src/renderer/chat/useConversation.ts b/src/renderer/chat/useConversation.ts
index 7275d24..5361426 100644
--- a/src/renderer/chat/useConversation.ts
+++ b/src/renderer/chat/useConversation.ts
@@ -1,5 +1,5 @@
 /**
- * Thin React binding over `ConversationController` (Phase 2, Milestone 1).
+ * Thin React binding over `ConversationController` (Phase 2, Milestones 1–2).
  *
  * Deliberately minimal: this hook owns no conversation logic of its own —
  * everything observable here is delegated to the controller, which is
@@ -8,7 +8,7 @@
  * controller's state and to give it stable `submit`/`retry` callbacks.
  */
 
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
 import { ConversationController, type ConversationState } from './conversation-controller';
 import type { ChatProvider } from '../../shared/chat';
@@ -21,13 +21,27 @@ export interface UseConversationResult {
 }
 
 /**
- * One controller instance per mounted provider identity. Passing a new
- * `provider` reference starts a fresh conversation — this milestone has
- * exactly one call site (`Chat.tsx`) and it never swaps providers at
- * runtime, so this is a deliberate simplicity choice, not an oversight.
+ * One controller instance for the component's whole lifetime, created via
+ * lazy `useRef` initialisation rather than `useMemo` — `useMemo` is
+ * documented by React as a performance optimisation only, not a correctness
+ * guarantee that it runs exactly once, which matters here because the
+ * controller carries live conversation state a remount must not discard.
+ *
+ * A new `provider` reference on a later render does **not** replace the
+ * controller (and so does not lose the conversation) — it is forwarded to
+ * the existing controller's `setProvider`, per
+ * `docs/phase-2-provider-architecture.md`'s "switching provider does not
+ * lose conversation state" requirement.
  */
 export function useConversation(provider: ChatProvider): UseConversationResult {
-  const controller = useMemo(() => new ConversationController({ provider }), [provider]);
+  const controllerRef = useRef<ConversationController | null>(null);
+  controllerRef.current ??= new ConversationController({ provider });
+  const controller = controllerRef.current;
+
+  useEffect(() => {
+    controller.setProvider(provider);
+  }, [controller, provider]);
+
   const [state, setState] = useState<ConversationState>(() => controller.getState());
 
   useEffect(() => {
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index c2c7376..d0650a3 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -138,6 +138,11 @@ main.app-ready {
   border-radius: 0.6rem;
   background: #0c1626;
 }
+.chat__provider-status {
+  margin: 0;
+  font-size: 0.8rem;
+  color: #73d5c8;
+}
 .chat__empty {
   margin: auto;
   max-width: 28rem;
diff --git a/src/shared/chat/index.ts b/src/shared/chat/index.ts
index 408670d..645b81e 100644
--- a/src/shared/chat/index.ts
+++ b/src/shared/chat/index.ts
@@ -1,9 +1,10 @@
 /**
- * Barrel for the chat provider layer (Phase 2, Milestone 1).
+ * Barrel for the chat provider layer (Phase 2, Milestones 1–2).
  *
  * Everything exported here is pure, has no Electron or Node dependency, and
- * makes no network request — see `provider.ts` and `mock-provider.ts` for
- * why that is enforced structurally, not only by convention.
+ * makes no network request — see `provider.ts`, `mock-provider.ts`,
+ * `registry.ts` and `timeout.ts` for why that is enforced structurally, not
+ * only by convention.
  */
 
 export { CHAT_PROVIDER_ERROR_CODES, ChatProviderError } from './provider';
@@ -17,3 +18,16 @@ export type {
 
 export { createMockChatProvider, MOCK_CHAT_PROVIDER_DEFAULT_DELAY_MS } from './mock-provider';
 export type { CreateMockChatProviderOptions } from './mock-provider';
+
+export {
+  createChatProviderForSelection,
+  describeChatProviderStatus,
+  getChatProviderCapabilities,
+} from './registry';
+export type {
+  ChatProviderAvailability,
+  ChatProviderCapabilities,
+  ChatProviderStatus,
+} from './registry';
+
+export { withProviderTimeout } from './timeout';
diff --git a/src/shared/chat/provider.ts b/src/shared/chat/provider.ts
index 047fd2d..03c669a 100644
--- a/src/shared/chat/provider.ts
+++ b/src/shared/chat/provider.ts
@@ -1,12 +1,15 @@
 /**
- * Chat provider abstraction (Phase 2, Milestone 1).
+ * Chat provider abstraction (Phase 2, Milestones 1–2).
  *
  * A `ChatProvider` turns a validated conversation into assistant reply text.
- * This module defines the shape only. The one implementation that exists in
- * this milestone is the deterministic mock (`./mock-provider.ts`) — there is
- * no real provider yet. A future phase adding a real provider (GLM, an
- * OpenAI-compatible endpoint, Ollama) implements this same interface; nothing
- * that consumes a `ChatProvider` needs to change when that happens.
+ * This module defines the shape only. The one working implementation in this
+ * codebase is still the deterministic mock (`./mock-provider.ts`) — Milestone
+ * 2 adds the registry (`./registry.ts`), request/response schemas
+ * (`../schemas/chat.schema.ts`) and a timeout decorator (`./timeout.ts`)
+ * around this same interface, but implements no real provider. A future
+ * phase adding one (GLM, an OpenAI-compatible endpoint, Ollama) implements
+ * this same interface; nothing that consumes a `ChatProvider` needs to
+ * change when that happens.
  *
  * Deliberately provider-independent and inert:
  *
@@ -26,6 +29,11 @@
  *  - Cancellation is an `AbortSignal`, the standard inert, dependency-free
  *    mechanism — nothing here starts a timer or a network request that would
  *    need a bespoke cancellation channel.
+ *  - Timeout is deliberately **not** a field on {@link ChatProviderRequestOptions}.
+ *    Every provider already accepts a `signal`, so a caller wanting a timeout
+ *    budget composes `withProviderTimeout(provider, timeoutMs)`
+ *    (`./timeout.ts`) once, rather than every adapter re-implementing its own
+ *    timer and every call site remembering to pass one.
  */
 
 import type { ChatMessage } from '../schemas/chat.schema';
@@ -44,7 +52,37 @@ export interface ChatProviderResult {
   readonly content: string;
 }
 
-export const CHAT_PROVIDER_ERROR_CODES = ['PROVIDER_REQUEST_FAILED', 'PROVIDER_ABORTED'] as const;
+/**
+ * The normalized failure vocabulary every `ChatProvider` reports through,
+ * covering the five categories a caller must be able to distinguish:
+ *
+ *  - `PROVIDER_UNAVAILABLE` — the provider cannot be used at all right now:
+ *    nothing is configured (`none`), or the configured provider has no real
+ *    implementation yet (`glm`, `openai-compatible`, `ollama` in Phase 2), or
+ *    an unrecognised identifier reached the registry. See
+ *    `src/shared/chat/registry.ts`.
+ *  - `PROVIDER_INVALID_CONFIGURATION` — the provider is implemented but its
+ *    configuration is unusable (for example, a real HTTP adapter with no
+ *    base URL). Declared now for a future real adapter to report against;
+ *    nothing in this milestone constructs this code, since no adapter here
+ *    has configuration to validate beyond what `settingsSchema` already
+ *    enforces.
+ *  - `PROVIDER_TIMEOUT` — the request did not complete within a caller's
+ *    configured budget. See `src/shared/chat/timeout.ts`'s
+ *    `withProviderTimeout`, the one thing in this codebase that produces it.
+ *  - `PROVIDER_ABORTED` — cancelled via `AbortSignal`, whether by the caller
+ *    directly or as a side effect of `withProviderTimeout`'s own internal
+ *    cancellation forwarding.
+ *  - `PROVIDER_REQUEST_FAILED` — a generic failure that fits none of the
+ *    above. The mock provider's deliberate failure trigger uses this.
+ */
+export const CHAT_PROVIDER_ERROR_CODES = [
+  'PROVIDER_UNAVAILABLE',
+  'PROVIDER_INVALID_CONFIGURATION',
+  'PROVIDER_TIMEOUT',
+  'PROVIDER_ABORTED',
+  'PROVIDER_REQUEST_FAILED',
+] as const;
 export type ChatProviderErrorCode = (typeof CHAT_PROVIDER_ERROR_CODES)[number];
 
 /**
diff --git a/src/shared/chat/registry.ts b/src/shared/chat/registry.ts
new file mode 100644
index 0000000..b1cd40a
--- /dev/null
+++ b/src/shared/chat/registry.ts
@@ -0,0 +1,138 @@
+/**
+ * Approved-provider registry (Phase 2, Milestone 2).
+ *
+ * Maps the four settings-level provider identifiers (`none`, `glm`,
+ * `openai-compatible`, `ollama` — {@link MODEL_PROVIDERS}) to safe capability
+ * metadata and to a `ChatProvider` adapter. No real network adapter exists
+ * for any of them yet, so {@link createChatProviderForSelection} returns a
+ * fail-closed placeholder for all four: asking any of them to `send()`
+ * always rejects with a normalized `PROVIDER_UNAVAILABLE` error, never a
+ * silent success and never a real request. This is deliberate, not a gap —
+ * see `docs/phase-2-provider-architecture.md` for why `none` and the three
+ * unimplemented real identifiers are treated identically at the `send()`
+ * boundary and are distinguished only by status text, never by one of them
+ * quietly working.
+ *
+ * The deterministic mock (`./mock-provider.ts`) is a separate, always-
+ * available adapter — for tests, and as the one thing that actually answers
+ * a chat message in this phase. `src/renderer/chat/useActiveChatProvider.ts`
+ * is the single, explicit place that decides to use it; nothing here wires
+ * it in automatically for any approved identifier, so the fail-closed
+ * guarantee below is real and independently testable.
+ *
+ * No I/O, no Electron, no network — the same `src/shared` purity boundary as
+ * every file in this directory.
+ */
+
+import { MODEL_PROVIDERS, PROVIDERS_REQUIRING_API_KEY, type ModelProvider } from '../constants';
+import { ChatProviderError, type ChatProvider, type ChatProviderResult } from './provider';
+
+/** Safe, non-secret metadata describing one approved provider identifier. */
+export interface ChatProviderCapabilities {
+  readonly id: ModelProvider;
+  /** Human-readable label, safe to show in the UI. */
+  readonly label: string;
+  /** Whether this provider authenticates with a key from the encrypted secret store. */
+  readonly requiresApiKey: boolean;
+  /** Whether a real, network-capable adapter exists for this identifier yet. Always `false` in Phase 2. */
+  readonly implemented: boolean;
+}
+
+const LABEL_BY_PROVIDER: Readonly<Record<ModelProvider, string>> = {
+  none: 'No provider configured',
+  glm: 'GLM',
+  'openai-compatible': 'OpenAI-compatible endpoint',
+  ollama: 'Ollama (local)',
+};
+
+/**
+ * Safe capability metadata for an approved provider identifier.
+ *
+ * `requiresApiKey` is derived from {@link PROVIDERS_REQUIRING_API_KEY} —
+ * the same constant `main/settings-service.ts`'s `hasApiKey` reconciliation
+ * and `main/ipc.ts`'s `secrets.write` eligibility check already use — rather
+ * than a second, hand-duplicated table that could silently drift from it.
+ */
+export function getChatProviderCapabilities(id: ModelProvider): ChatProviderCapabilities {
+  return {
+    id,
+    label: LABEL_BY_PROVIDER[id],
+    requiresApiKey: PROVIDERS_REQUIRING_API_KEY.includes(id),
+    implemented: false,
+  };
+}
+
+/** What the interface should tell the user about the currently selected provider. */
+export type ChatProviderAvailability = 'not-configured' | 'not-implemented';
+
+export interface ChatProviderStatus {
+  readonly selected: ModelProvider;
+  readonly availability: ChatProviderAvailability;
+  /**
+   * Safe, user-facing summary text. Never contains a key, a header, a URL,
+   * or any value from the encrypted secret store — it is built entirely from
+   * the fixed labels above and a fixed template, never from settings input.
+   */
+  readonly summary: string;
+}
+
+/**
+ * Describes the currently selected provider for display, without implying a
+ * real connection exists — none does yet.
+ */
+export function describeChatProviderStatus(selected: ModelProvider): ChatProviderStatus {
+  const capabilities = getChatProviderCapabilities(selected);
+  if (selected === 'none') {
+    return {
+      selected,
+      availability: 'not-configured',
+      summary: 'No provider configured. Chat is running on the local mock provider.',
+    };
+  }
+  return {
+    selected,
+    availability: 'not-implemented',
+    summary: `${capabilities.label} is selected but not connected yet. Chat is running on the local mock provider.`,
+  };
+}
+
+const UNAVAILABLE_MESSAGE_BY_PROVIDER: Readonly<Record<ModelProvider, string>> = {
+  none: 'No provider is configured. Choose one in provider settings.',
+  glm: 'GLM is configured but not yet connected in this version.',
+  'openai-compatible':
+    'This OpenAI-compatible endpoint is configured but not yet connected in this version.',
+  ollama: 'Ollama is configured but not yet connected in this version.',
+};
+
+/**
+ * A `ChatProvider` whose `send()` always rejects with `PROVIDER_UNAVAILABLE`
+ * and the given safe message — never a network request, never a partial
+ * result. Used for every approved identifier in {@link createChatProviderForSelection}
+ * and for any identifier the registry does not recognise.
+ */
+function createUnavailableChatProvider(id: string, message: string): ChatProvider {
+  return {
+    id,
+    send(): Promise<ChatProviderResult> {
+      return Promise.reject(new ChatProviderError('PROVIDER_UNAVAILABLE', message));
+    },
+  };
+}
+
+/**
+ * Resolves the `ChatProvider` for an approved settings-level identifier.
+ *
+ * Every one of the four approved identifiers — including `none` — maps to a
+ * fail-closed adapter in this milestone: none of them makes a network
+ * request, and none of them silently succeeds. An identifier outside
+ * {@link MODEL_PROVIDERS} (which should not happen, since `ModelProvider` is
+ * a closed type validated by `settingsSchema`, but may reach here through an
+ * untrusted boundary that bypassed that validation) fails closed the same
+ * way rather than throwing.
+ */
+export function createChatProviderForSelection(id: ModelProvider): ChatProvider {
+  if (!MODEL_PROVIDERS.includes(id)) {
+    return createUnavailableChatProvider('unknown', 'This provider is not recognised.');
+  }
+  return createUnavailableChatProvider(id, UNAVAILABLE_MESSAGE_BY_PROVIDER[id]);
+}
diff --git a/src/shared/chat/timeout.ts b/src/shared/chat/timeout.ts
new file mode 100644
index 0000000..33c9d00
--- /dev/null
+++ b/src/shared/chat/timeout.ts
@@ -0,0 +1,101 @@
+/**
+ * Timeout decorator for any `ChatProvider` (Phase 2, Milestone 2).
+ *
+ * `withProviderTimeout(provider, timeoutMs)` wraps a provider so a request
+ * that does not settle within `timeoutMs` is aborted and rejected with
+ * `ChatProviderError('PROVIDER_TIMEOUT', …)`, instead of hanging
+ * indefinitely. Composable and provider-neutral: it wraps `mock-provider.ts`
+ * today and will wrap a real adapter identically once one exists, without
+ * either implementation needing its own timer.
+ *
+ * No network access, no Electron, no Node built-in — the same `src/shared`
+ * purity boundary as every other file in this directory.
+ */
+
+import {
+  ChatProviderError,
+  type ChatProvider,
+  type ChatProviderRequest,
+  type ChatProviderRequestOptions,
+  type ChatProviderResult,
+} from './provider';
+
+/**
+ * A module-local sentinel, never exported: identifies an abort this
+ * decorator caused itself (the timer firing), distinct from one it merely
+ * forwarded from an external signal. A fresh `Symbol` rather than a string
+ * so nothing outside this file could construct an equal value by accident.
+ */
+const TIMEOUT_REASON = Symbol('withProviderTimeout:timeout');
+
+/**
+ * Wraps `provider` so every `send()` call is bounded by `timeoutMs`.
+ *
+ * A single fresh `AbortController` is created per call and passed to the
+ * wrapped provider as its `signal` — never the caller's own signal directly
+ * — so this decorator can tell, when the wrapped provider's promise rejects,
+ * whether the cause was its own timer firing (report `PROVIDER_TIMEOUT`) or
+ * something else (forward the original error unchanged, including a genuine
+ * caller-initiated `PROVIDER_ABORTED`). It tells the two apart via
+ * `AbortSignal.abort(reason)`'s `reason` — a fixed local sentinel for the
+ * timer, the external signal's own `reason` when forwarding an outside
+ * cancellation — rather than a separate mutable flag: a `let` reassigned
+ * only inside the `setTimeout` callback below would need an explicit type
+ * annotation to stop TypeScript narrowing it to `false` for the rest of this
+ * function body (control-flow analysis does not follow the reassignment
+ * through that closure), and an explicit annotation on an otherwise-inferred
+ * boolean is exactly what `@typescript-eslint/no-inferrable-types` forbids.
+ * Reading `combined.signal.reason` sidesteps the conflict entirely. The
+ * caller's signal, if supplied, is forwarded into the same combined
+ * controller, so an external cancellation still cancels the wrapped
+ * provider's work exactly as it would without this decorator.
+ *
+ * An externally already-aborted signal is rejected immediately, before the
+ * wrapped provider's `send()` is ever called. This does not rely on the
+ * wrapped provider itself correctly noticing a pre-aborted signal — the
+ * interface documents that a provider *may* check `signal.aborted` up front
+ * the way the mock provider does, but nothing requires every future
+ * implementation to, and this decorator's own cancellation guarantee should
+ * not depend on that.
+ */
+export function withProviderTimeout(provider: ChatProvider, timeoutMs: number): ChatProvider {
+  return {
+    id: provider.id,
+    async send(
+      request: ChatProviderRequest,
+      options?: ChatProviderRequestOptions,
+    ): Promise<ChatProviderResult> {
+      const externalSignal = options?.signal;
+      if (externalSignal?.aborted) {
+        throw new ChatProviderError('PROVIDER_ABORTED', 'The request was already aborted.');
+      }
+
+      const combined = new AbortController();
+
+      const forwardAbort = (): void => {
+        combined.abort(externalSignal?.reason);
+      };
+      externalSignal?.addEventListener('abort', forwardAbort, { once: true });
+
+      const timer: ReturnType<typeof setTimeout> = setTimeout(() => {
+        combined.abort(TIMEOUT_REASON);
+      }, timeoutMs);
+
+      try {
+        return await provider.send(request, { signal: combined.signal });
+      } catch (error) {
+        if (combined.signal.reason === TIMEOUT_REASON) {
+          throw new ChatProviderError(
+            'PROVIDER_TIMEOUT',
+            `The provider did not respond within ${String(timeoutMs)}ms.`,
+            { cause: error },
+          );
+        }
+        throw error;
+      } finally {
+        clearTimeout(timer);
+        externalSignal?.removeEventListener('abort', forwardAbort);
+      }
+    },
+  };
+}
diff --git a/src/shared/schemas/chat.schema.ts b/src/shared/schemas/chat.schema.ts
index 5c1b3eb..d8f0da5 100644
--- a/src/shared/schemas/chat.schema.ts
+++ b/src/shared/schemas/chat.schema.ts
@@ -18,6 +18,7 @@ import { z } from 'zod';
 import {
   BIDI_CONTROL_PATTERN,
   CHAT_CONTROL_CHARACTER_PATTERN,
+  CHAT_CONVERSATION_MAX_MESSAGES,
   CHAT_MESSAGE_CONTENT_MAX_LENGTH,
   CHAT_MESSAGE_CONTENT_MIN_LENGTH,
   CHAT_MESSAGE_ROLES,
@@ -26,6 +27,23 @@ import {
 import { auditParametersSchema } from './audit-parameters.schema';
 import type { AuditParameters } from './audit-parameters.schema';
 
+/**
+ * Bounded, control-character- and bidi-safe text, shared by a message's own
+ * `content` and by {@link chatProviderResultSchema}'s `content` — the same
+ * safety rules apply the moment either crosses a validation boundary,
+ * whether that text was typed by the user or returned by a provider.
+ */
+const chatContentSchema = z
+  .string()
+  .min(CHAT_MESSAGE_CONTENT_MIN_LENGTH)
+  .max(CHAT_MESSAGE_CONTENT_MAX_LENGTH)
+  .refine((value) => !CHAT_CONTROL_CHARACTER_PATTERN.test(value), {
+    message: 'must not contain unsafe control characters',
+  })
+  .refine((value) => !BIDI_CONTROL_PATTERN.test(value), {
+    message: 'must not contain bidirectional control characters',
+  });
+
 /**
  * Reuses the audit-parameter schema for message metadata rather than
  * defining a second bounded-JSON-object schema: the requirements are
@@ -42,16 +60,7 @@ export const chatMessageSchema = z.strictObject({
   /** Stable, caller-supplied identifier — a UUID generated by the renderer. */
   id: z.uuid(),
   role: z.enum(CHAT_MESSAGE_ROLES),
-  content: z
-    .string()
-    .min(CHAT_MESSAGE_CONTENT_MIN_LENGTH)
-    .max(CHAT_MESSAGE_CONTENT_MAX_LENGTH)
-    .refine((value) => !CHAT_CONTROL_CHARACTER_PATTERN.test(value), {
-      message: 'must not contain unsafe control characters',
-    })
-    .refine((value) => !BIDI_CONTROL_PATTERN.test(value), {
-      message: 'must not contain bidirectional control characters',
-    }),
+  content: chatContentSchema,
   /** UTC ISO-8601. Offsets are rejected so every message is comparable and sortable. */
   createdAt: z.iso.datetime(),
   /** See {@link CHAT_MESSAGE_STATUSES}'s doc comment for why this is unused today. */
@@ -83,3 +92,35 @@ export function createChatMessage(input: {
 }): ChatMessage {
   return chatMessageSchema.parse(input);
 }
+
+/**
+ * A `ChatProvider.send()` request, validated at the boundary where a
+ * conversation crosses into a provider (Phase 2, Milestone 2).
+ *
+ * Every message it carries was already constructed through
+ * {@link createChatMessage}, so this mainly re-asserts one property that,
+ * before this milestone, was enforced only by `ConversationController`'s own
+ * runtime `if` check and nowhere in the schema layer: the conversation
+ * cannot exceed {@link CHAT_CONVERSATION_MAX_MESSAGES}. `strictObject` also
+ * means a request cannot carry an extra field (a stray `apiKey`, say)
+ * without being rejected outright.
+ */
+export const chatProviderRequestSchema = z.strictObject({
+  messages: z.array(chatMessageSchema).max(CHAT_CONVERSATION_MAX_MESSAGES),
+});
+export type ChatProviderRequestPayload = z.infer<typeof chatProviderRequestSchema>;
+
+/**
+ * A `ChatProvider.send()` result, validated the moment it comes back from
+ * a provider — mock today, real in a later phase — and before its `content`
+ * is trusted for anything, including being wrapped into a
+ * {@link ChatMessage} by `createChatMessage`. Rejects a non-string, an empty,
+ * an oversized, or an unsafe `content`, and — via `strictObject` — any field
+ * beyond `content` at all, so a provider cannot smuggle extra data (a
+ * "confidence score," a raw upstream error object, anything) past this
+ * boundary.
+ */
+export const chatProviderResultSchema = z.strictObject({
+  content: chatContentSchema,
+});
+export type ChatProviderResultPayload = z.infer<typeof chatProviderResultSchema>;
diff --git a/src/shared/schemas/index.ts b/src/shared/schemas/index.ts
index 17c361f..320d1cd 100644
--- a/src/shared/schemas/index.ts
+++ b/src/shared/schemas/index.ts
@@ -88,5 +88,16 @@ export type {
 export { createEmptySecretStoreFile, secretStoreFileSchema } from './secrets.schema';
 export type { SecretStoreFile } from './secrets.schema';
 
-export { chatMessageMetadataSchema, chatMessageSchema, createChatMessage } from './chat.schema';
-export type { ChatMessage, ChatMessageMetadata } from './chat.schema';
+export {
+  chatMessageMetadataSchema,
+  chatMessageSchema,
+  chatProviderRequestSchema,
+  chatProviderResultSchema,
+  createChatMessage,
+} from './chat.schema';
+export type {
+  ChatMessage,
+  ChatMessageMetadata,
+  ChatProviderRequestPayload,
+  ChatProviderResultPayload,
+} from './chat.schema';
diff --git a/tests/unit/renderer/conversation-controller.test.ts b/tests/unit/renderer/conversation-controller.test.ts
index f2b2813..16caa77 100644
--- a/tests/unit/renderer/conversation-controller.test.ts
+++ b/tests/unit/renderer/conversation-controller.test.ts
@@ -307,4 +307,110 @@ describe('ConversationController', () => {
 
     expect(listener).not.toHaveBeenCalled();
   });
+
+  describe('setProvider', () => {
+    it('is a no-op when passed the same provider reference already in use', async () => {
+      const provider = instantProvider(() => ({ content: 'ok' }));
+      const controller = new ConversationController({ provider, ...makeDeps() });
+      await controller.submit('hello');
+
+      const before = controller.getState();
+      controller.setProvider(provider);
+
+      expect(controller.getState()).toBe(before);
+    });
+
+    it('switching provider while idle preserves the existing conversation', async () => {
+      const providerA = instantProvider(() => ({ content: 'from A' }));
+      const controller = new ConversationController({ provider: providerA, ...makeDeps() });
+      await controller.submit('hello');
+      expect(controller.getState().messages).toHaveLength(2);
+
+      const providerB = instantProvider(() => ({ content: 'from B' }));
+      controller.setProvider(providerB);
+
+      expect(controller.getState().messages).toHaveLength(2);
+      expect(controller.getState().status).toBe('idle');
+
+      await controller.submit('second message');
+      const state = controller.getState();
+      expect(state.messages).toHaveLength(4);
+      expect(state.messages[3]?.content).toBe('from B');
+    });
+
+    it('switching provider while a response is pending aborts the stale request and returns to idle without losing the user message', async () => {
+      const { provider: providerA, resolve: resolveA, calls: callsA } = deferredProvider();
+      const controller = new ConversationController({ provider: providerA, ...makeDeps() });
+
+      const submitPromise = controller.submit('hello');
+      expect(controller.getState().status).toBe('awaiting-response');
+      expect(callsA).toHaveLength(1);
+
+      const providerB = instantProvider(() => ({ content: 'unused' }));
+      controller.setProvider(providerB);
+
+      expect(controller.getState().status).toBe('idle');
+      expect(controller.getState().messages).toHaveLength(1);
+      expect(controller.getState().messages[0]).toMatchObject({ role: 'user', content: 'hello' });
+
+      // The original request resolves late, after the switch. Its result
+      // must never land in the conversation now being served by providerB.
+      resolveA({ content: 'stale response from A' });
+      await submitPromise;
+
+      const state = controller.getState();
+      expect(state.messages).toHaveLength(1);
+      expect(state.messages.some((message) => message.content.includes('stale'))).toBe(false);
+    });
+
+    it('a stale response cannot overwrite a newer response already recorded', async () => {
+      const { provider: providerA, resolve: resolveA } = deferredProvider();
+      const controller = new ConversationController({ provider: providerA, ...makeDeps() });
+
+      // This request is never resolved until the end of the test, so its
+      // own promise is not awaited here — awaiting it now, before resolveA
+      // is ever called, would hang forever.
+      const submitPromise = controller.submit('hello');
+      const providerB = instantProvider(() => ({ content: 'fresh response from B' }));
+      controller.setProvider(providerB);
+
+      // A fresh submission (not retry() — there is no standing error to
+      // retry from, just a switch) now goes through providerB and completes.
+      await controller.submit('are you there');
+      const afterB = controller.getState();
+      expect(afterB.messages).toHaveLength(3);
+      expect(afterB.messages[2]?.content).toBe('fresh response from B');
+
+      // providerA's long-abandoned request finally resolves. It must not be
+      // appended, and it must not disturb the conversation providerB already
+      // completed.
+      resolveA({ content: 'very stale response from A' });
+      await submitPromise;
+
+      const state = controller.getState();
+      expect(state.messages).toHaveLength(3);
+      expect(state.messages[2]?.content).toBe('fresh response from B');
+      expect(state.messages.some((message) => message.content.includes('stale'))).toBe(false);
+    });
+
+    it('retry after a provider switch with no standing error is a no-op, not a call to either provider', async () => {
+      const sendA = vi.fn(() => new Promise<ChatProviderResult>(() => undefined));
+      const providerA: ChatProvider = { id: 'a', send: sendA };
+      const controller = new ConversationController({ provider: providerA, ...makeDeps() });
+
+      void controller.submit('hello');
+      expect(sendA).toHaveBeenCalledTimes(1);
+
+      const sendB = vi.fn(() => Promise.resolve({ content: 'ok' }));
+      controller.setProvider({ id: 'b', send: sendB });
+
+      // The switch itself never failed anything — status is idle with no
+      // error — so retry() (meant only to recover from a failure) must stay
+      // a no-op rather than firing a request of its own against providerB.
+      await controller.retry();
+
+      expect(sendA).toHaveBeenCalledTimes(1);
+      expect(sendB).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/tests/unit/shared/chat-boundary-scan.test.ts b/tests/unit/shared/chat-boundary-scan.test.ts
new file mode 100644
index 0000000..40c9a15
--- /dev/null
+++ b/tests/unit/shared/chat-boundary-scan.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Source-scan regression test (Phase 2, Milestone 2).
+ *
+ * The chat and provider layers are already structurally barred from
+ * reaching Electron, Node built-ins, the network, or `window.localAgent` —
+ * `eslint.config.js`'s purity boundary covers `src/shared/**`, and nothing
+ * under `src/renderer/chat` imports the preload bridge. This test makes that
+ * guarantee empirical rather than relying solely on lint staying configured
+ * correctly forever: it reads the actual source of every file in both
+ * directories, strips comments (this codebase's own doc comments freely
+ * *describe* what is absent — "never touches `window.localAgent`" — which
+ * would otherwise trip a naive substring scan on prose, not code), and
+ * asserts none of the forbidden references appear anywhere in what remains.
+ */
+
+const REPO_ROOT = join(__dirname, '..', '..', '..');
+const SCAN_DIRECTORIES = [
+  join(REPO_ROOT, 'src', 'shared', 'chat'),
+  join(REPO_ROOT, 'src', 'renderer', 'chat'),
+];
+
+const FORBIDDEN_PATTERNS: readonly { readonly label: string; readonly pattern: RegExp }[] = [
+  { label: 'ipcRenderer', pattern: /ipcRenderer/ },
+  { label: 'window.localAgent', pattern: /window\.localAgent/ },
+  { label: "import ... from 'electron'", pattern: /from ['"]electron['"]/ },
+  { label: 'require("electron")', pattern: /require\(['"]electron['"]\)/ },
+  { label: 'child_process', pattern: /child_process/ },
+  { label: 'node:fs', pattern: /from ['"]node:fs/ },
+  { label: 'fetch(', pattern: /\bfetch\(/ },
+  { label: 'XMLHttpRequest', pattern: /XMLHttpRequest/ },
+  { label: 'WebSocket', pattern: /\bWebSocket\b/ },
+  { label: 'eval(', pattern: /\beval\(/ },
+  { label: 'new Function(', pattern: /new Function\(/ },
+  { label: 'dangerouslySetInnerHTML', pattern: /dangerouslySetInnerHTML/ },
+  { label: 'ActionProposal (chat has no action to authorize)', pattern: /ActionProposal/ },
+];
+
+function listSourceFiles(dir: string): string[] {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listSourceFiles(fullPath));
+    } else if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * Strips `/* ... *\/` block comments (including JSDoc) and `// ...` line
+ * comments. Verified safe for this specific, small scan target: none of the
+ * files under scan contain a `//` inside a string literal (checked by
+ * inspection — every `//` occurrence in them is already inside a comment),
+ * so this does not need a full tokenizer to be correct here.
+ */
+function stripComments(source: string): string {
+  const withoutBlockComments = source.replace(/\/\*[\s\S]*?\*\//g, '');
+  return withoutBlockComments.replace(/\/\/.*$/gm, '');
+}
+
+describe('chat/provider layer source-scan boundary', () => {
+  const files = SCAN_DIRECTORIES.flatMap((dir) => listSourceFiles(dir));
+  const codeByFile = new Map(
+    files.map((file) => [file, stripComments(readFileSync(file, 'utf8'))]),
+  );
+
+  it('found a non-empty set of files to scan (the scan itself is not vacuous)', () => {
+    expect(files.length).toBeGreaterThan(0);
+  });
+
+  it('comment-stripping does not silently empty out a whole file', () => {
+    for (const [file, code] of codeByFile) {
+      expect(code.trim().length, `${file} became empty after stripping comments`).toBeGreaterThan(
+        0,
+      );
+    }
+  });
+
+  it.each(FORBIDDEN_PATTERNS)('no code (comments excluded) references $label', ({ pattern }) => {
+    const offenders = [...codeByFile.entries()]
+      .filter(([, code]) => pattern.test(code))
+      .map(([file]) => file);
+    expect(offenders).toEqual([]);
+  });
+});
diff --git a/tests/unit/shared/chat-provider-schema.test.ts b/tests/unit/shared/chat-provider-schema.test.ts
new file mode 100644
index 0000000..441caa1
--- /dev/null
+++ b/tests/unit/shared/chat-provider-schema.test.ts
@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  chatProviderRequestSchema,
+  chatProviderResultSchema,
+  createChatMessage,
+} from '../../../src/shared/schemas/chat.schema';
+import {
+  CHAT_CONVERSATION_MAX_MESSAGES,
+  CHAT_MESSAGE_CONTENT_MAX_LENGTH,
+} from '../../../src/shared/constants';
+
+const CREATED_AT = '2026-01-01T00:00:00.000Z';
+
+function userMessage(content: string, id = '11111111-1111-4111-8111-111111111111') {
+  return createChatMessage({ id, role: 'user', content, createdAt: CREATED_AT });
+}
+
+describe('chatProviderRequestSchema', () => {
+  it('accepts a request with a normal-sized conversation', () => {
+    const result = chatProviderRequestSchema.safeParse({ messages: [userMessage('hello')] });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts an empty conversation (first request has no history)', () => {
+    const result = chatProviderRequestSchema.safeParse({ messages: [] });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a conversation at exactly the maximum length', () => {
+    const messages = Array.from({ length: CHAT_CONVERSATION_MAX_MESSAGES }, (_, index) =>
+      userMessage(
+        `message ${String(index)}`,
+        `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`,
+      ),
+    );
+    const result = chatProviderRequestSchema.safeParse({ messages });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects a conversation one message past the maximum length', () => {
+    const messages = Array.from({ length: CHAT_CONVERSATION_MAX_MESSAGES + 1 }, (_, index) =>
+      userMessage(
+        `message ${String(index)}`,
+        `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`,
+      ),
+    );
+    const result = chatProviderRequestSchema.safeParse({ messages });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an unknown top-level field', () => {
+    const result = chatProviderRequestSchema.safeParse({
+      messages: [userMessage('hello')],
+      apiKey: 'sk-not-real-test-only',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a malformed message inside the conversation', () => {
+    const result = chatProviderRequestSchema.safeParse({
+      messages: [{ id: 'not-a-uuid', role: 'user', content: 'hi', createdAt: CREATED_AT }],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a message carrying an unredacted secret-looking metadata field', () => {
+    const message = {
+      id: '11111111-1111-4111-8111-111111111111',
+      role: 'user',
+      content: 'hello',
+      createdAt: CREATED_AT,
+      metadata: { apiKey: 'sk-not-real-test-only' },
+    };
+    const result = chatProviderRequestSchema.safeParse({ messages: [message] });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('chatProviderResultSchema', () => {
+  it('accepts a well-formed result', () => {
+    const result = chatProviderResultSchema.safeParse({ content: 'a reply' });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects an empty content string', () => {
+    const result = chatProviderResultSchema.safeParse({ content: '' });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a non-string content', () => {
+    const result = chatProviderResultSchema.safeParse({ content: 12345 });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects content past the maximum length', () => {
+    const result = chatProviderResultSchema.safeParse({
+      content: 'a'.repeat(CHAT_MESSAGE_CONTENT_MAX_LENGTH + 1),
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects content containing an unsafe control character', () => {
+    const result = chatProviderResultSchema.safeParse({ content: 'hello\x00world' });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an unknown field, so a provider cannot smuggle extra data past this boundary', () => {
+    const result = chatProviderResultSchema.safeParse({
+      content: 'a reply',
+      confidence: 0.9,
+      rawUpstreamError: { status: 500 },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects a missing content field', () => {
+    const result = chatProviderResultSchema.safeParse({});
+    expect(result.success).toBe(false);
+  });
+});
diff --git a/tests/unit/shared/chat-registry.test.ts b/tests/unit/shared/chat-registry.test.ts
new file mode 100644
index 0000000..834953d
--- /dev/null
+++ b/tests/unit/shared/chat-registry.test.ts
@@ -0,0 +1,133 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createChatProviderForSelection,
+  describeChatProviderStatus,
+  getChatProviderCapabilities,
+} from '../../../src/shared/chat/registry';
+import { ChatProviderError } from '../../../src/shared/chat/provider';
+import { MODEL_PROVIDERS, type ModelProvider } from '../../../src/shared/constants';
+
+describe('getChatProviderCapabilities', () => {
+  it.each(MODEL_PROVIDERS)('describes every approved identifier: %s', (id) => {
+    const capabilities = getChatProviderCapabilities(id);
+    expect(capabilities.id).toBe(id);
+    expect(typeof capabilities.label).toBe('string');
+    expect(capabilities.label.length).toBeGreaterThan(0);
+  });
+
+  it('reports requiresApiKey only for glm and openai-compatible', () => {
+    expect(getChatProviderCapabilities('none').requiresApiKey).toBe(false);
+    expect(getChatProviderCapabilities('ollama').requiresApiKey).toBe(false);
+    expect(getChatProviderCapabilities('glm').requiresApiKey).toBe(true);
+    expect(getChatProviderCapabilities('openai-compatible').requiresApiKey).toBe(true);
+  });
+
+  it('reports every provider as not implemented in this phase', () => {
+    for (const id of MODEL_PROVIDERS) {
+      expect(getChatProviderCapabilities(id).implemented).toBe(false);
+    }
+  });
+
+  it('exposes requiresApiKey only as a boolean flag, never a credential-shaped value', () => {
+    // `requiresApiKey` is a safe, neutral capability flag — the same pattern
+    // `settings.json`'s own `hasApiKey` boolean already uses — not a secret
+    // itself. What must never appear is an actual key- or token-shaped
+    // *value* anywhere in this object.
+    for (const id of MODEL_PROVIDERS) {
+      const capabilities = getChatProviderCapabilities(id);
+      expect(typeof capabilities.requiresApiKey).toBe('boolean');
+      for (const value of Object.values(capabilities)) {
+        if (typeof value === 'string') {
+          expect(value).not.toMatch(/^sk-|bearer\s|^[A-Za-z0-9_-]{32,}$/i);
+        }
+      }
+    }
+  });
+});
+
+describe('describeChatProviderStatus', () => {
+  it('reports "none" as not-configured', () => {
+    const status = describeChatProviderStatus('none');
+    expect(status.availability).toBe('not-configured');
+    expect(status.summary).toMatch(/mock/i);
+  });
+
+  it.each(['glm', 'openai-compatible', 'ollama'] as const)(
+    'reports %s as not-implemented',
+    (id) => {
+      const status = describeChatProviderStatus(id);
+      expect(status.availability).toBe('not-implemented');
+      expect(status.summary).toMatch(/mock/i);
+    },
+  );
+
+  it('never places settings input into the summary text, only fixed labels', () => {
+    // The function's only input is the enum identifier itself — there is no
+    // parameter through which a hostile or unexpected string could reach
+    // the summary, so this asserts the output is always one of the four
+    // known, reviewed templates.
+    for (const id of MODEL_PROVIDERS) {
+      const summary = describeChatProviderStatus(id).summary;
+      expect(summary).not.toContain('apiKey');
+      expect(summary).not.toContain('token');
+    }
+  });
+});
+
+describe('createChatProviderForSelection', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it.each(MODEL_PROVIDERS)('fails closed for the approved identifier %s', async (id) => {
+    const provider = createChatProviderForSelection(id);
+    await expect(provider.send({ messages: [] })).rejects.toBeInstanceOf(ChatProviderError);
+  });
+
+  it.each(MODEL_PROVIDERS)('reports PROVIDER_UNAVAILABLE for %s', async (id) => {
+    const provider = createChatProviderForSelection(id);
+    await expect(provider.send({ messages: [] })).rejects.toMatchObject({
+      code: 'PROVIDER_UNAVAILABLE',
+    });
+  });
+
+  it('fails closed for an identifier outside the approved set, never throwing synchronously', async () => {
+    const hostile = 'anthropic' as unknown as ModelProvider;
+    const provider = createChatProviderForSelection(hostile);
+    await expect(provider.send({ messages: [] })).rejects.toMatchObject({
+      code: 'PROVIDER_UNAVAILABLE',
+    });
+  });
+
+  it('never returns a provider whose id is one of the disapproved identifiers', () => {
+    for (const hostile of ['anthropic', 'openai', 'claude', 'gemini'] as const) {
+      const provider = createChatProviderForSelection(hostile as unknown as ModelProvider);
+      expect(provider.id).not.toBe(hostile);
+    }
+  });
+
+  it('never calls the global fetch function for any approved identifier', async () => {
+    if (typeof globalThis.fetch !== 'function') return;
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    for (const id of MODEL_PROVIDERS) {
+      await createChatProviderForSelection(id)
+        .send({ messages: [] })
+        .catch(() => undefined);
+    }
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it('never resolves successfully for any approved identifier', async () => {
+    for (const id of MODEL_PROVIDERS) {
+      let resolved = false;
+      await createChatProviderForSelection(id)
+        .send({ messages: [] })
+        .then(() => {
+          resolved = true;
+        })
+        .catch(() => undefined);
+      expect(resolved).toBe(false);
+    }
+  });
+});
diff --git a/tests/unit/shared/provider-timeout.test.ts b/tests/unit/shared/provider-timeout.test.ts
new file mode 100644
index 0000000..9352e1a
--- /dev/null
+++ b/tests/unit/shared/provider-timeout.test.ts
@@ -0,0 +1,143 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { withProviderTimeout } from '../../../src/shared/chat/timeout';
+import { ChatProviderError } from '../../../src/shared/chat/provider';
+import type {
+  ChatProvider,
+  ChatProviderRequest,
+  ChatProviderRequestOptions,
+  ChatProviderResult,
+} from '../../../src/shared/chat/provider';
+
+const EMPTY_REQUEST: ChatProviderRequest = { messages: [] };
+
+/** A provider whose resolution/rejection is controlled by the test, and that observes its signal. */
+function controllableProvider(): {
+  provider: ChatProvider;
+  resolve: (result: ChatProviderResult) => void;
+  reject: (error: unknown) => void;
+  receivedSignals: (AbortSignal | undefined)[];
+} {
+  const receivedSignals: (AbortSignal | undefined)[] = [];
+  let resolveFn: (result: ChatProviderResult) => void = () => undefined;
+  let rejectFn: (error: unknown) => void = () => undefined;
+
+  const provider: ChatProvider = {
+    id: 'controllable-test-provider',
+    send: (_request: ChatProviderRequest, options?: ChatProviderRequestOptions) => {
+      receivedSignals.push(options?.signal);
+      return new Promise<ChatProviderResult>((resolve, reject) => {
+        resolveFn = resolve;
+        rejectFn = reject;
+        options?.signal?.addEventListener('abort', () => {
+          reject(new ChatProviderError('PROVIDER_ABORTED', 'aborted by wrapped provider'));
+        });
+      });
+    },
+  };
+
+  return {
+    provider,
+    resolve: (result) => {
+      resolveFn(result);
+    },
+    reject: (error) => {
+      rejectFn(error);
+    },
+    receivedSignals,
+  };
+}
+
+describe('withProviderTimeout', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('preserves the wrapped provider id', () => {
+    const { provider } = controllableProvider();
+    const wrapped = withProviderTimeout(provider, 1000);
+    expect(wrapped.id).toBe(provider.id);
+  });
+
+  it('resolves normally when the provider answers within the budget', async () => {
+    const { provider, resolve } = controllableProvider();
+    const wrapped = withProviderTimeout(provider, 1000);
+
+    const promise = wrapped.send(EMPTY_REQUEST);
+    resolve({ content: 'on time' });
+
+    await expect(promise).resolves.toEqual({ content: 'on time' });
+  });
+
+  it('rejects with PROVIDER_TIMEOUT when the provider does not answer in time', async () => {
+    vi.useFakeTimers();
+    try {
+      const { provider } = controllableProvider(); // never resolved
+      const wrapped = withProviderTimeout(provider, 1000);
+
+      const promise = wrapped.send(EMPTY_REQUEST);
+      const assertion = expect(promise).rejects.toMatchObject({ code: 'PROVIDER_TIMEOUT' });
+
+      await vi.advanceTimersByTimeAsync(1500);
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('propagates the provider error unchanged when it fails before the timeout', async () => {
+    const { provider, reject } = controllableProvider();
+    const wrapped = withProviderTimeout(provider, 1000);
+
+    const promise = wrapped.send(EMPTY_REQUEST);
+    reject(new ChatProviderError('PROVIDER_REQUEST_FAILED', 'genuine failure'));
+
+    await expect(promise).rejects.toMatchObject({ code: 'PROVIDER_REQUEST_FAILED' });
+  });
+
+  it('forwards an external abort signal into the wrapped provider, reported as aborted, not timeout', async () => {
+    const { provider } = controllableProvider(); // wrapped provider rejects with PROVIDER_ABORTED on its own signal
+    const wrapped = withProviderTimeout(provider, 5000);
+    const external = new AbortController();
+
+    const promise = wrapped.send(EMPTY_REQUEST, { signal: external.signal });
+    external.abort();
+
+    await expect(promise).rejects.toMatchObject({ code: 'PROVIDER_ABORTED' });
+  });
+
+  it('does not wait out the timeout when the external signal is already aborted', async () => {
+    const { provider } = controllableProvider();
+    const wrapped = withProviderTimeout(provider, 5000);
+    const external = new AbortController();
+    external.abort();
+
+    await expect(wrapped.send(EMPTY_REQUEST, { signal: external.signal })).rejects.toMatchObject({
+      code: 'PROVIDER_ABORTED',
+    });
+  });
+
+  it('passes a combined signal to the wrapped provider, never the external signal directly', () => {
+    const { provider, receivedSignals } = controllableProvider();
+    const wrapped = withProviderTimeout(provider, 1000);
+    const external = new AbortController();
+
+    void wrapped.send(EMPTY_REQUEST, { signal: external.signal });
+
+    expect(receivedSignals[0]).not.toBe(external.signal);
+  });
+
+  it('never calls the global fetch function', async () => {
+    if (typeof globalThis.fetch !== 'function') return;
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+    const { provider, resolve } = controllableProvider();
+    const wrapped = withProviderTimeout(provider, 1000);
+
+    const promise = wrapped.send(EMPTY_REQUEST);
+    resolve({ content: 'ok' });
+    await promise;
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});