docs(P03): phase 3 shipped — checkpoint advances to phase 4

---ci---
phase: 3
milestone: v0.3
status: complete
requirements:
  covered: [REQ-75, REQ-76, REQ-77, REQ-78, REQ-79, REQ-80, REQ-81, REQ-82]
  partial: []
---/ci---

Ship record: PR #19 squash-merged phase/03-live-surfaces →
milestone/v0.3-hosted (b485fc0), tag v0.3.3, phase branch deleted
(local+remote), Gitea release v0.3.3 created. Gates green at the tag
(backend 314 passed + ruff + mypy; frontend 164 passed + tsc + build
+ drift). REQUIREMENTS traceability REQ-75..82 → complete; ROADMAP
P3 → complete, P4 (hosting) → next.

.ciagent/CHECKPOINT.json

@@ -1,8 +1,8 @@
 {
-  "phase": 1,
+  "phase": 3,
   "stage": "complete",
   "milestone": "v0.3",
   "phase_role": "execution",
   "attempts": 0,
-  "updated_at": "2026-09-29T21:40:00Z"
+  "updated_at": "2026-09-29T23:20:00Z"
 }

.ciagent/REQUIREMENTS.md

@@ -162,7 +162,7 @@
 | REQ-17, REQ-32, REQ-34 (adversarial, E2E, round-trip) | v0.2 | P4 | complete (v0.2.4) |
 | All REQ-01..34 (milestone gate) | v0.2 | P5 | complete (v0.2.5 — **owner approval recorded 2026-09-27**, G-009 ratified; milestone merged to main) |
 | REQ-69..71 (auth, sessions, scoping) | v0.3 | P1 | complete (v0.3.1; security review P0 register race + P1 corrupt-store fail-closed fixed in-phase; verify PASS 4/4) |
-| REQ-72..74 (settings, per-user keys, resolution chain) | v0.3 | P2 | pending |
-| REQ-76..82 (live surfaces, user-scoped) | v0.3 | P3 | pending |
-| REQ-75 (delegation-end half) + REQ-83..85 (hosting; live default hosted) | v0.3 | P3/P4 (REQ-75 split per G-103: delegation-end P3, hosted-default P4) | pending |
+| REQ-72..74 (settings, per-user keys, resolution chain) | v0.3 | P2 | complete (v0.3.2; P0 null-poisoning fixed in verify; P-1/P-2/P-13 closed; production main entrypoint P-3 backend half) |
+| REQ-76..82 (live surfaces, user-scoped) | v0.3 | P3 | complete (v0.3.3; D-112 standalone client, G-109 honest inbox, P-8 full closure, P-12 dead; verify PASS-WITH-FIXES) |
+| REQ-75 (delegation-end half) + REQ-83..85 (hosting; live default hosted) | v0.3 | P3/P4 (REQ-75 split per G-103: delegation-end P3 complete, hosted-default P4) | REQ-75 complete in P3 |
 | REQ-35..51 | v2 backlog (post-MVP milestones) | — | pending |

.ciagent/ROADMAP.md

@@ -152,14 +152,14 @@ Scope (owner session 2026-09-29): one milestone combining the G-009-ratified liv
 - **Requirements covered**: REQ-72, REQ-73, REQ-74
 - **Success criteria**: a keyed user gets fully real inference end-to-end; keys never appear in API responses (masked only), logs, or traces; resolution tier surfaced in config status; zero-key tests stay green via REQ-31 fakes
 - **Depends on**: 1
-- **Status**: pending
+- **Status**: complete (PR #18 squash-merged to milestone/v0.3-hosted ee26ff1, tag v0.3.2, release HTTP 201, phase branch deleted; verify PASS-WITH-FIXES — P0 settings null-poisoning fixed in-phase; 264 backend + 131 frontend tests)
 
 ### Phase 3 — Live Surfaces (user-scoped)
 - **Description**: Library read-model (GET /api/library), connections + graph (GET /api/library/connections, GET /api/graph), task inbox (GET /api/tasks), suggestions (GET /api/suggestions), refine (POST /api/refine/*, real planner calls), profile (GET/PUT /api/profile), live Reading Room fidelity (structured report, anchored citations, ledger panel). G-002 boundary lifted; frontend live swaps with zero component rewrites (REQ-54).
 - **Requirements covered**: REQ-76, REQ-77, REQ-78, REQ-79, REQ-80, REQ-81, REQ-82
 - **Success criteria**: every prototype surface works against real user data in live mode; suggestions/refine driven by real model calls; Reading Room parity with mock; ≤3-click path still green
 - **Depends on**: 2
-- **Status**: pending
+- **Status**: complete (PR #19 squash-merged to milestone/v0.3-hosted b485fc0, tag v0.3.3, release HTTP 201, phase branch deleted; verify PASS-WITH-FIXES — CSRF test pin P0 fixed; G-108 valve not needed; 314 backend + 164 frontend tests)
 
 ### Phase 4 — Hosting + Real-Inference Default
 - **Description**: Backend Dockerfile (single worker, non-root), two-service deployment via deploy.sh extension, SSE-safe HAProxy path routing (/api → backend, streaming timeouts), hosted instance runs live mode by default (mock demoted to dev/test fixture), auth guard verified through the public URL.

backend/pyproject.toml

@@ -10,6 +10,7 @@ dependencies = [
     "sse-starlette>=2.1,<3",
     "httpx>=0.27,<1",
     "argon2-cffi>=23.1,<26",
+    "cryptography>=43",
 ]
 
 [dependency-groups]

backend/src/researchx/adapters/model_factory.py

@@ -0,0 +1,163 @@
+"""Per-run model adapter factory (T-2.5, REQ-74 — D-110, P-2 closure).
+
+Resolves the per-run credential chain for the CURRENT user:
+
+    user key (decrypted per-user key store)  ->  tier "user"
+    server env-file OLLAMA_API_KEY           ->  tier "server"
+    neither (localhost:11434 fallback)       ->  tier "keyless"
+
+One adapter instance per ``resolve()`` call — NEVER cached across runs.
+The per-instance ``_active_base`` fallback mutation in
+OllamaModelAdapter is then per-run by construction, killing the
+shared-adapter bug where one user's cloud failure flipped every
+subsequent user's run to localhost.
+
+The keyless tier constructs an adapter with no key (no Authorization
+header is sent — see ollama.py) and the existing cloud→local fallback
+semantics are preserved: a keyless adapter starts on the cloud base
+and falls back on failure exactly as before, so localhost:11434
+remains the zero-cost path.
+
+Tampered/corrupt key-store envelopes surface as ``KeyStoreError`` (a
+typed ``AdapterError``) from ``resolve()`` — the caller decides how
+to present the honest error; the factory NEVER silently falls down the
+chain on a read failure (that would be a silent tier drop, C3-06).
+"""
+
+import hashlib
+
+from researchx.adapters.model import ModelRoles
+from researchx.adapters.ollama import OllamaModelAdapter
+from researchx.adapters.secrets import SecretsProvider
+from researchx.auth.key_store import KEY_SCOPE, KeyStore, KeyStoreError
+from researchx.auth.models import UserPublic
+from researchx.auth.settings import DEFAULT_PLANNER_MODEL, DEFAULT_WRITER_MODEL, UserSettings
+
+TIER_USER = "user"
+TIER_SERVER = "server"
+TIER_KEYLESS = "keyless"
+
+
+class ModelAdapterFactory:
+    """Resolve (adapter, tier) for a user's run — per call, never cached."""
+
+    def __init__(
+        self,
+        secrets: SecretsProvider,
+        key_store: KeyStore,
+        *,
+        planner_model: str = DEFAULT_PLANNER_MODEL,
+        writer_model: str = DEFAULT_WRITER_MODEL,
+        cloud_base_url: str | None = None,
+        local_base_url: str | None = None,
+    ) -> None:
+        self._secrets = secrets
+        self._key_store = key_store
+        self._planner_model = planner_model
+        self._writer_model = writer_model
+        self._cloud_base_url = cloud_base_url
+        self._local_base_url = local_base_url
+
+    def _construct(
+        self, planner: str, writer: str, api_key: str | None
+    ) -> OllamaModelAdapter:
+        return OllamaModelAdapter(
+            self._secrets,
+            planner_model=planner,
+            writer_model=writer,
+            cloud_base_url=self._cloud_base_url,
+            local_base_url=self._local_base_url,
+            api_key=api_key,
+        )
+
+    async def resolve(
+        self, user: UserPublic, settings: UserSettings
+    ) -> tuple[OllamaModelAdapter, str]:
+        """Resolve the user's credential chain and build ONE adapter.
+
+        The adapter's roles honor the user's saved settings
+        (planner_model/writer_model); an unset settings value keeps the
+        factory defaults. Raises ``KeyStoreError`` (an AdapterError)
+        when the user's stored envelope is tampered/corrupt — never a
+        silent tier drop.
+        """
+        planner = settings.planner_model or self._planner_model
+        writer = settings.writer_model or self._writer_model
+
+        if self._key_store.enabled:
+            # get_key raises KeyStoreError on tamper — honest error, not
+            # a silent fall to server/keyless.
+            user_key = await self._key_store.get_key(user.user_id)
+            if user_key:
+                return self._construct(planner, writer, user_key), TIER_USER
+
+        server_key = self._secrets.resolve(KEY_SCOPE)
+        if server_key:
+            return self._construct(planner, writer, server_key), TIER_SERVER
+
+        return self._construct(planner, writer, None), TIER_KEYLESS
+
+    async def resolve_status(
+        self, user: UserPublic, settings: UserSettings
+    ) -> tuple[OllamaModelAdapter, str, str | None]:
+        """Status variant for GET /api/config: like resolve() but a
+        tampered/corrupt key-store read DEGRADES down the chain and
+        returns the honest error message instead of raising — the
+        config status must never 500 on a corrupt envelope, and the
+        tier must never silently claim 'user' when the key cannot be
+        decrypted. create_run keeps the raising resolve() (a corrupt
+        key there is an honest 409 failure).
+        """
+        error: str | None = None
+        planner = settings.planner_model or self._planner_model
+        writer = settings.writer_model or self._writer_model
+
+        if self._key_store.enabled:
+            try:
+                user_key = await self._key_store.get_key(user.user_id)
+            except KeyStoreError as exc:
+                # Honest degradation: the tier falls to server/keyless
+                # but the error message is carried alongside — surfaced
+                # by the config status so the user can see WHY.
+                user_key = None
+                error = str(exc)
+            if user_key:
+                return self._construct(planner, writer, user_key), TIER_USER, None
+
+        server_key = self._secrets.resolve(KEY_SCOPE)
+        if server_key:
+            return self._construct(planner, writer, server_key), TIER_SERVER, error
+
+        return self._construct(planner, writer, None), TIER_KEYLESS, error
+
+    async def key_fingerprint(self, user: UserPublic) -> str:
+        """Stable per-(user, tier, key) probe-cache key component.
+
+        The raw key is NEVER the fingerprint — a short sha256 of the
+        effective key (or the tier itself when keyless) identifies the
+        resolution without exposing material. A key-store read error
+        yields the server/keyless fingerprint; the probe itself will
+        surface the error state through the config status.
+        """
+        if self._key_store.enabled:
+            try:
+                user_key = await self._key_store.get_key(user.user_id)
+            except KeyStoreError:
+                user_key = None
+            if user_key:
+                return f"{TIER_USER}:{hashlib.sha256(user_key.encode()).hexdigest()[:12]}"
+        server_key = self._secrets.resolve(KEY_SCOPE)
+        if server_key:
+            return f"{TIER_SERVER}:{hashlib.sha256(server_key.encode()).hexdigest()[:12]}"
+        return TIER_KEYLESS
+
+    def roles_defaults(self) -> ModelRoles:
+        return ModelRoles(planner=self._planner_model, writer=self._writer_model)
+
+
+__all__ = [
+    "TIER_KEYLESS",
+    "TIER_SERVER",
+    "TIER_USER",
+    "ModelAdapterFactory",
+]

backend/src/researchx/adapters/ollama.py

@@ -3,7 +3,7 @@ from typing import Any
 import httpx
 
 from researchx.adapters.model import ModelRoles
-from researchx.adapters.secrets import EnvFileSecretsProvider
+from researchx.adapters.secrets import SecretsProvider
 from researchx.adapters.types import AdapterError, ChatResult, ModelMessage, Usage
 
 _DEFAULT_CLOUD_BASE = "https://ollama.com/v1"
@@ -16,18 +16,22 @@ class OllamaModelAdapter:
 
     def __init__(
         self,
-        secrets: EnvFileSecretsProvider,
+        secrets: SecretsProvider,
         planner_model: str,
         writer_model: str,
         cloud_base_url: str | None = None,
         local_base_url: str | None = None,
+        api_key: str | None = None,
     ) -> None:
         self._secrets = secrets
         self._roles = ModelRoles(planner=planner_model, writer=writer_model)
         self._cloud_base = (cloud_base_url or secrets.resolve("OLLAMA_BASE_URL") or _DEFAULT_CLOUD_BASE).rstrip("/")
         self._local_base = (local_base_url or _DEFAULT_LOCAL_BASE).rstrip("/")
         self._active_base = self._cloud_base
-        self._api_key = secrets.resolve("OLLAMA_API_KEY")
+        # Explicit api_key takes precedence over the secrets resolve
+        # (T-2.5: the per-run factory passes the user's decrypted key);
+        # the secrets path stays for back-compat (server tier).
+        self._api_key = api_key if api_key is not None else secrets.resolve("OLLAMA_API_KEY")
         self._last_fallback_reason: str | None = None
 
     def _headers(self, base_url: str) -> dict[str, str]:
@@ -99,12 +103,19 @@ class OllamaModelAdapter:
                     raise AdapterError(f"models listing failed ({type(exc).__name__})") from exc
                 data: dict[str, Any] = response.json()
             return [str(entry["id"]) for entry in data.get("data", [])]
-        except (AdapterError, httpx.HTTPError):
-            if self._active_base == self._cloud_base:
+        except (AdapterError, httpx.HTTPError) as exc:
+            # Fallback only if there IS a distinct local base to fall
+            # back to (a caller pinning both bases to one endpoint —
+            # e.g. a private gateway — must not recurse forever), and
+            # never leak a raw httpx error: the adapter's outward
+            # contract is a typed AdapterError.
+            if self._active_base == self._cloud_base and self._local_base != self._cloud_base:
                 self._last_fallback_reason = "cloud models listing failed; using local"
                 self._active_base = self._local_base
                 return await self.list_models()
-            raise
+            if isinstance(exc, AdapterError):
+                raise
+            raise AdapterError(f"models listing failed ({type(exc).__name__})") from exc
 
     def roles(self) -> ModelRoles:
         return self._roles

backend/src/researchx/api/app.py

@@ -1,4 +1,6 @@
 import asyncio
+import json
+import time
 from collections.abc import AsyncIterator
 from pathlib import Path
 from typing import Annotated, Any
@@ -11,13 +13,17 @@ from sse_starlette.sse import EventSourceResponse
 from researchx.adapters.capability_probe import probe_model_adapter, supports_probe
 from researchx.adapters.fakes import CORPUS, FakeModelAdapter, FakeSearchAdapter
 from researchx.adapters.local_storage import LocalStorageAdapter
-from researchx.adapters.types import AdapterError, ChatResult
+from researchx.adapters.model_factory import ModelAdapterFactory
+from researchx.adapters.types import AdapterError, ChatResult, ModelMessage
+from researchx.api.read_models import connections, graph, library, list_runs, suggestions, tasks
 from researchx.auth.admin_routes import build_admin_router
 from researchx.auth.guard import Guard, build_admin_guard, build_dev_guard, build_guard
-from researchx.auth.models import UserPublic
+from researchx.auth.key_store import KEY_SCOPE, KeyStore, KeyStoreError
+from researchx.auth.models import _EMAIL_RE, UserPublic
 from researchx.auth.routes import build_auth_router
 from researchx.auth.sessions import SessionStore
-from researchx.auth.users import UserStore
+from researchx.auth.settings import SettingsStore, SettingsStoreError, UserSettings
+from researchx.auth.users import UserError, UserStore
 from researchx.config.paths import data_root
 from researchx.engine.actor import RunActor, make_run_config
 from researchx.engine.events import EventBus, RunEvent
@@ -36,6 +42,10 @@ _CANNED_WRITER = (
 
 _CORS_ORIGINS = ["http://localhost:3000", "http://127.0.0.1:3000"]
 
+# Config-status probe cache TTL (P-1): in-process, keyed
+# (user_id, tier, key_fingerprint) so a key change invalidates.
+_PROBE_CACHE_TTL_SECONDS = 60.0
+
 
 class CreateRunBody(BaseModel):
     question: str = Field(min_length=1, max_length=2000)
@@ -48,6 +58,42 @@ class ApproveBody(BaseModel):
     plan: dict[str, Any] | None = None
 
 
+class SettingsBody(BaseModel):
+    """PUT /api/config/settings body — partial update (D-111)."""
+
+    planner_model: str | None = Field(default=None, min_length=1, max_length=200)
+    writer_model: str | None = Field(default=None, min_length=1, max_length=200)
+    methodology_defaults: dict[str, Any] | None = None
+    appearance: str | None = Field(default=None, max_length=40)
+
+
+class ModelKeyBody(BaseModel):
+    """PUT /api/config/settings/model-key body — the raw key, accepted,
+    never echoed (REQ-73)."""
+
+    key: str = Field(min_length=1, max_length=512)
+
+
+class KeyStatus(BaseModel):
+    """Masked-only key status — the raw key NEVER appears (REQ-73)."""
+
+    configured: bool
+    masked: str | None = None
+    disabled: bool = False
+    reason: str | None = None
+
+
+class ConfigStatus(BaseModel):
+    resolved_tier: str  # user | server | keyless (REQ-74)
+    key_store: str  # enabled | disabled
+    key_status: KeyStatus
+    model_adapter: str
+    search_adapter: str
+    storage_dir: str
+    probe: dict[str, Any] | None = None
+    cost_counters: dict[str, int]
+
+
 class RunSummary(BaseModel):
     id: str
     status: str
@@ -68,14 +114,6 @@ class MethodologyCard(BaseModel):
     dials: dict[str, Any]
 
 
-class ConfigStatus(BaseModel):
-    model_adapter: str
-    search_adapter: str
-    storage_dir: str
-    probe: dict[str, Any] | None = None
-    cost_counters: dict[str, int]
-
-
 _STATUS_MAP = {
     RunStateName.PLANNING: "planning",
     RunStateName.AWAITING_APPROVAL: "awaiting_approval",
@@ -222,6 +260,10 @@ def create_app(
     auth_enabled: bool = True,
     cookie_secure: bool = False,
     data_dir: Path | None = None,
+    key_store: KeyStore | None = None,
+    settings_store: SettingsStore | None = None,
+    model_factory: ModelAdapterFactory | None = None,
+    secrets_provider: Any = None,
 ) -> FastAPI:
     """Build the ResearchX API app.
 
@@ -230,6 +272,14 @@ def create_app(
     dev admin for every request so zero-key suites keep working.
     ``data_dir`` overrides the auth-store location (defaults to
     ``data_root()``); ``storage_dir`` remains the run-artifact base.
+
+    Per-user stores (T-2.2/T-2.3): ``key_store`` defaults to a KeyStore
+    over the data root (disabled when no KEK is configured — honest
+    degradation); ``settings_store`` likewise. Both are injectable for
+    tests. ``model_factory`` (T-2.5) resolves the per-user credential
+    chain user → server → keyless for ``create_run`` and
+    ``GET /api/config``; when absent the fixed ``model_adapter`` is
+    used (test harness), tiered resolution disabled by construction.
     """
     app = FastAPI(title="ResearchX API", version="0.2.0")
 
@@ -237,21 +287,44 @@ def create_app(
     # overrides for tests); auth stores always share the same root.
     storage_base = storage_dir if storage_dir is not None else data_root()
     runs = RunRegistry()
-    model = model_adapter or FakeModelAdapter(
-        canned=[
-            ChatResult(content=_CANNED_PLAN, model="fake-planner"),
-            ChatResult(content=_CANNED_WRITER, model="fake-writer"),
-        ]
-    )
+    # The fallback model is constructed ONLY when no factory is wired:
+    # the factory path (production, T-2.5) resolves a real adapter per
+    # run and the production entrypoint can therefore never hold a
+    # FakeModelAdapter in memory (P-3).
+    model: Any
+    if model_adapter is not None:
+        model = model_adapter
+    elif model_factory is not None:
+        model = None  # every consumer goes through the factory
+    else:
+        model = FakeModelAdapter(
+            canned=[
+                ChatResult(content=_CANNED_PLAN, model="fake-planner"),
+                ChatResult(content=_CANNED_WRITER, model="fake-writer"),
+            ]
+        )
     search = search_adapter or FakeSearchAdapter(CORPUS)
 
     auth_root = data_dir if data_dir is not None else data_root()
     users = UserStore(auth_root / "users.json")
     sessions = SessionStore(auth_root / "sessions.json")
 
+    # Per-user stores wired from the same root as the auth stores;
+    # injectable for tests (key_store=None -> disabled, honest reason).
+    key_store = key_store if key_store is not None else KeyStore(
+        secrets_provider or _NullSecrets(), auth_root
+    )
+    settings_store = settings_store if settings_store is not None else SettingsStore(auth_root)
+
     guard: Guard = build_guard(users, sessions) if auth_enabled else build_dev_guard()
     admin_guard = build_admin_guard(guard)
 
+    # In-process probe cache keyed (user_id, tier, key_fingerprint)
+    # with a short TTL (P-1 closure — the probe runs against the
+    # RESOLVED tier, never stolen from the registry, and a key change
+    # rotates the fingerprint which invalidates the entry).
+    probe_cache: dict[tuple[str, str, str], tuple[float, dict[str, Any] | None]] = {}
+
     def _owner_storage(user: UserPublic) -> LocalStorageAdapter:
         """Owner-scoped storage, constructed per request from the auth
         dependency (REQ-71): runs/<user_id>/<run_id>/."""
@@ -269,6 +342,24 @@ def create_app(
             started_at=state.created_at.isoformat(),
         )
 
+    async def _masked_key_status(user: UserPublic) -> KeyStatus:
+        """Masked-only key status — never the raw key (REQ-73)."""
+        try:
+            status = await key_store.masked_status(user.user_id)
+        except KeyStoreError as exc:
+            # Stored-but-unreadable: surface the error state honestly.
+            return KeyStatus(
+                configured=False, masked=None, disabled=not key_store.enabled, reason=str(exc)
+            )
+        masked = status.get("masked")
+        reason = status.get("reason")
+        return KeyStatus(
+            configured=bool(status.get("configured")),
+            masked=str(masked) if masked is not None else None,
+            disabled=bool(status.get("disabled")),
+            reason=str(reason) if reason is not None else None,
+        )
+
     # ------------------------------------------------------------------
     # PUBLIC surface: /healthz outside /api (D-103 — plain GET for the
     # TLS-front proxy, never auth-wrapped) + /api/auth/* (no
@@ -289,20 +380,103 @@ def create_app(
 
     protected.include_router(build_admin_router(users, sessions, admin_guard))
 
-    @protected.get("/api/config")
+    @protected.get("/api/config", response_model=ConfigStatus)
     async def config_status(user: Annotated[UserPublic, Depends(guard)]) -> ConfigStatus:
-        latest_probe = None
-        for owner_and_run in list(runs._actors)[-1:]:
-            if owner_and_run[0] == user.user_id:
-                latest_probe = runs.actor(*owner_and_run).state.probe
+        """Current user's resolved credential tier + status (T-2.6).
+
+        P-1 closure: the probe is resolved via the factory for the
+        CURRENT user — no run creation, no reads of the private
+        registry dict, correct with zero runs, no cross-user leak.
+        A corrupt/tampered stored envelope degrades the tier honestly
+        (server/keyless) and surfaces the error in key_status.reason —
+        never a 500, never a silent drop.
+        """
+        tier = "keyless"
+        adapter_name = type(model).__name__ if model is not None else "unknown"
+        probe: dict[str, Any] | None = None
+        resolve_error: str | None = None
+
+        if model_factory is not None:
+            settings = await settings_store.get(user.user_id)
+            adapter, tier, resolve_error = await model_factory.resolve_status(user, settings)
+            adapter_name = type(adapter).__name__
+            fingerprint = await model_factory.key_fingerprint(user)
+            cache_key = (user.user_id, tier, fingerprint)
+            now = time.monotonic()
+            cached = probe_cache.get(cache_key)
+            if cached is not None and now - cached[0] < _PROBE_CACHE_TTL_SECONDS:
+                probe = cached[1]
+            elif supports_probe(adapter):
+                try:
+                    probe_result = await probe_model_adapter(adapter)
+                    probe = probe_result.model_dump(mode="json")
+                    probe_cache[cache_key] = (now, probe)
+                except AdapterError:
+                    probe = None
+                    probe_cache[cache_key] = (now, None)
+        key_status = await _masked_key_status(user)
+        if resolve_error is not None and key_status.reason is None:
+            # The tier degraded honestly; say WHY (never silently).
+            key_status = key_status.model_copy(update={"reason": resolve_error})
         return ConfigStatus(
-            model_adapter=type(model).__name__,
+            resolved_tier=tier,
+            key_store="enabled" if key_store.enabled else "disabled",
+            key_status=key_status,
+            model_adapter=adapter_name,
             search_adapter=type(search).__name__,
             storage_dir=str(storage_base),
-            probe=latest_probe,
+            probe=probe,
             cost_counters=runs.completed_snapshot(user.user_id),
         )
 
+    @protected.get("/api/config/settings", response_model=UserSettings)
+    async def get_settings(user: Annotated[UserPublic, Depends(guard)]) -> UserSettings:
+        return await settings_store.get(user.user_id)
+
+    @protected.put("/api/config/settings", response_model=UserSettings)
+    async def put_settings(
+        body: SettingsBody, user: Annotated[UserPublic, Depends(guard)]
+    ) -> UserSettings:
+        """Persist a partial settings update (REQ-72); returns the
+        updated settings. An explicit null field is treated as absent
+        (partial-merge semantics — the store refuses null-valued
+        fields, so a null can never poison the on-disk payload)."""
+        updates: dict[str, Any] = {
+            key: value
+            for key, value in body.model_dump(exclude_unset=True).items()
+            if value is not None
+        }
+        try:
+            current = await settings_store.get(user.user_id)
+            merged = current.model_copy(update=updates)
+            return await settings_store.update(user.user_id, merged)
+        except SettingsStoreError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    @protected.put("/api/config/settings/model-key", response_model=KeyStatus)
+    async def put_model_key(
+        body: ModelKeyBody, user: Annotated[UserPublic, Depends(guard)]
+    ) -> KeyStatus:
+        """Accept the user's raw model key, encrypt it at rest, return
+        ONLY the masked status (REQ-73 — the raw key never appears in
+        any response, log, or trace). Without a KEK: honest 409."""
+        if not key_store.enabled:
+            # Honest refusal, never a silent no-op.
+            raise HTTPException(
+                status_code=409,
+                detail={
+                    "key_store": "disabled",
+                    "reason": key_store.disabled_reason,
+                },
+            )
+        await key_store.set_key(user.user_id, KEY_SCOPE, body.key)
+        return await _masked_key_status(user)
+
+    @protected.get("/api/config/settings/model-key", response_model=KeyStatus)
+    async def get_model_key_status(user: Annotated[UserPublic, Depends(guard)]) -> KeyStatus:
+        """Masked-only key status (never the raw key)."""
+        return await _masked_key_status(user)
+
     @protected.get("/api/methodologies")
     async def methodologies() -> list[MethodologyCard]:
         cards: list[MethodologyCard] = []
@@ -327,6 +501,24 @@ def create_app(
         if body.methodology not in registry:
             raise HTTPException(status_code=404, detail="unknown methodology")
         storage = _owner_storage(user)
+
+        # Per-run credential resolution (T-2.5, REQ-74): one adapter
+        # instance per run — the _active_base fallback mutation is
+        # per-instance by construction (P-2 closure).
+        tier: str | None = None
+        if model_factory is not None:
+            settings = await settings_store.get(user.user_id)
+            try:
+                run_model, tier = await model_factory.resolve(user, settings)
+            except KeyStoreError as exc:
+                # A tampered/corrupt stored key is an honest failure —
+                # never a silent tier drop and never a wrong-key run.
+                raise HTTPException(status_code=409, detail=str(exc)) from exc
+        else:
+            # No factory: the fixed test-harness adapter (create_app
+            # guarantees one exists whenever the factory is absent).
+            run_model = model
+
         try:
             run_id, config = make_run_config(
                 question=body.question,
@@ -343,7 +535,7 @@ def create_app(
         bus = EventBus()
         actor = RunActor(
             run_config=config,
-            model=model,
+            model=run_model,
             search=search,
             storage=storage,
             registry=registry,
@@ -352,9 +544,10 @@ def create_app(
         # Stamp the owner on the persisted state (REQ-71). The actor
         # itself is untouched — engine contracts unchanged.
         actor.state.owner_id = user.user_id
-        if supports_probe(model):
+        actor.state.credential_tier = tier  # REQ-74: auditability
+        if supports_probe(run_model):
             try:
-                probe = await probe_model_adapter(model)
+                probe = await probe_model_adapter(run_model)
                 await actor.attach_probe(probe.model_dump(mode="json"))
             except AdapterError:
                 pass
@@ -466,27 +659,240 @@ def create_app(
 
     @protected.get("/api/runs/{run_id}/report")
     async def run_report(run_id: str, user: Annotated[UserPublic, Depends(guard)]) -> dict[str, Any]:
-        if not runs.has(user.user_id, run_id):
+        """Disk-read, registry-independent (P-8 full closure, T-3.3):
+        the run directory under THIS owner is the existence check — no
+        RunRegistry involvement, correct after a restart with zero
+        in-memory actors. Pre-artifact DONE runs (and any run whose
+        report.json was not yet written) fall back to markdown-only
+        with null report/evidence — never a 500 (D-106: old artifacts
+        disposable)."""
+        storage = _owner_storage(user)
+        if not (storage.run_dir(run_id)).is_dir():
             raise HTTPException(status_code=404, detail="run not found")
         try:
-            content = await _owner_storage(user).read_run_artifact(run_id, "report.md")
+            markdown = await storage.read_run_artifact(run_id, "report.md")
         except AdapterError:
             raise HTTPException(status_code=404, detail="report not ready")
-        return {"run_id": run_id, "markdown": content}
+        report: dict[str, Any] | None = None
+        evidence: dict[str, Any] | None = None
+        try:
+            parsed = json.loads(await storage.read_run_artifact(run_id, "report.json"))
+            if isinstance(parsed, dict):
+                report = parsed
+        except (AdapterError, json.JSONDecodeError):
+            pass
+        try:
+            parsed = json.loads(await storage.read_run_artifact(run_id, "evidence.json"))
+            if isinstance(parsed, dict):
+                evidence = parsed
+        except (AdapterError, json.JSONDecodeError):
+            pass
+        return {"run_id": run_id, "markdown": markdown, "report": report, "evidence": evidence}
 
     @protected.get("/api/runs/{run_id}/ledger")
     async def run_ledger(run_id: str, user: Annotated[UserPublic, Depends(guard)]) -> dict[str, Any]:
-        if not runs.has(user.user_id, run_id):
+        """Disk-read, registry-independent (T-3.3): same owner-dir
+        existence check as the report route."""
+        storage = _owner_storage(user)
+        if not (storage.run_dir(run_id)).is_dir():
             raise HTTPException(status_code=404, detail="run not found")
         try:
-            content = await _owner_storage(user).read_run_artifact(run_id, "ledger.json")
+            content = await storage.read_run_artifact(run_id, "ledger.json")
         except AdapterError:
             raise HTTPException(status_code=404, detail="ledger not ready")
-        import json
-
         data: dict[str, Any] = json.loads(content)
         return data
 
+    # ------------------------------------------------------------- T-3.2/T-3.3
+    # Live surfaces (REQ-76..79): read-model routes — disk reads only,
+    # owner-scoped via the guard, NEVER the in-memory RunRegistry
+    # (D-115). Every route below is correct after a restart with zero
+    # in-process actors (P-8 full closure, pinned by test).
+
+    @protected.get("/api/runs")
+    async def list_runs_route(user: Annotated[UserPublic, Depends(guard)]) -> list[RunSummary]:
+        """All of this owner's runs from disk state files, most recent
+        first — the registry-independent run list (post-sweep
+        CANCELLED runs surface cancelled, NOT open)."""
+        records = list_runs(storage_base, user.user_id)
+        summaries: list[RunSummary] = []
+        for record in records:
+            plan = record.state.get("plan")
+            summaries.append(
+                RunSummary(
+                    id=record.run_id,
+                    status=_STATUS_MAP.get(RunStateName(record.status), "failed"),
+                    question=record.question,
+                    methodology=record.methodology_slug,
+                    plan=plan if isinstance(plan, dict) else None,
+                    started_at=record.created_at,
+                )
+            )
+        return summaries
+
+    @protected.get("/api/library")
+    async def library_route(
+        user: Annotated[UserPublic, Depends(guard)], sort: str = "recent"
+    ) -> dict[str, Any]:
+        return library(storage_base, user.user_id, sort=sort)
+
+    @protected.get("/api/library/connections")
+    async def connections_route(user: Annotated[UserPublic, Depends(guard)]) -> list[dict[str, Any]]:
+        return connections(storage_base, user.user_id)
+
+    @protected.get("/api/graph")
+    async def graph_route(user: Annotated[UserPublic, Depends(guard)]) -> dict[str, Any]:
+        return graph(storage_base, user.user_id)
+
+    @protected.get("/api/tasks")
+    async def tasks_route(user: Annotated[UserPublic, Depends(guard)]) -> list[dict[str, str]]:
+        return tasks(storage_base, user.user_id)
+
+    @protected.get("/api/suggestions")
+    async def suggestions_route(
+        user: Annotated[UserPublic, Depends(guard)]
+    ) -> list[dict[str, str]]:
+        return suggestions(storage_base, user.user_id)
+
+    # ------------------------------------------------------------- T-3.6
+    # Refine + profile (REQ-80/81). The refine planner calls ride the
+    # SAME per-user credential chain as runs (P2 factory); an
+    # unavailable model is an honest 503, never a hang.
+
+    class RefineDraftBody(BaseModel):
+        draft: str = Field(min_length=1, max_length=2000)
+
+    class RefineComposeBody(BaseModel):
+        draft: str = Field(min_length=1, max_length=2000)
+        answers: list[str] = Field(default_factory=list, max_length=10)
+
+    _REFINE_QUESTIONS_PROMPT = (
+        "You are a research question refiner. The user drafted a research "
+        "question. Reply with a JSON object {{\"questions\": [...]}} holding "
+        "exactly three short clarifying questions that would sharpen the "
+        "draft. No commentary, JSON only.\nDraft: {draft}"
+    )
+    _REFINE_COMPOSE_PROMPT = (
+        "You are a research question refiner. The user drafted a research "
+        "question and answered clarifying questions. Compose the refined "
+        "research question and a short suggested-context paragraph. Reply "
+        "with a JSON object {{\"question\": \"...\", \"context\": \"...\"}}, "
+        "JSON only.\nDraft: {draft}\nAnswers: {answers}"
+    )
+
+    def _parse_refine_json(content: str) -> dict[str, Any]:
+        try:
+            parsed = json.loads(content)
+        except json.JSONDecodeError as exc:
+            raise AdapterError("refine planner returned non-JSON") from exc
+        if not isinstance(parsed, dict):
+            raise AdapterError("refine planner returned non-JSON")
+        return parsed
+
+    async def _refine_model(user: UserPublic) -> tuple[Any, str]:
+        """Resolve the per-user adapter for a refine call — the same
+        chain as create_run (user -> server -> keyless), one fresh
+        adapter instance per call (P-2)."""
+        if model_factory is not None:
+            settings = await settings_store.get(user.user_id)
+            run_model, tier = await model_factory.resolve(user, settings)
+            return run_model, tier
+        if model is None:  # factory wired but absent — impossible via create_app
+            raise AdapterError("no model adapter available")
+        return model, "keyless"
+
+    @protected.post("/api/refine/questions")
+    async def refine_questions(
+        body: RefineDraftBody, user: Annotated[UserPublic, Depends(guard)]
+    ) -> dict[str, Any]:
+        draft = body.draft.strip()
+        if not draft:
+            raise HTTPException(status_code=422, detail="draft must not be empty")
+        try:
+            adapter, _tier = await _refine_model(user)
+            result = await adapter.chat(
+                [ModelMessage(role="user", content=_REFINE_QUESTIONS_PROMPT.format(draft=draft))],
+                model=adapter.roles().planner,
+                json_mode=True,
+            )
+        except AdapterError as exc:
+            # Honest 503 (T-3.6): the resolved tier is unavailable —
+            # never a hang, never a silent success.
+            raise HTTPException(status_code=503, detail=str(exc)) from exc
+        parsed = _parse_refine_json(result.content)
+        raw = parsed.get("questions", [])
+        questions = [str(q).strip() for q in raw if str(q).strip()] if isinstance(raw, list) else []
+        if not questions:
+            raise HTTPException(status_code=503, detail="refine planner returned no questions")
+        return {"questions": questions[:3]}
+
+    @protected.post("/api/refine/compose")
+    async def refine_compose(
+        body: RefineComposeBody, user: Annotated[UserPublic, Depends(guard)]
+    ) -> dict[str, str]:
+        draft = body.draft.strip()
+        if not draft:
+            raise HTTPException(status_code=422, detail="draft must not be empty")
+        answers = [str(a).strip() for a in body.answers if str(a).strip()]
+        try:
+            adapter, _tier = await _refine_model(user)
+            result = await adapter.chat(
+                [
+                    ModelMessage(
+                        role="user",
+                        content=_REFINE_COMPOSE_PROMPT.format(
+                            draft=draft, answers=json.dumps(answers)
+                        ),
+                    )
+                ],
+                model=adapter.roles().planner,
+                json_mode=True,
+            )
+        except AdapterError as exc:
+            raise HTTPException(status_code=503, detail=str(exc)) from exc
+        parsed = _parse_refine_json(result.content)
+        question = str(parsed.get("question", "")).strip()
+        if not question:
+            raise HTTPException(status_code=503, detail="refine planner returned no question")
+        return {"question": question, "context": str(parsed.get("context", "")).strip()}
+
+    # ------------------------------------------------------------- profile
+
+    class ProfileBody(BaseModel):
+        display_name: str | None = Field(default=None, min_length=1, max_length=120)
+        email: str | None = Field(default=None, pattern=_EMAIL_RE, max_length=254)
+
+    @protected.get("/api/profile")
+    async def get_profile(user: Annotated[UserPublic, Depends(guard)]) -> dict[str, str]:
+        return {
+            "user_id": user.user_id,
+            "display_name": user.display_name,
+            "email": user.email,
+        }
+
+    @protected.put("/api/profile")
+    async def put_profile(
+        body: ProfileBody, user: Annotated[UserPublic, Depends(guard)]
+    ) -> dict[str, str]:
+        """Update display name and/or email (no deletion, REQ-81).
+        The email stays unique (casefolded) across other users."""
+        stored = users.get(user.user_id)
+        if stored is None:
+            raise HTTPException(status_code=401, detail="account disabled")
+        try:
+            updated = await users.update_profile(
+                user.user_id,
+                display_name=body.display_name,
+                email=body.email,
+            )
+        except UserError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        return {
+            "user_id": updated.user_id,
+            "display_name": updated.display_name,
+            "email": updated.email,
+        }
+
     app.include_router(public)
     app.include_router(protected)
 
@@ -512,8 +918,17 @@ def create_app(
 
     return app
 
+
+class _NullSecrets:
+    """No-secrets provider: the default key store is disabled unless a
+    secrets provider is injected (zero-key test harness stays green)."""
+
+    def resolve(self, name: str) -> str | None:
+        return None
+
+
 # Dev-only module app (README's `uvicorn researchx.api.app:app`).
 # Pitfall P-12/§8 item 3: this serves FAKES with default storage —
 # the production entrypoint (researchx.api.main, Phase 2) must never
 # import this global. Single worker only (in-memory stores by design).
-app = create_app()
+app = create_app()

backend/src/researchx/api/main.py

@@ -0,0 +1,87 @@
+"""Production entrypoint (T-2.7 — P-3 backend closure).
+
+``uvicorn researchx.api.main:app`` — the ONLY serving entry the
+container ever runs (T-4.1). Distinct from ``researchx.api.app`` (the
+test/dev factory, whose module-global serves fakes):
+
+- ``auth_enabled=True`` is HARDWIRED — not a parameter here, never an
+  env var, never False on any path that serves traffic (REQ-85).
+- ``cookie_secure=True`` (E-4 handoff): the cookie is set with Secure
+  because the public surface sits behind the TLS-fronted proxy.
+- Run artifacts + auth stores + key store + settings live under
+  ``RESEARCHX_DATA_DIR`` (container default ``/var/lib/researchx``,
+  D-107) — never cwd-dependent.
+- Secrets come from the runtime env file (``.ciagent/.env.secrets``
+  by default, overridable via ``RESEARCHX_SECRETS_FILE``; the
+  container passes its own env-file via ``--env-file``):
+  ``RESEARCHX_KEK`` (keys scope) enables the per-user key store,
+  ``OLLAMA_API_KEY`` the server tier, ``TAVILY_API_KEY`` keyed search.
+- The model adapter is ALWAYS the real OllamaModelAdapter, constructed
+  per run by the ModelAdapterFactory — this module can never serve
+  FakeModelAdapter (pinned by test_main_entrypoint).
+- Search: TavilySearchAdapter when TAVILY_API_KEY is present, else the
+  documented keyless DuckDuckGo fallback (degraded mode — G-008).
+- Single uvicorn worker only (in-memory RunRegistry + session store).
+"""
+
+from pathlib import Path
+
+from fastapi import FastAPI
+
+from researchx.adapters.duckduckgo import resolve_search_adapter
+from researchx.adapters.model_factory import ModelAdapterFactory
+from researchx.adapters.secrets import EnvFileSecretsProvider
+from researchx.api.app import create_app
+from researchx.auth.key_store import KeyStore
+from researchx.auth.settings import SettingsStore
+from researchx.config.paths import data_root
+
+_DEFAULT_SECRETS_PATHS = [
+    Path("/etc/researchx/env.secrets"),  # container convention (runtime bind)
+    Path.cwd() / ".ciagent" / ".env.secrets",  # repo-local dev
+    Path.cwd().parents[1] / ".ciagent" / ".env.secrets",  # tests run from backend/
+]
+
+
+def _secrets_paths() -> list[Path]:
+    """Runtime env-file candidates (first existing wins per merge order)."""
+    import os
+
+    override = os.environ.get("RESEARCHX_SECRETS_FILE")
+    if override:
+        return [Path(override)]
+    return [p for p in _DEFAULT_SECRETS_PATHS if p.is_file()] or _DEFAULT_SECRETS_PATHS
+
+
+def build_app() -> FastAPI:
+    """Build the LIVE app: real adapters, real auth, data-root storage.
+
+    ``auth_enabled`` and ``cookie_secure`` are not parameters — they
+    are the production posture, fixed here (C3-16/REQ-85).
+    """
+    secrets = EnvFileSecretsProvider(paths=_secrets_paths())
+    root = data_root()
+
+    key_store = KeyStore(secrets, root)
+    settings_store = SettingsStore(root)
+    factory = ModelAdapterFactory(secrets, key_store)
+
+    # Tavily when keyed, documented keyless DuckDuckGo otherwise (G-008).
+    search, _search_name = resolve_search_adapter(secrets)
+
+    return create_app(
+        storage_dir=root,
+        data_dir=root,
+        search_adapter=search,
+        secrets_provider=secrets,
+        key_store=key_store,
+        settings_store=settings_store,
+        model_factory=factory,
+        auth_enabled=True,  # HARDWIRED — the parameter exists for the test factory only
+        cookie_secure=True,  # behind the TLS-front proxy (E-4)
+    )
+
+
+# Module-level app for `uvicorn researchx.api.main:app`. This is the
+# production object; it is built from live wiring (never fakes).
+app = build_app()

backend/src/researchx/api/read_models.py

@@ -0,0 +1,505 @@
+"""Disk read-models (T-3.2, D-114, D-115 — REQ-76..79).
+
+Pure functions over ``runs/<owner_id>/<run_id>/`` disk artifacts —
+NEVER the in-memory RunRegistry (D-115): every read endpoint stays
+correct after a restart with zero in-process actors (P-8 full
+closure). Payloads are shaped EXACTLY to the existing frontend types
+(``frontend/src/lib/types.ts``): ``ReportLibrary``/``ReportSummary``,
+``ReportConnection``, ``ProjectGraph`` nodes/edges, ``InboxItem``,
+``SuggestedQuery`` — camelCase, field-for-field, so T-3.9's surface
+swaps need zero component rewrites (REQ-54).
+
+Categorization is deterministic + dumb by design: a methodology
+folder (``deep-report``/``rapid-answer``) plus topic tokens from plan
+sub-questions. No model calls, no synthesis — the same disk tree
+always categorizes identically.
+
+Open-question semantics (D-114): inbox items are plan sub-questions
+of the user's runs, ``done`` iff the run reached DONE — anything
+else (post-sweep CANCELLED included) stays ``open``; suggestions are
+those open items joined with source run titles — never synthetic.
+"""
+
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+# --------------------------------------------------------------- wire shapes
+
+
+@dataclass(frozen=True)
+class ReportFolder:
+    """matches frontend ReportFolder — id == ReportSummary.category."""
+
+    id: str
+    name: str
+    description: str
+
+    def payload(self) -> dict[str, str]:
+        return {"id": self.id, "name": self.name, "description": self.description}
+
+
+@dataclass(frozen=True)
+class ReportSummary:
+    """matches frontend ReportSummary — the library card."""
+
+    id: str
+    runId: str
+    title: str
+    question: str
+    methodologySlug: str
+    category: str
+    generatedAt: str
+    citationCount: int
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "runId": self.runId,
+            "title": self.title,
+            "question": self.question,
+            "methodologySlug": self.methodologySlug,
+            "category": self.category,
+            "generatedAt": self.generatedAt,
+            "citationCount": self.citationCount,
+        }
+
+
+@dataclass(frozen=True)
+class ReportConnection:
+    """matches frontend ReportConnection — a shared-source/topic edge."""
+
+    fromReportId: str
+    toReportId: str
+    kind: str  # "shared-sources" | "related-topic"
+    label: str
+
+    def payload(self) -> dict[str, str]:
+        return {
+            "fromReportId": self.fromReportId,
+            "toReportId": self.toReportId,
+            "kind": self.kind,
+            "label": self.label,
+        }
+
+
+@dataclass(frozen=True)
+class GraphNode:
+    id: str
+    topic: str
+    linkedSources: list[str]
+    findings: list[str]
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "topic": self.topic,
+            "linkedSources": self.linkedSources,
+            "findings": self.findings,
+        }
+
+
+@dataclass(frozen=True)
+class GraphEdge:
+    fromId: str
+    toId: str
+    sharedSourceCount: int
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            "fromId": self.fromId,
+            "toId": self.toId,
+            "sharedSourceCount": self.sharedSourceCount,
+        }
+
+
+@dataclass(frozen=True)
+class InboxItem:
+    """matches frontend InboxItem — "<run_id>#<idx>" ids (D-114)."""
+
+    id: str
+    question: str
+    sourceRunId: str
+    status: str  # "open" | "done" (in_progress is mock-only vocabulary)
+
+    def payload(self) -> dict[str, str]:
+        return {
+            "id": self.id,
+            "question": self.question,
+            "sourceRunId": self.sourceRunId,
+            "status": self.status,
+        }
+
+
+@dataclass(frozen=True)
+class SuggestedQuery:
+    """matches frontend SuggestedQuery — an open item + run title."""
+
+    id: str
+    question: str
+    sourceRunId: str
+    sourceReportTitle: str
+
+    def payload(self) -> dict[str, str]:
+        return {
+            "id": self.id,
+            "question": self.question,
+            "sourceRunId": self.sourceRunId,
+            "sourceReportTitle": self.sourceReportTitle,
+        }
+
+
+# ------------------------------------------------------------- disk scanning
+
+_METHOD_NAMES = {"rapid-answer": "Rapid Answer", "deep-report": "Deep Report"}
+_QUOTE_MAX = 200
+
+
+def _is_scannable(run_dir: Path) -> bool:
+    """Defensive scan filter (D-115): dotfiles/tmp leftovers skipped."""
+    name = run_dir.name
+    return run_dir.is_dir() and not name.startswith(".") and ".tmp" not in name
+
+
+@dataclass
+class RunDiskRecord:
+    """One run as it sits on disk — the read-model's only input."""
+
+    run_id: str
+    state: dict[str, Any]
+    report: dict[str, Any] | None = None
+    ledger: dict[str, Any] | None = None
+    # derived, filled by load:
+    status: str = field(default="", init=False)
+
+    def __post_init__(self) -> None:
+        self.status = str(self.state.get("state", ""))
+
+    @property
+    def is_done(self) -> bool:
+        return self.status == "DONE"
+
+    @property
+    def question(self) -> str:
+        return str(self.state.get("question", ""))
+
+    @property
+    def methodology_slug(self) -> str:
+        return str(self.state.get("methodology_slug", ""))
+
+    @property
+    def created_at(self) -> str:
+        return str(self.state.get("created_at", ""))
+
+    @property
+    def sub_questions(self) -> list[str]:
+        plan = self.state.get("plan")
+        if not isinstance(plan, dict):
+            return []
+        raw = plan.get("sub_questions", [])
+        if not isinstance(raw, list):
+            return []
+        return [str(q) for q in raw]
+
+    def report_title(self) -> str:
+        """The report.json title, else methodology-name — question."""
+        if self.report is not None and self.report.get("title"):
+            return str(self.report["title"])
+        name = _METHOD_NAMES.get(self.methodology_slug, "Research")
+        return f"{name} — {self.question}"
+
+    def citation_count(self) -> int:
+        if self.report is not None:
+            citations = self.report.get("citations")
+            if isinstance(citations, list):
+                return len(citations)
+        return 0
+
+    def ledger_urls(self) -> list[str]:
+        if self.ledger is None:
+            return []
+        entries = self.ledger.get("entries")
+        if not isinstance(entries, list):
+            return []
+        return [str(e.get("url")) for e in entries if isinstance(e, dict) and e.get("url")]
+
+
+def _read_json(path: Path) -> dict[str, Any] | None:
+    try:
+        raw: object = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return None
+    return raw if isinstance(raw, dict) else None
+
+
+def list_runs(base_dir: Path, owner_id: str) -> list[RunDiskRecord]:
+    """Scan this owner's partition: state.json (+ report.json,
+    ledger.json where present). Dotfiles/tmp skipped defensively
+    (D-115); corrupt or stateless directories are skipped, never
+    fatal. Records are ordered most-recent first (created_at desc,
+    run_id as the stable tiebreaker)."""
+    runs_dir = base_dir / "runs" / owner_id
+    if not runs_dir.is_dir():
+        return []
+    records: list[RunDiskRecord] = []
+    for run_dir in sorted(runs_dir.iterdir()):
+        if not _is_scannable(run_dir):
+            continue
+        state = _read_json(run_dir / "state.json")
+        if state is None:
+            continue
+        records.append(
+            RunDiskRecord(
+                run_id=run_dir.name,
+                state=state,
+                report=_read_json(run_dir / "report.json"),
+                ledger=_read_json(run_dir / "ledger.json"),
+            )
+        )
+    records.sort(key=lambda r: (r.created_at, r.run_id), reverse=True)
+    return records
+
+
+# ------------------------------------------------------- categorization (dumb)
+
+_STOPWORDS = {
+    "the", "a", "an", "of", "in", "on", "and", "or", "to", "for", "is",
+    "are", "what", "which", "how", "do", "does", "why", "when", "with",
+    "that", "this", "these", "those", "it", "its", "by", "at", "be",
+    "can", "could", "should", "will", "into", "from", "about", "across",
+}
+
+_TOPIC_TOKEN_RE = re.compile(r"[a-z][a-z0-9-]*")
+
+
+def topic_tokens(record: RunDiskRecord) -> list[str]:
+    """Deterministic topic tokens: salient words of the plan
+    sub-questions (lowercased, deduped, order-preserving)."""
+    tokens: list[str] = []
+    for question in record.sub_questions:
+        for token in _TOPIC_TOKEN_RE.findall(question.lower()):
+            if token not in _STOPWORDS and token not in tokens:
+                tokens.append(token)
+    return tokens
+
+
+def categorize(record: RunDiskRecord) -> str:
+    """The folder id a report files under: methodology + topic token.
+
+    Deterministic + dumb (REQ-76): the methodology forms the folder
+    base and the first topic token of the plan names the sub-folder —
+    the same disk tree always categorizes identically. Runs without a
+    plan (pre-approval) fall back to the bare methodology slug; a run
+    with neither resolves to "research".
+    """
+    slug = record.methodology_slug or "research"
+    tokens = topic_tokens(record)
+    if not tokens:
+        return slug
+    return f"{slug}-{tokens[0]}"
+
+
+def _category_name(category: str) -> str:
+    """Humanize a category id: 'deep-report-battery' -> 'Deep Report:
+    Battery'. The methodology slug (multi-hyphen, e.g.
+    'deep-report') is stripped as a unit before the topic token is
+    titled."""
+    for slug, name in _METHOD_NAMES.items():
+        prefix = f"{slug}-"
+        if category.startswith(prefix):
+            tail = category[len(prefix) :]
+            return f"{name}: {tail.replace('-', ' ').title()}" if tail else name
+    return category.replace("-", " ").title()
+
+
+def _category_description(category: str) -> str:
+    return f"Auto-filed from {category.replace('-', ' ')} research."
+
+
+def _summary(record: RunDiskRecord) -> ReportSummary:
+    generated_at = (
+        str(record.report.get("generated_at")) if record.report is not None else record.created_at
+    )
+    return ReportSummary(
+        id=f"rep-{record.run_id}",
+        runId=record.run_id,
+        title=record.report_title(),
+        question=record.question,
+        methodologySlug=record.methodology_slug,
+        category=categorize(record),
+        generatedAt=generated_at or datetime.now(UTC).isoformat(),
+        citationCount=record.citation_count(),
+    )
+
+
+# ----------------------------------------------------------------- library
+
+
+def library(base_dir: Path, owner_id: str, sort: str = "recent") -> dict[str, Any]:
+    """GET /api/library payload: folders + ReportSummary[] (REQ-76).
+
+    Only DONE runs with a report are "stored reports" — a cancelled or
+    failed run produced nothing worth filing. ``sort`` is "recent"
+    (default, created_at desc — the scan order) or "title" (A-Z).
+    """
+    if sort not in ("recent", "title"):
+        sort = "recent"
+    done = [r for r in list_runs(base_dir, owner_id) if r.is_done]
+    reports = [_summary(r) for r in done]
+    if sort == "title":
+        reports.sort(key=lambda summary: (summary.title.casefold(), summary.runId))
+    seen: dict[str, int] = {}
+    for summary in reports:
+        seen[summary.category] = seen.get(summary.category, 0) + 1
+    folders = [
+        ReportFolder(
+            id=category,
+            name=_category_name(category),
+            description=_category_description(category),
+        ).payload()
+        for category in sorted(seen)
+    ]
+    return {
+        "folders": folders,
+        "reports": [summary.payload() for summary in reports],
+    }
+
+
+# ------------------------------------------------------------ connections
+
+
+def _shared_urls(first: RunDiskRecord, second: RunDiskRecord) -> set[str]:
+    return set(first.ledger_urls()) & set(second.ledger_urls())
+
+
+def connections(base_dir: Path, owner_id: str) -> list[dict[str, Any]]:
+    """GET /api/library/connections payload (REQ-77): shared-source
+    edges (>=1 ledger URL overlap) + related-topic edges (same
+    methodology + shared category). Between the user's DONE runs
+    only; edges point older -> newer (the fixture convention).
+    """
+    done = list(reversed([r for r in list_runs(base_dir, owner_id) if r.is_done]))
+    edges: list[ReportConnection] = []
+    for i, first in enumerate(done):
+        for second in done[i + 1 :]:
+            shared = _shared_urls(first, second)
+            if shared:
+                edges.append(
+                    ReportConnection(
+                        fromReportId=f"rep-{first.run_id}",
+                        toReportId=f"rep-{second.run_id}",
+                        kind="shared-sources",
+                        label=f"{len(shared)} shared source{'s' if len(shared) != 1 else ''}",
+                    )
+                )
+            elif categorize(first) == categorize(second):
+                edges.append(
+                    ReportConnection(
+                        fromReportId=f"rep-{first.run_id}",
+                        toReportId=f"rep-{second.run_id}",
+                        kind="related-topic",
+                        label="Adjacent topic",
+                    )
+                )
+    return [edge.payload() for edge in edges]
+
+
+# -------------------------------------------------------------------- graph
+
+
+def _report_finding(record: RunDiskRecord) -> str:
+    """The node's first 'finding': the report's title (a real artifact
+    value — never fabricated prose)."""
+    return record.report_title()
+
+
+def graph(base_dir: Path, owner_id: str) -> dict[str, Any]:
+    """GET /api/graph payload (REQ-77): DONE runs as GraphNodes, the
+    same edges as connections() as GraphEdges."""
+    done = list(reversed([r for r in list_runs(base_dir, owner_id) if r.is_done]))
+    nodes = [
+        GraphNode(
+            id=record.run_id,
+            topic=record.report_title(),
+            linkedSources=sorted(set(record.ledger_urls())),
+            findings=[_report_finding(record)],
+        ).payload()
+        for record in done
+    ]
+    edges: list[GraphEdge] = []
+    for i, first in enumerate(done):
+        for second in done[i + 1 :]:
+            shared = _shared_urls(first, second)
+            if shared:
+                edges.append(GraphEdge(first.run_id, second.run_id, len(shared)))
+            elif categorize(first) == categorize(second):
+                edges.append(GraphEdge(first.run_id, second.run_id, 0))
+    return {"nodes": nodes, "edges": [edge.payload() for edge in edges]}
+
+
+# -------------------------------------------------------------------- tasks
+
+
+def tasks(base_dir: Path, owner_id: str) -> list[dict[str, str]]:
+    """GET /api/tasks payload (REQ-78, D-114): plan sub-questions as
+    InboxItems, ``done`` iff the source run reached DONE — post-sweep
+    CANCELLED runs surface ``open``, never answered."""
+    items: list[InboxItem] = []
+    for record in list_runs(base_dir, owner_id):
+        status = "done" if record.is_done else "open"
+        for idx, question in enumerate(record.sub_questions):
+            items.append(
+                InboxItem(
+                    id=f"{record.run_id}#{idx}",
+                    question=question,
+                    sourceRunId=record.run_id,
+                    status=status,
+                )
+            )
+    return [item.payload() for item in items]
+
+
+# -------------------------------------------------------------- suggestions
+
+
+def suggestions(base_dir: Path, owner_id: str) -> list[dict[str, str]]:
+    """GET /api/suggestions payload (REQ-79): the OPEN inbox items
+    joined with their source run titles — derived from the user's own
+    runs only, never synthetic; empty for a fresh user."""
+    suggested: list[SuggestedQuery] = []
+    for record in list_runs(base_dir, owner_id):
+        if record.is_done:
+            continue
+        for idx, question in enumerate(record.sub_questions):
+            suggested.append(
+                SuggestedQuery(
+                    id=f"sug-{record.run_id}#{idx}",
+                    question=question,
+                    sourceRunId=record.run_id,
+                    sourceReportTitle=record.report_title(),
+                )
+            )
+    return [item.payload() for item in suggested]
+
+
+__all__ = [
+    "GraphEdge",
+    "GraphNode",
+    "InboxItem",
+    "ReportConnection",
+    "ReportFolder",
+    "ReportSummary",
+    "RunDiskRecord",
+    "SuggestedQuery",
+    "categorize",
+    "connections",
+    "graph",
+    "library",
+    "list_runs",
+    "suggestions",
+    "tasks",
+    "topic_tokens",
+]

backend/src/researchx/auth/key_store.py

@@ -0,0 +1,336 @@
+"""Per-user encrypted key store (T-2.2, REQ-73 — D-108/D-109).
+
+AES-256-GCM envelope encryption of per-user model keys:
+
+- KEK: ``RESEARCHX_KEK`` from the env-file secrets **'keys' scope**,
+  accepted as urlsafe-base64 or hex, exactly 32 bytes (AES-256). Decode
+  or length errors raise typed ``AdapterError`` (never a silent
+  fallback). With no KEK configured the store is DISABLED — honestly,
+  with a reason string — and the credential chain degrades to
+  server/keyless (C3-06).
+- AAD: ``user_id.encode()`` — a key file copied under another user_id
+  fails ``InvalidTag`` at decrypt time (cross-user binding by
+  construction).
+- Nonce: fresh ``os.urandom(12)`` per write; a GCM nonce must NEVER
+  repeat under the same KEK.
+- File: ``keys/<user_id>.json`` under the data root — ``{v, alg,
+  updated_at, entries}`` — written atomically (tmp + ``os.replace``)
+  with mode 0600.
+- Crypto runs in ``asyncio.to_thread`` so the event loop is never
+  blocked by file I/O.
+- Scope: ``OLLAMA_API_KEY`` only in v0.3 (D-109).
+
+KEK-loss posture (G-105, binding):
+    The KEK is NOT recoverable from anything in this repository or in
+    the running process. If the owner loses it, every per-user
+    encrypted key becomes unrecoverable — by design, that is the point
+    of envelope encryption. The honest degradation is: the key store
+    reports disabled, the resolution chain falls to server/keyless,
+    users re-enter their keys under a re-provisioned KEK, and the owner
+    MUST back up the KEK off-repo. Rotation tooling is out of v0.3
+    scope (recorded). A changed KEK requires a process restart — the
+    secrets provider loads once at construction.
+
+Corruption is never a silent tier drop: ``InvalidTag`` (AAD tamper,
+wrong KEK, garbage ciphertext) and malformed envelopes both surface as
+typed errors (``KeyStoreError``), so the credential chain can report an
+honest error state instead of quietly falling back.
+"""
+
+import asyncio
+import base64
+import os
+import secrets
+import threading
+from datetime import UTC, datetime
+from pathlib import Path
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from pydantic import BaseModel, Field, ValidationError
+
+from researchx.adapters.secrets import SecretsProvider
+from researchx.adapters.types import AdapterError
+
+KEK_NAME = "RESEARCHX_KEK"
+KEY_SCOPE = "OLLAMA_API_KEY"
+_NONCE_BYTES = 12
+_KEY_BYTES = 32
+
+
+class KeyStoreError(AdapterError):
+    """Typed key-store failure: corrupt/tampered envelope, bad KEK shape.
+
+    ``kind`` lets callers (routes, factory, tests) distinguish the
+    failure mode without parsing messages:
+
+    - ``disabled``   — no usable KEK; the store refuses honestly.
+    - ``unreadable`` — the on-disk envelope is corrupt garbage.
+    - ``tampered``   — decrypt failed (InvalidTag: wrong user AAD,
+                       wrong KEK, or bit-rot ciphertext). NEVER a
+                       silent None — the tier must not silently drop.
+    - ``bad_kek``    — the configured KEK is malformed (decode/length).
+    """
+
+    def __init__(self, kind: str, message: str) -> None:
+        super().__init__(message)
+        self.kind = kind
+
+
+class _KeyEntry(BaseModel):
+    nonce: str
+    ct: str
+    updated_at: str
+
+
+class _KeyEnvelope(BaseModel):
+    v: int
+    alg: str = "AES-256-GCM"
+    updated_at: str
+    entries: dict[str, _KeyEntry] = Field(default_factory=dict)
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def load_kek_bytes(secrets: SecretsProvider) -> bytes | None:
+    """Resolve ``RESEARCHX_KEK`` to raw 32 key bytes.
+
+    Accepted encodings: urlsafe-base64 (with or without padding) or
+    hex. Anything that decodes but does not yield exactly 32 bytes, or
+    fails to decode at all, raises ``KeyStoreError(kind="bad_kek")``
+    (the research-file's typed AdapterError contract). ``None`` is
+    returned only when the KEK is simply absent — the honest disabled
+    state, distinct from a broken one.
+    """
+    raw = secrets.resolve(KEK_NAME)
+    if not raw:
+        return None
+    raw = raw.strip()
+    # Try hex first (unambiguous: hex keys are [0-9a-fA-F]{64}); then
+    # urlsafe b64 with flexible padding.
+    try:
+        if len(raw) == _KEY_BYTES * 2 and all(c in "0123456789abcdefABCDEF" for c in raw):
+            return bytes.fromhex(raw)
+    except ValueError as exc:  # pragma: no cover — fromhex on checked chars can't fail
+        raise KeyStoreError("bad_kek", f"{KEK_NAME} is not valid hex") from exc
+    padded = raw + "=" * (-len(raw) % 4)
+    try:
+        decoded = base64.urlsafe_b64decode(padded.encode("ascii"))
+    except (ValueError, TypeError) as exc:
+        raise KeyStoreError(
+            "bad_kek", f"{KEK_NAME} is not valid urlsafe-b64 or hex"
+        ) from exc
+    if len(decoded) != _KEY_BYTES:
+        raise KeyStoreError(
+            "bad_kek", f"{KEK_NAME} must decode to exactly 32 bytes (AES-256), got {len(decoded)}"
+        )
+    return decoded
+
+
+def _encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def _decode(token: str) -> bytes:
+    return base64.urlsafe_b64decode(token + "=" * (-len(token) % 4))
+
+
+class KeyStore:
+    """Per-user encrypted key store (``keys/<user_id>.json``).
+
+    The store is ENABLED iff a valid KEK resolves at construction.
+    Every public method is async; file/crypto work runs in
+    ``asyncio.to_thread``.
+    """
+
+    def __init__(self, secrets: SecretsProvider, data_root: Path) -> None:
+        self._secrets = secrets
+        self._root = data_root / "keys"
+        self._lock = threading.Lock()
+        self._kek: bytes | None
+        self._disabled_reason: str | None = None
+        try:
+            self._kek = load_kek_bytes(secrets)
+        except KeyStoreError as exc:
+            # A malformed KEK is a hard misconfiguration: treat the
+            # store as disabled with the honest reason, never a crash
+            # and never a silent enable with the wrong key.
+            self._kek = None
+            self._disabled_reason = f"{KEK_NAME} is misconfigured: {exc}"
+        if self._kek is None and self._disabled_reason is None:
+            self._disabled_reason = (
+                f"no {KEK_NAME} configured (env-file secrets 'keys' scope); "
+                "per-user model keys cannot be stored — the credential chain "
+                "falls to the server tier or keyless localhost"
+            )
+
+    # ------------------------------------------------------------ state
+
+    @property
+    def enabled(self) -> bool:
+        return self._kek is not None
+
+    @property
+    def disabled_reason(self) -> str | None:
+        return self._disabled_reason
+
+    def _require_kek(self) -> bytes:
+        assert self._kek is not None  # internal invariant; callers gate on enabled
+        return self._kek
+
+    def _path(self, user_id: str) -> Path:
+        return self._root / f"{user_id}.json"
+
+    # ------------------------------------------------------- sync workers
+
+    def _read_envelope(self, user_id: str) -> _KeyEnvelope | None:
+        path = self._path(user_id)
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return None
+        try:
+            return _KeyEnvelope.model_validate_json(raw)
+        except ValidationError as exc:
+            raise KeyStoreError(
+                "unreadable",
+                f"key envelope for user {user_id} is corrupt ({exc.error_count()} errors)",
+            ) from exc
+
+    def _set_key_locked(self, user_id: str, raw_key: str) -> None:
+        kek = self._require_kek()
+        nonce = os.urandom(_NONCE_BYTES)  # fresh per write — NEVER reuse under the KEK
+        ct = AESGCM(kek).encrypt(nonce, raw_key.encode("utf-8"), user_id.encode("utf-8"))
+        envelope = _KeyEnvelope(
+            v=1,
+            alg="AES-256-GCM",
+            updated_at=_now(),
+            entries={KEY_SCOPE: _KeyEntry(nonce=_encode(nonce), ct=_encode(ct), updated_at=_now())},
+        )
+        path = self._path(user_id)
+        self._root.mkdir(parents=True, exist_ok=True)
+        tmp_path = path.with_name(f"{path.name}.{secrets.token_hex(4)}.tmp")
+        with open(tmp_path, "w", encoding="utf-8") as handle:
+            handle.write(envelope.model_dump_json(indent=2))
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(tmp_path, 0o600)
+        os.replace(tmp_path, path)  # atomic — a crash never leaves a torn file
+
+    def _get_key_locked(self, user_id: str) -> str | None:
+        envelope = self._read_envelope(user_id)
+        if envelope is None:
+            return None
+        entry = envelope.entries.get(KEY_SCOPE)
+        if entry is None:
+            return None
+        kek = self._require_kek()
+        try:
+            plain = AESGCM(kek).decrypt(
+                _decode(entry.nonce), _decode(entry.ct), user_id.encode("utf-8")
+            )
+        except InvalidTag as exc:
+            # AAD binding (user_id) failed, the KEK changed, or the
+            # ciphertext bit-rotted. This is a typed error, NEVER a
+            # silent None — a silent drop would let the tier fall to
+            # server/keyless without the user knowing their key is
+            # unreadable (C3-06).
+            raise KeyStoreError(
+                "tampered",
+                f"key envelope for user {user_id} failed authentication "
+                "(wrong user binding, changed KEK, or tampering)",
+            ) from exc
+        except (ValueError, TypeError) as exc:
+            raise KeyStoreError(
+                "unreadable", f"key envelope for user {user_id} has invalid encoding"
+            ) from exc
+        return plain.decode("utf-8")
+
+    # ------------------------------------------------------------ API
+
+    async def set_key(self, user_id: str, scope: str, raw_key: str) -> None:
+        """Encrypt and persist *raw_key* for *user_id* under *scope*.
+
+        Rejected with a typed error when the store is disabled — an
+        honest refusal, never a silent no-op.
+        """
+        if scope != KEY_SCOPE:
+            raise KeyStoreError("disabled", f"unsupported key scope: {scope} (v0.3: {KEY_SCOPE} only)")
+        if not self.enabled:
+            raise KeyStoreError("disabled", self._disabled_reason or "key store disabled")
+
+        def _work() -> None:
+            with self._lock:
+                self._set_key_locked(user_id, raw_key)
+
+        await asyncio.to_thread(_work)
+
+    async def get_key(self, user_id: str) -> str | None:
+        """Decrypt and return the user's key, or None when none stored.
+
+        Raises ``KeyStoreError`` on tamper/corruption (never a silent
+        None), and when the store is disabled with a stored envelope
+        that cannot be read.
+        """
+        if not self.enabled:
+            # Without a KEK nothing can be read — but an envelope that
+            # EXISTS is surfaced as an error state (the user has a key
+            # we cannot serve), not silently None.
+            def _peek() -> bool:
+                return self._path(user_id).is_file()
+
+            if await asyncio.to_thread(_peek):
+                raise KeyStoreError(
+                    "disabled",
+                    f"a key is stored for user {user_id} but the key store is disabled ({self._disabled_reason})",
+                )
+            return None
+
+        def _work() -> str | None:
+            with self._lock:
+                return self._get_key_locked(user_id)
+
+        return await asyncio.to_thread(_work)
+
+    async def masked_status(self, user_id: str) -> dict[str, object]:
+        """Masked-only status: ``{configured, masked}`` — NEVER the raw key.
+
+        When the store is disabled the status says so honestly
+        (``disabled: True`` + reason). A tampered/unreadable envelope
+        is surfaced as an error field rather than ``configured: False``
+        — never a silent tier drop.
+        """
+        status: dict[str, object] = {"configured": False, "masked": None}
+        if not self.enabled:
+            status["disabled"] = True
+            status["reason"] = self._disabled_reason
+
+            def _peek() -> bool:
+                return self._path(user_id).is_file()
+
+            if await asyncio.to_thread(_peek):
+                # An unreadable stored key is an error state, not "not configured".
+                raise KeyStoreError(
+                    "disabled",
+                    f"a key is stored for user {user_id} but the key store is disabled ({self._disabled_reason})",
+                )
+            return status
+
+        def _work() -> dict[str, object]:
+            with self._lock:
+                envelope = self._read_envelope(user_id)
+                if envelope is None or envelope.entries.get(KEY_SCOPE) is None:
+                    return {"configured": False, "masked": None, "disabled": False}
+                key = self._get_key_locked(user_id)  # surfaces tamper as KeyStoreError
+                return {
+                    "configured": True,
+                    "masked": f"…{key[-4:]}" if key and len(key) >= 4 else "…",
+                    "disabled": False,
+                }
+
+        return await asyncio.to_thread(_work)
+
+
+__all__ = ["KEK_NAME", "KEY_SCOPE", "KeyStore", "KeyStoreError", "load_kek_bytes"]

backend/src/researchx/auth/settings.py

@@ -0,0 +1,104 @@
+"""Per-user settings persistence (T-2.3, REQ-72 — D-111).
+
+``settings/<user_id>.json`` under the data root, written atomically
+(tmp + ``os.replace``). Fresh users get defaults on read (GET never
+writes). The ``UserSettings`` model carries the per-user surface the
+Settings page binds to: planner/writer model names, methodology
+defaults (resolved dial overrides per methodology — free-form dict in
+v0.3, validated at use time), and the appearance slot.
+
+The storage directory is server-managed and display-only (D-111) — it
+is NOT part of this payload; the config status route surfaces it.
+"""
+
+import asyncio
+import os
+import secrets
+import threading
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, ValidationError
+
+from researchx.adapters.types import AdapterError
+
+# Default model names — the same defaults the live smoke tier uses
+# (gpt-oss:20b on ollama.com). These are fallbacks only: the frontend
+# Settings page always shows the current value.
+DEFAULT_PLANNER_MODEL = "gpt-oss:20b"
+DEFAULT_WRITER_MODEL = "gpt-oss:20b"
+
+
+class UserSettings(BaseModel):
+    planner_model: str = DEFAULT_PLANNER_MODEL
+    writer_model: str = DEFAULT_WRITER_MODEL
+    methodology_defaults: dict[str, Any] = Field(default_factory=dict)
+    appearance: str = "system"
+
+
+class SettingsStoreError(AdapterError):
+    """Typed settings-store failure (corrupt on-disk payload)."""
+
+
+class SettingsStore:
+    """Per-user settings, one JSON file per user, atomic writes."""
+
+    def __init__(self, data_root: Path) -> None:
+        self._root = data_root / "settings"
+        self._lock = threading.Lock()
+
+    def _path(self, user_id: str) -> Path:
+        return self._root / f"{user_id}.json"
+
+    # ------------------------------------------------------------ sync
+
+    def _read_sync(self, user_id: str) -> UserSettings:
+        path = self._path(user_id)
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return UserSettings()  # fresh user: defaults, no write on read
+        try:
+            return UserSettings.model_validate_json(raw)
+        except ValidationError as exc:
+            raise SettingsStoreError(
+                f"settings payload for user {user_id} is corrupt ({exc.error_count()} errors)"
+            ) from exc
+
+    def _update_sync(self, user_id: str, partial: UserSettings) -> UserSettings:
+        current = self._read_sync(user_id)
+        merged = current.model_copy(update=partial.model_dump(exclude_unset=True))
+        # Validate the merged payload BEFORE it touches disk: a null
+        # field slipped past model_copy (it skips validation) would
+        # poison the file — every later read would raise corrupt.
+        merged = UserSettings.model_validate(merged.model_dump())
+        path = self._path(user_id)
+        self._root.mkdir(parents=True, exist_ok=True)
+        tmp_path = path.with_name(f"{path.name}.{secrets.token_hex(4)}.tmp")
+        with open(tmp_path, "w", encoding="utf-8") as handle:
+            handle.write(merged.model_dump_json(indent=2))
+            handle.flush()
+            os.fsync(handle.fileno())
+        tmp_path.replace(path)  # atomic
+        return merged
+
+    # ------------------------------------------------------------ async
+
+    async def get(self, user_id: str) -> UserSettings:
+        return await asyncio.to_thread(self._read_sync, user_id)
+
+    async def update(self, user_id: str, partial: UserSettings) -> UserSettings:
+        def _work() -> UserSettings:
+            with self._lock:
+                return self._update_sync(user_id, partial)
+
+        return await asyncio.to_thread(_work)
+
+
+__all__ = [
+    "DEFAULT_PLANNER_MODEL",
+    "DEFAULT_WRITER_MODEL",
+    "SettingsStore",
+    "SettingsStoreError",
+    "UserSettings",
+]

backend/src/researchx/auth/users.py

@@ -162,6 +162,40 @@ class UserStore:
             self._by_email[updated.email] = updated
             self._persist_locked()
 
+    async def update_profile(
+        self,
+        user_id: str,
+        *,
+        display_name: str | None = None,
+        email: str | None = None,
+    ) -> User:
+        """Update display name and/or email (T-3.6 — GET/PUT /api/profile).
+
+        The email must remain unique across OTHER users (a taken
+        address raises UserError); the email index is maintained
+        atomically under the store lock. No deletion exists.
+        """
+        with self._lock:
+            user = self._by_id.get(user_id)
+            if user is None:
+                raise UserError("unknown user")
+            new_email = user.email
+            if email is not None:
+                new_email = email.casefold()
+                other = self._by_email.get(new_email)
+                if other is not None and other.user_id != user_id:
+                    raise UserError("email already registered")
+            new_display = display_name if display_name is not None else user.display_name
+            updated = user.model_copy(update={"email": new_email, "display_name": new_display})
+            if new_email != user.email:
+                old = self._by_email.get(user.email)
+                if old is not None and old.user_id == user_id:
+                    del self._by_email[user.email]
+            self._by_id[user_id] = updated
+            self._by_email[new_email] = updated
+            self._persist_locked()
+            return updated
+
     async def create_first_admin(self, *, email: str, password: str, display_name: str) -> User:
         """Atomically create the first user, who is admin by construction.
 

backend/src/researchx/engine/actor.py

@@ -11,6 +11,7 @@ from researchx.adapters.types import AdapterError, ModelMessage
 from researchx.adapters.url_guard import url_allowed
 from researchx.config.dials import Dials
 from researchx.config.run_config import RunConfig, resolve_dials
+from researchx.engine.artifacts import build_evidence_artifact, build_report_artifact
 from researchx.engine.events import EventBus, RunEvent
 from researchx.engine.run_state import Plan, RunState
 from researchx.engine.states import RunStateName
@@ -328,6 +329,33 @@ class RunActor:
         )
         checklist = export_checklist(ledger)
         await self._storage.write_run_artifact(self._config.run_id, "checklist.md", checklist)
+        # Structured artifacts (T-3.1, D-113): report.json +
+        # evidence.json, written HERE — the only point where the
+        # per-actor EvidenceStore still exists (it dies with the actor;
+        # the disk read-models of D-114/D-115 can never rebuild it).
+        # Marker normalization [p-N] -> [^pN] happens at this
+        # persistence boundary ONLY (C3-10): report.md keeps the raw
+        # form the trust-loop regexes depend on.
+        evidence_artifact = build_evidence_artifact(
+            run_id=self._config.run_id, evidence=self._store
+        )
+        report_artifact = build_report_artifact(
+            run_id=self._config.run_id,
+            owner_id=self.state.owner_id,
+            question=self._config.question,
+            methodology_name=self._methodology.name,
+            methodology_slug=self._config.methodology_slug,
+            report_markdown=report,
+            ledger=ledger,
+            evidence=self._store,
+            generated_at=ledger.generated_at,
+        )
+        await self._storage.write_run_artifact(
+            self._config.run_id, "evidence.json", evidence_artifact.model_dump_json(indent=2)
+        )
+        await self._storage.write_run_artifact(
+            self._config.run_id, "report.json", report_artifact.model_dump_json(indent=2)
+        )
         await self._checkpoint(RunStateName.DONE)
         await self._publish("run_done", {"run_id": self._config.run_id})
 

backend/src/researchx/engine/artifacts.py

@@ -0,0 +1,227 @@
+"""Structured run artifacts (T-3.1, D-113): report.json + evidence.json.
+
+Built at DONE inside ``RunActor._verify_phase`` — the ONLY point where
+the per-actor ``EvidenceStore`` is still alive (it is GC'd with the
+actor; D-115 disk read-models come later and can never see it).
+
+**Marker normalization happens HERE ONLY (C3-10).** The writer emits
+``[p-N]`` — the trust-loop regexes (``anchoring.py``,
+``ledger.py``) and the actor's own ``_cited_urls`` depend on that raw
+form, so ``report.md`` is never touched. The Reading Room parses
+``[^pN]`` (``report-body.ts`` matches ``[A-Za-z0-9]+`` only —
+``[^p-1]`` does NOT match), therefore report.json section bodies and
+the id fields of both artifacts carry the normalized ``pN`` id form.
+
+Both artifacts are versioned (``v: 1``) so later schema changes stay
+detectable per file (D-106 old artifacts stay disposable/readable).
+"""
+
+import re
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from researchx.evidence.store import EvidenceStore
+from researchx.trust.ledger import CitationLedger
+
+#: The writer's raw marker form — the ONLY pattern normalized here.
+_MARKER_RE = re.compile(r"\[p-(\d+)\]")
+
+#: ATX headings (H1..H6) — section delimiters for report.json.
+_HEADING_RE = re.compile(r"^#{1,6}[ \t]+(.*)$", re.MULTILINE)
+
+#: A lone H1 — the report title source.
+_H1_RE = re.compile(r"^#[ \t]+(.*)$", re.MULTILINE)
+
+#: Quote display cap — matches EvidenceStore's ``quote`` convention.
+_QUOTE_MAX_CHARS = 200
+
+
+def normalize_passage_id(passage_id: str) -> str:
+    """``p-N`` -> ``pN`` (the id form report.json/evidence.json carry)."""
+    match = re.fullmatch(r"p-(\d+)", passage_id)
+    return f"p{match.group(1)}" if match else passage_id
+
+
+def normalize_markers(text: str) -> str:
+    """``[p-N]`` -> ``[^pN]`` — report.json section bodies ONLY."""
+    return _MARKER_RE.sub(lambda match: f"[^p{match.group(1)}]", text)
+
+
+def extract_title(markdown: str, fallback: str) -> str:
+    """First H1 of the report, else the methodology/question fallback."""
+    match = _H1_RE.search(markdown)
+    if match is not None:
+        return match.group(1).strip()
+    return fallback
+
+
+def split_sections(markdown: str) -> list[tuple[str, str]]:
+    """Split report.md into (heading, body) chunks on ATX headings.
+
+    Every ``^#{1,6}\\s`` heading starts a section and is included as
+    that section's heading (the H1 chunk included — the title is a
+    separate field and the frontend binding decides presentation).
+    Content before the first heading becomes a ``("", body)`` section
+    rather than being dropped — no content loss, no fabrication.
+    """
+    sections: list[tuple[str, str]] = []
+    matches = list(_HEADING_RE.finditer(markdown))
+    if not matches:
+        body = markdown.strip()
+        if body:
+            sections.append(("", body))
+        return sections
+    preamble = markdown[: matches[0].start()].strip()
+    if preamble:
+        sections.append(("", preamble))
+    for index, match in enumerate(matches):
+        heading = match.group(1).strip()
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(markdown)
+        sections.append((heading, markdown[start:end].strip()))
+    return sections
+
+
+class EvidencePassage(BaseModel):
+    """One stored passage — id in the normalized ``pN`` form."""
+
+    passage_id: str
+    url: str
+    title: str
+    quote: str
+    text: str
+
+
+class EvidenceArtifact(BaseModel):
+    """evidence.json — the serialized EvidenceStore at DONE."""
+
+    v: int = 1
+    run_id: str
+    passages: list[EvidencePassage] = Field(default_factory=list)
+
+
+class ReportSection(BaseModel):
+    heading: str
+    body: str
+
+
+class ReportCitation(BaseModel):
+    """A page-anchored citation — passage-level, quote included."""
+
+    passage_id: str  # pN form
+    url: str
+    title: str
+    quote: str
+    health: str
+    authority_tier: str
+
+
+class ReportArtifact(BaseModel):
+    """report.json — the structured Reading-Room payload at DONE."""
+
+    v: int = 1
+    run_id: str
+    owner_id: str | None = None
+    title: str
+    question: str
+    methodology_slug: str
+    generated_at: datetime
+    sections: list[ReportSection] = Field(default_factory=list)
+    citations: list[ReportCitation] = Field(default_factory=list)
+
+
+def _page_titles(evidence: EvidenceStore) -> dict[str, str]:
+    return {page.url: page.title for page in evidence.pages()}
+
+
+def _clip(quote: str) -> str:
+    return quote[:_QUOTE_MAX_CHARS]
+
+
+def build_evidence_artifact(*, run_id: str, evidence: EvidenceStore) -> EvidenceArtifact:
+    """Serialize the full EvidenceStore — ids renumbered ``pN``.
+
+    Every passage the run collected, full text included: this is the
+    only persisted copy (the in-actor store dies at DONE).
+    """
+    titles = _page_titles(evidence)
+    passages = [
+        EvidencePassage(
+            passage_id=normalize_passage_id(passage.passage_id),
+            url=passage.url,
+            title=titles.get(passage.url, ""),
+            quote=_clip(passage.quote),
+            text=passage.text,
+        )
+        for passage in evidence.writer_context()
+    ]
+    return EvidenceArtifact(run_id=run_id, passages=passages)
+
+
+def build_report_artifact(
+    *,
+    run_id: str,
+    owner_id: str | None,
+    question: str,
+    methodology_name: str,
+    methodology_slug: str,
+    report_markdown: str,
+    ledger: CitationLedger,
+    evidence: EvidenceStore,
+    generated_at: datetime,
+) -> ReportArtifact:
+    """Build report.json from the raw report.md + ledger + evidence.
+
+    Section bodies carry normalized ``[^pN]`` markers (C3-10); the raw
+    ``report.md`` on disk is untouched. Citations are the ledger's cited
+    URL entries resolved to their stored passages — real quotes from
+    the evidence in hand, never fabricated.
+    """
+    title = extract_title(report_markdown, fallback=f"{methodology_name} — {question}")
+    sections = [
+        ReportSection(heading=heading, body=normalize_markers(body))
+        for heading, body in split_sections(report_markdown)
+    ]
+    titles = _page_titles(evidence)
+    citations: list[ReportCitation] = []
+    for entry in ledger.entries:
+        for passage_id in entry.passages:
+            passage = evidence.get(passage_id)
+            if passage is None:
+                continue
+            citations.append(
+                ReportCitation(
+                    passage_id=normalize_passage_id(passage_id),
+                    url=entry.url,
+                    title=titles.get(entry.url, "") or entry.url,
+                    quote=_clip(passage.quote),
+                    health=entry.health,
+                    authority_tier=entry.authority_tier,
+                )
+            )
+    return ReportArtifact(
+        run_id=run_id,
+        owner_id=owner_id,
+        title=title,
+        question=question,
+        methodology_slug=methodology_slug,
+        generated_at=generated_at,
+        sections=sections,
+        citations=citations,
+    )
+
+
+__all__ = [
+    "EvidenceArtifact",
+    "EvidencePassage",
+    "ReportArtifact",
+    "ReportCitation",
+    "ReportSection",
+    "build_evidence_artifact",
+    "build_report_artifact",
+    "extract_title",
+    "normalize_markers",
+    "normalize_passage_id",
+    "split_sections",
+]

backend/src/researchx/engine/run_state.py

@@ -21,6 +21,10 @@ class RunState(BaseModel):
     # Owner of the run (REQ-71). None on pre-v0.3 state files — old
     # artifacts must deserialize unchanged (D-106: no migration).
     owner_id: str | None = None
+    # Which credential tier resolved for this run (REQ-74: user|
+    # server|keyless). None on pre-v0.3.2 state files — old artifacts
+    # deserialize unchanged (D-106: no migration).
+    credential_tier: str | None = None
     plan: Plan | None = None
     depth_cursor: int = 0
     depth_target: int = 1

backend/tests/test_artifacts.py

@@ -0,0 +1,325 @@
+"""Structured artifacts at DONE (T-3.1, D-113): report.json +
+evidence.json — marker normalization at the persistence boundary ONLY
+(C3-10: report.json bodies carry [^pN], report.md keeps raw [p-N])."""
+
+import asyncio
+import contextlib
+import json
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+
+from researchx.adapters.fakes import CORPUS, FakeModelAdapter, FakeSearchAdapter
+from researchx.adapters.local_storage import LocalStorageAdapter
+from researchx.adapters.types import ChatResult
+from researchx.engine.actor import EngineError, RunActor, make_run_config
+from researchx.engine.artifacts import (
+    build_evidence_artifact,
+    build_report_artifact,
+    extract_title,
+    normalize_markers,
+    normalize_passage_id,
+    split_sections,
+)
+from researchx.engine.events import EventBus
+from researchx.engine.states import RunStateName
+from researchx.evidence.store import EvidenceStore
+from researchx.methodologies import registry
+from researchx.trust.ledger import build_ledger
+from researchx.trust.liveness import LivenessStatus
+
+_PLAN = json.dumps(
+    {
+        "sub_questions": ["methodology verification", "quote anchoring"],
+        "source_universe": ["web"],
+        "outline": ["intro", "findings"],
+    }
+)
+
+# Multi-section report with [p-N] markers on multiple lines.
+_WRITER_REPORT = (
+    "# Battery Advances\n\n"
+    "The verification pass re-anchored every quoted claim [p-1].\n\n"
+    "## Findings\n\n"
+    "Methodology-first selection converts ad-hoc prompting [p-1] "
+    "into reproducible decisions [p-2].\n\n"
+    "## Conclusion\n\n"
+    "The anchored loop holds [p-2].\n"
+)
+
+
+def _canned() -> list[ChatResult]:
+    return [
+        ChatResult(content=_PLAN, model="fake-planner"),
+        ChatResult(content=_WRITER_REPORT, model="fake-writer"),
+    ]
+
+
+def _storage(tmp_path: Path) -> LocalStorageAdapter:
+    return LocalStorageAdapter(base_dir=tmp_path, owner_id="abcd2345")
+
+
+async def _run_to_done(tmp_path: Path) -> RunActor:
+    _run_id, config = make_run_config(
+        question="How do verification pipelines keep citations honest?",
+        context="",
+        methodology_slug="rapid-answer",
+        overrides={},
+        registry=registry,
+        run_id="abcd2345",
+        owner_id="abcd2345",
+    )
+    model = FakeModelAdapter(canned=_canned())
+    search = FakeSearchAdapter(CORPUS)
+    actor = RunActor(
+        run_config=config,
+        model=model,
+        search=search,
+        storage=_storage(tmp_path),
+        registry=registry,
+        event_bus=EventBus(),
+    )
+    actor.state.owner_id = "abcd2345"
+    task = asyncio.create_task(actor.run())
+    while actor.state.state != RunStateName.AWAITING_APPROVAL:
+        await asyncio.sleep(0.01)
+        if task.done():
+            break
+    await actor.approve()
+    await task
+    assert actor.state.state == RunStateName.DONE
+    return actor
+
+
+async def _read_json(tmp_path: Path, name: str) -> dict[str, object]:
+    raw = await _storage(tmp_path).read_run_artifact("abcd2345", name)
+    return json.loads(raw)  # type: ignore[no-any-return]
+
+
+# ------------------------------------------------------------- unit helpers
+
+
+def test_normalize_markers_converts_p_dash_form() -> None:
+    assert normalize_markers("claim [p-1] and [p-12]") == "claim [^p1] and [^p12]"
+
+
+def test_normalize_passage_id_renumbers() -> None:
+    assert normalize_passage_id("p-1") == "p1"
+    assert normalize_passage_id("p-42") == "p42"
+
+
+def test_split_sections_on_headings() -> None:
+    sections = split_sections("# Title\n\nintro body\n\n## A\n\na body\n\n### B\n\nb body")
+    assert sections == [
+        ("Title", "intro body"),
+        ("A", "a body"),
+        ("B", "b body"),
+    ]
+
+
+def test_split_sections_preamble_and_no_headings() -> None:
+    assert split_sections("loose text only") == [("", "loose text only")]
+    assert split_sections("before\n\n# H\n\nafter") == [("", "before"), ("H", "after")]
+
+
+def test_extract_title_prefers_first_h1() -> None:
+    assert extract_title("# First H1\n\n## Second\n", "fallback") == "First H1"
+    assert extract_title("no heading at all", "Deep Report — q?") == "Deep Report — q?"
+
+
+# --------------------------------------------------------------- build paths
+
+
+def _fixture_store() -> EvidenceStore:
+    store = EvidenceStore()
+    store.add_page(
+        "https://example.org/verification",
+        "Verification passes in research pipelines",
+        (
+            "The verification pass re-anchored every quoted claim to its stored "
+            "passage before the report was allowed to ship, so the audit trail "
+            "stays honest claim by claim."
+        ),
+    )
+    return store
+
+
+def test_build_evidence_artifact_renumbers_ids_and_keeps_text() -> None:
+    artifact = build_evidence_artifact(run_id="abcd2345", evidence=_fixture_store())
+    payload = json.loads(artifact.model_dump_json())
+    assert payload["v"] == 1
+    assert payload["run_id"] == "abcd2345"
+    assert len(payload["passages"]) == 1
+    passage = payload["passages"][0]
+    assert passage["passage_id"] == "p1"  # p-1 -> p1
+    assert passage["url"] == "https://example.org/verification"
+    assert passage["title"] == "Verification passes in research pipelines"
+    assert passage["quote"] == passage["text"][:200]
+    assert "re-anchored" in passage["text"]
+
+
+def test_build_report_artifact_sections_and_citations() -> None:
+    store = _fixture_store()
+    markdown = "# Report\n\nClaim [p-1] here.\n\n## Findings\n\nAnother [p-1] claim.\n"
+    ledger = build_ledger(
+        run_id="abcd2345",
+        report_text=markdown,
+        evidence=store,
+        liveness={"https://example.org/verification": LivenessStatus.LIVE},
+        visited_at=datetime.now(UTC),
+    )
+    artifact = build_report_artifact(
+        run_id="abcd2345",
+        owner_id="abcd2345",
+        question="q?",
+        methodology_name="Rapid Answer",
+        methodology_slug="rapid-answer",
+        report_markdown=markdown,
+        ledger=ledger,
+        evidence=store,
+        generated_at=ledger.generated_at,
+    )
+    payload = json.loads(artifact.model_dump_json())
+    assert payload["v"] == 1
+    assert payload["owner_id"] == "abcd2345"
+    assert payload["title"] == "Report"
+    assert payload["question"] == "q?"
+    assert payload["methodology_slug"] == "rapid-answer"
+    assert [s["heading"] for s in payload["sections"]] == ["Report", "Findings"]
+    # C3-10: normalized markers in section bodies ONLY.
+    assert "[^p1]" in payload["sections"][0]["body"]
+    assert "[p-1]" not in payload["sections"][0]["body"]
+    assert [c["passage_id"] for c in payload["citations"]] == ["p1"]
+    citation = payload["citations"][0]
+    assert citation["url"] == "https://example.org/verification"
+    assert citation["title"] == "Verification passes in research pipelines"
+    assert citation["quote"].startswith("The verification pass")
+    assert citation["health"] == "live"
+    assert citation["authority_tier"] == "reference"
+
+
+def test_build_report_artifact_title_fallback_uses_methodology_name() -> None:
+    store = _fixture_store()
+    ledger = build_ledger(
+        run_id="abcd2345",
+        report_text="no heading [p-1]",
+        evidence=store,
+        liveness={},
+        visited_at=datetime.now(UTC),
+    )
+    artifact = build_report_artifact(
+        run_id="abcd2345",
+        owner_id=None,
+        question="what about X?",
+        methodology_name="Deep Report",
+        methodology_slug="deep-report",
+        report_markdown="no heading [p-1]",
+        ledger=ledger,
+        evidence=store,
+        generated_at=ledger.generated_at,
+    )
+    assert artifact.title == "Deep Report — what about X?"
+
+
+# --------------------------------------------------- at-DONE persistence
+
+
+async def test_done_writes_report_and_evidence_artifacts(tmp_path: Path) -> None:
+    await _run_to_done(tmp_path)
+
+    report_payload = await _read_json(tmp_path, "report.json")
+    evidence_payload = await _read_json(tmp_path, "evidence.json")
+
+    # report.json shape
+    assert report_payload["v"] == 1
+    assert report_payload["run_id"] == "abcd2345"
+    assert report_payload["owner_id"] == "abcd2345"
+    assert report_payload["title"] == "Battery Advances"
+    assert report_payload["methodology_slug"] == "rapid-answer"
+    assert "generated_at" in report_payload
+    assert [s["heading"] for s in report_payload["sections"]] == [  # type: ignore[call-overload]
+        "Battery Advances",
+        "Findings",
+        "Conclusion",
+    ]
+
+    # evidence.json shape
+    assert evidence_payload["v"] == 1
+    assert evidence_payload["run_id"] == "abcd2345"
+    assert len(evidence_payload["passages"]) >= 2  # type: ignore[arg-type]
+
+
+async def test_marker_normalization_at_boundary_only(tmp_path: Path) -> None:
+    """C3-10 pinned end to end: report.json bodies carry [^pN]; the raw
+    report.md keeps [p-N] (the trust-loop regexes' form)."""
+    await _run_to_done(tmp_path)
+
+    report_payload = await _read_json(tmp_path, "report.json")
+    markdown = await _storage(tmp_path).read_run_artifact("abcd2345", "report.md")
+
+    sections = report_payload["sections"]
+    assert isinstance(sections, list) and sections
+    joined = "\n".join(str(s["body"]) for s in sections)
+    assert "[^p1]" in joined
+    assert "[p-1]" not in joined
+    assert "[^p2]" in joined
+    # The raw artifact is untouched — trust-loop regexes keep working.
+    assert "[p-1]" in markdown
+    assert "[^p1]" not in markdown
+
+
+async def test_citations_carry_real_quotes_and_pn_ids(tmp_path: Path) -> None:
+    await _run_to_done(tmp_path)
+    report_payload = await _read_json(tmp_path, "report.json")
+    evidence_payload = await _read_json(tmp_path, "evidence.json")
+
+    citations = report_payload["citations"]
+    assert isinstance(citations, list) and citations
+    for citation in citations:
+        assert re.fullmatch(r"^p\d+$", str(citation["passage_id"]))
+        assert citation["url"].startswith("https://")
+        assert citation["quote"], "citation quote must be a real stored quote"
+        assert len(str(citation["quote"])) <= 200
+        assert citation["health"] in {"live", "stale", "dead"}
+        assert citation["authority_tier"]
+
+    # Evidence carries full texts: quote is the clipped head of text.
+    passages = evidence_payload["passages"]
+    assert isinstance(passages, list) and passages
+    evidence_by_id = {str(p["passage_id"]): p for p in passages}
+    for citation in citations:
+        passage = evidence_by_id[str(citation["passage_id"])]
+        assert str(passage["quote"]) == str(citation["quote"])
+        assert len(str(passage["text"])) >= len(str(passage["quote"]))
+
+
+async def test_artifacts_only_written_at_done(tmp_path: Path) -> None:
+    """A run cancelled at AWAITING_APPROVAL leaves no structured
+    artifacts — the write point is _verify_phase, nothing earlier."""
+    _run_id, config = make_run_config(
+        question="q",
+        context="",
+        methodology_slug="rapid-answer",
+        overrides={},
+        registry=registry,
+        run_id="abcd2345",
+        owner_id="abcd2345",
+    )
+    actor = RunActor(
+        run_config=config,
+        model=FakeModelAdapter(canned=_canned()),
+        search=FakeSearchAdapter(CORPUS),
+        storage=_storage(tmp_path),
+        registry=registry,
+        event_bus=EventBus(),
+    )
+    task = asyncio.create_task(actor.run())
+    while actor.state.state != RunStateName.AWAITING_APPROVAL:
+        await asyncio.sleep(0.01)
+    actor.cancel()
+    await actor.approve()
+    with contextlib.suppress(asyncio.CancelledError, EngineError):
+        await task
+    run_dir = tmp_path / "runs" / "abcd2345" / "abcd2345"
+    assert not (run_dir / "report.json").exists()
+    assert not (run_dir / "evidence.json").exists()

backend/tests/test_key_store_adversarial.py

@@ -0,0 +1,336 @@
+"""Key-store adversarial route suite (T-2.8 — security-engineer hat).
+
+Route-level adversarial coverage beyond the unit suite in
+test_key_store_settings.py: corrupt/tampered envelopes surfacing
+through the API (typed error, honest degraded tier, never a silent
+drop and never a 500), raw-key non-leak across the FULL response
+surface of a session that touches the key store, and the create_run
+409 honesty on a corrupt envelope (never a wrong-key run, never a
+silent tier fall).
+"""
+
+import asyncio
+import base64
+import json
+import os
+from pathlib import Path
+
+import httpx
+import pytest
+
+from researchx.adapters.fakes import CORPUS, FakeModelAdapter, FakeSearchAdapter
+from researchx.adapters.model_factory import ModelAdapterFactory
+from researchx.adapters.secrets import EnvFileSecretsProvider
+from researchx.adapters.types import ChatResult
+from researchx.api.app import create_app
+from researchx.auth.guard import CSRF_HEADER
+from researchx.auth.key_store import KEK_NAME, KeyStore
+
+_PLAN = json.dumps(
+    {"sub_questions": ["verification passes"], "source_universe": ["web"], "outline": ["intro"]}
+)
+_WRITER = "# Report\n\nClaim [p-1] and claim [p-2].\n"
+
+_ADMIN_EMAIL = "admin@example.org"
+_ADMIN_PASSWORD = "correct-horse-battery"
+_SECOND_EMAIL = "second@example.org"
+_SECOND_PASSWORD = "second-long-password"
+
+_HEADERS = {CSRF_HEADER: "1"}
+_KEK = base64.urlsafe_b64encode(os.urandom(32)).decode()
+_USER_KEY = "adversarial-user-key-4242"
+
+
+def _app(tmp_path: Path, secrets_values: dict[str, str]):
+    env_file = tmp_path / ".env.secrets"
+    env_file.write_text(
+        "".join(f"{k}={v}\n" for k, v in secrets_values.items()), encoding="utf-8"
+    )
+    secrets = EnvFileSecretsProvider(paths=[env_file])
+    return create_app(
+        storage_dir=tmp_path,
+        model_adapter=FakeModelAdapter(
+            canned=[
+                ChatResult(content=_PLAN, model="fake-planner"),
+                ChatResult(content=_WRITER, model="fake-writer"),
+            ]
+        ),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=True,
+        data_dir=tmp_path,
+        secrets_provider=secrets,
+        model_factory=ModelAdapterFactory(
+            secrets,
+            KeyStore(secrets, tmp_path),
+            cloud_base_url="http://127.0.0.1:1/v1",  # hermetic: unroutable
+            local_base_url="http://127.0.0.1:1/v1",
+        ),
+    )
+
+
+async def _login_admin(client: httpx.AsyncClient) -> None:
+    await client.post(
+        "/api/auth/register",
+        json={"email": _ADMIN_EMAIL, "password": _ADMIN_PASSWORD, "display_name": "Admin"},
+        headers=_HEADERS,
+    )
+    await client.post(
+        "/api/auth/login",
+        json={"email": _ADMIN_EMAIL, "password": _ADMIN_PASSWORD},
+        headers=_HEADERS,
+    )
+
+
+async def _store_key(client: httpx.AsyncClient, key: str) -> None:
+    response = await client.put(
+        "/api/config/settings/model-key", json={"key": key}, headers=_HEADERS
+    )
+    assert response.status_code == 200
+    assert response.json()["configured"] is True
+
+
+def _corrupt_key_file(tmp_path: Path, user_id: str, content: str) -> None:
+    path = tmp_path / "keys" / f"{user_id}.json"
+    assert path.is_file(), "the key must be stored before corrupting it"
+    path.write_text(content, encoding="utf-8")
+
+
+async def _current_user_id(client: httpx.AsyncClient) -> str:
+    me = await client.get("/api/auth/me")
+    return me.json()["user_id"]
+
+
+async def _await_terminal_or_approval(client: httpx.AsyncClient, run_id: str) -> str:
+    for _ in range(300):
+        status = (await client.get(f"/api/runs/{run_id}")).json()["status"]
+        if status in ("done", "failed", "cancelled", "awaiting_approval"):
+            return status
+        await asyncio.sleep(0.01)
+    return status
+
+
+# ------------------------------------------------- corrupt envelope at the API
+
+
+async def test_config_status_degrades_honestly_on_garbage_envelope(tmp_path: Path) -> None:
+    """Garbage keys/<uid>.json -> config status 200 with a DEGRADED
+    tier (keyless/server) + the error surfaced in key_status.reason —
+    typed error surfacing, never a silent tier drop, never a 500."""
+    app = _app(tmp_path, {KEK_NAME: _KEK})
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _login_admin(client)
+        await _store_key(client, _USER_KEY)
+        user_id = await _current_user_id(client)
+        _corrupt_key_file(tmp_path, user_id, "this is garbage, not json")
+
+        config = await client.get("/api/config")
+        assert config.status_code == 200  # never a 500
+        body = config.json()
+        assert body["resolved_tier"] in ("server", "keyless")  # honest degradation
+        assert body["key_store"] == "enabled"
+        assert body["key_status"]["configured"] is False
+        assert body["key_status"]["reason"] is not None
+        assert "corrupt" in body["key_status"]["reason"].lower()
+
+
+async def test_config_status_degrades_honestly_on_tampered_envelope(tmp_path: Path) -> None:
+    """A tampered envelope -> same honest degradation + 'failed
+    authentication' reason — never the decrypted key, never a silent
+    'user' tier."""
+    app = _app(tmp_path, {KEK_NAME: _KEK})
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _login_admin(client)
+        await _store_key(client, _USER_KEY)
+        user_id = await _current_user_id(client)
+        original = json.loads((tmp_path / "keys" / f"{user_id}.json").read_text())
+        # Flip ciphertext bytes: the envelope stays valid JSON but
+        # decrypt must fail (InvalidTag -> typed 'tampered').
+        ct = base64.urlsafe_b64decode(original["entries"]["OLLAMA_API_KEY"]["ct"] + "===")
+        flipped = bytes([ct[0] ^ 0xFF]) + ct[1:]
+        original["entries"]["OLLAMA_API_KEY"]["ct"] = (
+            base64.urlsafe_b64encode(flipped).decode().rstrip("=")
+        )
+        _corrupt_key_file(tmp_path, user_id, json.dumps(original))
+
+        config = await client.get("/api/config")
+        assert config.status_code == 200
+        body = config.json()
+        assert body["resolved_tier"] in ("server", "keyless")
+        assert "authentication" in body["key_status"]["reason"].lower()
+        assert _USER_KEY not in config.text
+
+
+async def test_create_run_corrupt_envelope_is_honest_409(tmp_path: Path) -> None:
+    """create_run with a corrupt stored envelope -> 409 with the typed
+    error — the run is NOT created (never a wrong-key run, never a
+    silent tier fall)."""
+    app = _app(tmp_path, {KEK_NAME: _KEK})
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _login_admin(client)
+        await _store_key(client, _USER_KEY)
+        user_id = await _current_user_id(client)
+        _corrupt_key_file(tmp_path, user_id, "{corrupt")
+
+        created = await client.post(
+            "/api/runs", json={"question": "q", "methodology": "rapid-answer"}, headers=_HEADERS
+        )
+        assert created.status_code == 409
+        detail = created.json()["detail"].lower()
+        assert "corrupt" in detail or "key" in detail
+
+
+async def test_model_key_put_overwrites_after_corruption(tmp_path: Path) -> None:
+    """Recovery path: a user whose envelope corrupted can PUT a fresh
+    key (atomic overwrite) and return to the 'user' tier."""
+    app = _app(tmp_path, {KEK_NAME: _KEK})
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _login_admin(client)
+        await _store_key(client, _USER_KEY)
+        user_id = await _current_user_id(client)
+        _corrupt_key_file(tmp_path, user_id, "garbage")
+        config = await client.get("/api/config")
+        assert config.json()["resolved_tier"] != "user"
+
+        await _store_key(client, "fresh-key-value-9999")
+        config = await client.get("/api/config")
+        body = config.json()
+        assert body["resolved_tier"] == "user"
+        assert body["key_status"]["masked"].endswith("9999")
+
+
+# ------------------------------------------------------------- leak scan
+
+
+async def test_no_raw_key_in_full_session_response_surface(tmp_path: Path) -> None:
+    """Every response of a full session that stores, reads, and runs
+    with a user key — scanned for the raw key material (REQ-73)."""
+    app = _app(tmp_path, {KEK_NAME: _KEK})
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _login_admin(client)
+        put = await client.put(
+            "/api/config/settings/model-key",
+            json={"key": _USER_KEY},
+            headers=_HEADERS,
+        )
+        responses: list[httpx.Response] = [put]
+        for path in [
+            "/api/config",
+            "/api/config/settings",
+            "/api/config/settings/model-key",
+            "/api/auth/me",
+            "/api/methodologies",
+            "/api/admin/users",
+        ]:
+            responses.append(await client.get(path))
+        responses.append(
+            await client.put(
+                "/api/config/settings", json={"appearance": "dark"}, headers=_HEADERS
+            )
+        )
+
+        # A run executing under the user tier must not leak the key in
+        # any run response either.
+        created = await client.post(
+            "/api/runs", json={"question": "q", "methodology": "rapid-answer"}, headers=_HEADERS
+        )
+        assert created.status_code == 201
+        responses.append(created)
+        run_id = created.json()["id"]
+        status = await _await_terminal_or_approval(client, run_id)
+        responses.append(await client.get(f"/api/runs/{run_id}"))
+        if status == "awaiting_approval":
+            responses.append(
+                await client.post(f"/api/runs/{run_id}/approve", headers=_HEADERS)
+            )
+
+        for response in responses:
+            assert _USER_KEY not in response.text, "raw model key leaked in a response"
+        # And never on disk in plaintext.
+        for path in (tmp_path / "keys").iterdir():
+            assert _USER_KEY not in path.read_text(encoding="utf-8")
+
+
+# ---------------------------------------------------- AAD bind via the API
+
+
+async def test_second_user_cannot_shadow_first_users_key(tmp_path: Path) -> None:
+    """Two users, each with their own key: the second user's tier is
+    'user' via THEIR key, and the first user's key never affects the
+    second user's resolution (per-user AAD bind end to end)."""
+    app = _app(tmp_path, {KEK_NAME: _KEK})
+    transport = httpx.ASGITransport(app=app)
+
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as admin:
+        await _login_admin(admin)
+        await _store_key(admin, "first-user-key-aaaa")
+        config = await admin.get("/api/config")
+        assert config.json()["resolved_tier"] == "user"
+        assert config.json()["key_status"]["masked"].endswith("aaaa")
+        await admin.post(
+            "/api/admin/users",
+            json={
+                "email": _SECOND_EMAIL,
+                "password": _SECOND_PASSWORD,
+                "role": "user",
+            },
+            headers=_HEADERS,
+        )
+
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as second:
+        await second.post(
+            "/api/auth/login",
+            json={"email": _SECOND_EMAIL, "password": _SECOND_PASSWORD},
+            headers=_HEADERS,
+        )
+        # Before storing a key: keyless (no server key configured).
+        config = await second.get("/api/config")
+        assert config.json()["resolved_tier"] == "keyless"
+        assert "first-user-key" not in config.text
+
+        await _store_key(second, "second-user-key-bbbb")
+        config = await second.get("/api/config")
+        assert config.json()["resolved_tier"] == "user"
+        assert config.json()["key_status"]["masked"].endswith("bbbb")
+        assert "aaaa" not in config.text
+
+
+# ---------------------------------------------- settings store isolation
+
+
+async def test_settings_corruption_is_typed_not_crashing(tmp_path: Path) -> None:
+    """A corrupt settings file surfaces a typed SettingsStoreError —
+    the store fails honestly rather than silently serving defaults
+    over a corrupt payload."""
+    from researchx.auth.settings import SettingsStore, SettingsStoreError
+
+    app = _app(tmp_path, {KEK_NAME: _KEK})
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _login_admin(client)
+        user_id = await _current_user_id(client)
+        settings_dir = tmp_path / "settings"
+        settings_dir.mkdir(parents=True, exist_ok=True)
+        (settings_dir / f"{user_id}.json").write_text("{{not json", encoding="utf-8")
+
+        with pytest.raises(SettingsStoreError):
+            await SettingsStore(tmp_path).get(user_id)
+
+
+def test_key_store_error_is_adapter_error() -> None:
+    """The typed key-store error IS an AdapterError — the factory and
+    routes can catch one family (C3-06 contract)."""
+    from researchx.adapters.types import AdapterError
+    from researchx.auth.key_store import KeyStoreError
+
+    assert issubclass(KeyStoreError, AdapterError)

backend/tests/test_key_store_settings.py

@@ -0,0 +1,474 @@
+"""Key store + settings store suite (T-2.2/T-2.3, REQ-72/73).
+
+The adversarial core of the per-user key store: KEK decode rules
+(b64/hex/wrong-length/garbage), set/get round-trips, AAD binding
+(a copied envelope under another user FAILS — never a wrong-key leak),
+nonce uniqueness, masked-only status, disabled-honesty without a KEK,
+0600 file permissions, and the settings defaults/update round-trip.
+
+The STEP-4 adversarial extension (corrupt-entry surfacing, concurrent
+set_key atomicity, opt-in keyed live tier) lives at the bottom of this
+file under the "T-2.8 adversarial extension" banner.
+"""
+
+import asyncio
+import base64
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from researchx.adapters.secrets import EnvFileSecretsProvider
+from researchx.auth.key_store import KEK_NAME, KEY_SCOPE, KeyStore, KeyStoreError, load_kek_bytes
+from researchx.auth.settings import SettingsStore, UserSettings
+
+_KEK_RAW = os.urandom(32)
+_KEK_B64 = base64.urlsafe_b64encode(_KEK_RAW).decode()
+_KEK_HEX = _KEK_RAW.hex()
+_USER = "abcd2345"
+_OTHER_USER = "efgh6789"
+_RAW_KEY = "sk-live-key-abcd1234"
+
+
+def _secrets_with(values: dict[str, str], tmp_path: Path) -> EnvFileSecretsProvider:
+    env_file = tmp_path / ".env.secrets"
+    env_file.write_text("".join(f"{k}={v}\n" for k, v in values.items()), encoding="utf-8")
+    return EnvFileSecretsProvider(paths=[env_file])
+
+
+def _enabled_store(tmp_path: Path) -> KeyStore:
+    return KeyStore(_secrets_with({KEK_NAME: _KEK_B64}, tmp_path), tmp_path)
+
+
+# ---------------------------------------------------------------- KEK decode
+
+
+def test_kek_decode_b64(tmp_path: Path) -> None:
+    secrets = _secrets_with({KEK_NAME: _KEK_B64}, tmp_path)
+    assert load_kek_bytes(secrets) == _KEK_RAW
+
+
+def test_kek_decode_hex(tmp_path: Path) -> None:
+    secrets = _secrets_with({KEK_NAME: _KEK_HEX}, tmp_path)
+    assert load_kek_bytes(secrets) == _KEK_RAW
+
+
+def test_kek_wrong_length_raises(tmp_path: Path) -> None:
+    short = base64.urlsafe_b64encode(b"only-16-bytes!!").decode()
+    with pytest.raises(KeyStoreError) as exc_info:
+        load_kek_bytes(_secrets_with({KEK_NAME: short}, tmp_path))
+    assert "32 bytes" in str(exc_info.value)
+    assert exc_info.value.kind == "bad_kek"
+
+
+def test_kek_garbage_raises(tmp_path: Path) -> None:
+    with pytest.raises(KeyStoreError) as exc_info:
+        load_kek_bytes(_secrets_with({KEK_NAME: "!!!not-base64!!!"}, tmp_path))
+    assert exc_info.value.kind == "bad_kek"
+
+
+def test_kek_absent_is_none_not_error(tmp_path: Path) -> None:
+    assert load_kek_bytes(_secrets_with({}, tmp_path)) is None
+
+
+def test_bad_kek_disables_store_honestly(tmp_path: Path) -> None:
+    """A malformed KEK is not a crash and not a silent enable."""
+    store = KeyStore(_secrets_with({KEK_NAME: "garbage-value"}, tmp_path), tmp_path)
+    assert store.enabled is False
+    assert store.disabled_reason is not None
+    assert "misconfigured" in store.disabled_reason
+
+
+# ------------------------------------------------------------- round trips
+
+
+async def test_set_get_round_trip(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+    assert await store.get_key(_USER) == _RAW_KEY
+
+
+async def test_get_without_set_is_none(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    assert await store.get_key(_USER) is None
+
+
+async def test_set_overwrites_previous_key(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, "first-key-value")
+    await store.set_key(_USER, KEY_SCOPE, "second-key-value")
+    assert await store.get_key(_USER) == "second-key-value"
+
+
+async def test_envelope_shape_on_disk(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+    payload = json.loads((tmp_path / "keys" / f"{_USER}.json").read_text(encoding="utf-8"))
+    assert payload["v"] == 1
+    assert payload["alg"] == "AES-256-GCM"
+    assert "updated_at" in payload
+    entry = payload["entries"][KEY_SCOPE]
+    assert set(entry) == {"nonce", "ct", "updated_at"}
+    # Raw key material must not appear anywhere in the file.
+    assert _RAW_KEY not in json.dumps(payload)
+
+
+# -------------------------------------------------------------------- AAD
+
+
+async def test_aad_tamper_copy_to_other_user_fails(tmp_path: Path) -> None:
+    """The AAD is user_id: a file copied under another user's id FAILS
+    decrypt with a typed error — never returns the other user's key."""
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+
+    keys_dir = tmp_path / "keys"
+    (keys_dir / f"{_OTHER_USER}.json").write_text(
+        (keys_dir / f"{_USER}.json").read_text(encoding="utf-8"),
+        encoding="utf-8",
+    )
+
+    with pytest.raises(KeyStoreError) as exc_info:
+        await store.get_key(_OTHER_USER)
+    assert exc_info.value.kind == "tampered"
+    # Never the wrong user's key:
+    assert exc_info.value.args[0] != _RAW_KEY
+
+
+async def test_aad_tamper_masked_status_also_fails(tmp_path: Path) -> None:
+    """Status must not silently report configured=False for a tampered
+    envelope — that would be a silent tier drop."""
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+    keys_dir = tmp_path / "keys"
+    (keys_dir / f"{_OTHER_USER}.json").write_text(
+        (keys_dir / f"{_USER}.json").read_text(encoding="utf-8"),
+        encoding="utf-8",
+    )
+    with pytest.raises(KeyStoreError):
+        await store.masked_status(_OTHER_USER)
+
+
+async def test_kek_change_surfaces_as_tamper(tmp_path: Path) -> None:
+    """A re-provisioned KEK cannot read old envelopes — typed error,
+    never silent None (documented loss posture, G-105)."""
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+
+    new_kek = base64.urlsafe_b64encode(os.urandom(32)).decode()
+    rotated = KeyStore(_secrets_with({KEK_NAME: new_kek}, tmp_path), tmp_path)
+    with pytest.raises(KeyStoreError) as exc_info:
+        await rotated.get_key(_USER)
+    assert exc_info.value.kind == "tampered"
+
+
+# ------------------------------------------------------------------ nonces
+
+
+async def test_nonce_unique_across_writes(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    nonces = []
+    for i in range(3):
+        await store.set_key(_USER, KEY_SCOPE, f"key-number-{i}")
+        payload = json.loads((tmp_path / "keys" / f"{_USER}.json").read_text(encoding="utf-8"))
+        nonces.append(payload["entries"][KEY_SCOPE]["nonce"])
+    assert len(set(nonces)) == 3  # a GCM nonce must NEVER repeat under a KEK
+
+
+async def test_nonce_is_12_bytes(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+    payload = json.loads((tmp_path / "keys" / f"{_USER}.json").read_text(encoding="utf-8"))
+    nonce_b64 = payload["entries"][KEY_SCOPE]["nonce"]
+    assert len(base64.urlsafe_b64decode(nonce_b64 + "===")) == 12
+
+
+# ------------------------------------------------------------ masked status
+
+
+async def test_masked_status_never_returns_raw_key(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+    status = await store.masked_status(_USER)
+    assert status["configured"] is True
+    assert status["masked"].endswith(_RAW_KEY[-4:])
+    assert _RAW_KEY not in json.dumps(status)
+    assert status["masked"].startswith("…"[:1]) or status["masked"][0] in ("…", ".")
+
+
+async def test_masked_status_unconfigured(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    status = await store.masked_status(_USER)
+    assert status["configured"] is False
+    assert status["masked"] is None
+
+
+# -------------------------------------------------------- disabled honesty
+
+
+async def test_disabled_store_set_rejected_honestly(tmp_path: Path) -> None:
+    store = KeyStore(_secrets_with({}, tmp_path), tmp_path)  # no KEK
+    assert store.enabled is False
+    with pytest.raises(KeyStoreError) as exc_info:
+        await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+    assert exc_info.value.kind == "disabled"
+    assert "RESEARCHX_KEK" in str(exc_info.value)
+    # And nothing was written to disk.
+    assert not (tmp_path / "keys" / f"{_USER}.json").exists()
+
+
+async def test_disabled_store_get_returns_none(tmp_path: Path) -> None:
+    store = KeyStore(_secrets_with({}, tmp_path), tmp_path)
+    assert await store.get_key(_USER) is None
+
+
+async def test_disabled_store_status_says_disabled(tmp_path: Path) -> None:
+    store = KeyStore(_secrets_with({}, tmp_path), tmp_path)
+    status = await store.masked_status(_USER)
+    assert status["disabled"] is True
+    assert "RESEARCHX_KEK" in str(status["reason"])
+    assert status["configured"] is False
+
+
+async def test_disabled_store_with_stored_key_surfaces_error(tmp_path: Path) -> None:
+    """The loss posture made visible: a KEK vanished after keys were
+    stored — reads must surface an error state, never silently None
+    (which would look like 'no key configured')."""
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+
+    gone = KeyStore(_secrets_with({}, tmp_path), tmp_path)
+    with pytest.raises(KeyStoreError) as exc_info:
+        await gone.get_key(_USER)
+    assert exc_info.value.kind == "disabled"
+    with pytest.raises(KeyStoreError):
+        await gone.masked_status(_USER)
+
+
+async def test_unsupported_scope_rejected(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    with pytest.raises(KeyStoreError):
+        await store.set_key(_USER, "TAVILY_API_KEY", "should-not-work")
+
+
+# ------------------------------------------------------------ file perms
+
+
+async def test_key_file_perms_0600(tmp_path: Path) -> None:
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+    mode = (tmp_path / "keys" / f"{_USER}.json").stat().st_mode & 0o777
+    assert mode == 0o600
+
+
+def test_key_store_docstring_documents_loss_posture() -> None:
+    """G-105: the loss posture must be stated where the keys live."""
+    import researchx.auth.key_store as key_store_module
+
+    doc = key_store_module.__doc__ or ""
+    assert "KEK-loss" in doc or "unrecoverable" in doc
+    assert "back up the KEK" in doc
+
+
+# ------------------------------------------------------------- settings
+
+
+async def test_settings_defaults_for_fresh_user(tmp_path: Path) -> None:
+    store = SettingsStore(tmp_path)
+    settings = await store.get(_USER)
+    assert settings.planner_model
+    assert settings.writer_model
+    assert settings.methodology_defaults == {}
+    assert settings.appearance == "system"
+    # GET never writes:
+    assert not (tmp_path / "settings" / f"{_USER}.json").exists()
+
+
+async def test_settings_update_round_trip(tmp_path: Path) -> None:
+    store = SettingsStore(tmp_path)
+    updated = await store.update(_USER, UserSettings(planner_model="m1", writer_model="m2"))
+    assert updated.planner_model == "m1"
+    assert updated.writer_model == "m2"
+    assert updated.appearance == "system"  # untouched field keeps default
+
+    reloaded = await store.get(_USER)
+    assert reloaded.planner_model == "m1"
+    assert reloaded.methodology_defaults == {}
+
+
+async def test_settings_partial_update_preserves_other_fields(tmp_path: Path) -> None:
+    store = SettingsStore(tmp_path)
+    await store.update(_USER, UserSettings(planner_model="keep-planner", appearance="dark"))
+    updated = await store.update(_USER, UserSettings(appearance="light"))
+    assert updated.planner_model == "keep-planner"  # survived the partial write
+    assert updated.appearance == "light"
+
+
+async def test_settings_methodology_defaults_round_trip(tmp_path: Path) -> None:
+    store = SettingsStore(tmp_path)
+    payload = UserSettings(methodology_defaults={"rapid-answer": {"depth": 2}})
+    await store.update(_USER, payload)
+    reloaded = await store.get(_USER)
+    assert reloaded.methodology_defaults == {"rapid-answer": {"depth": 2}}
+
+
+async def test_settings_update_validates_merged_payload_before_write(tmp_path: Path) -> None:
+    """P2-verify P0 regression: the store never writes a payload it
+    cannot read back — a null field that slipped past model_copy (which
+    skips validation) is refused before touching disk."""
+    store = SettingsStore(tmp_path)
+    await store.update(_USER, UserSettings(planner_model="keep-me"))
+    poisoned = await store.get(_USER)
+    poisoned = poisoned.model_copy(update={"planner_model": None})
+    with pytest.raises(ValueError):
+        await store.update(_USER, poisoned)
+    reloaded = await store.get(_USER)
+    assert reloaded.planner_model == "keep-me"  # on-disk payload untouched
+
+
+async def test_settings_isolated_per_user(tmp_path: Path) -> None:
+    store = SettingsStore(tmp_path)
+    await store.update(_USER, UserSettings(appearance="dark"))
+    other = await store.get(_OTHER_USER)
+    assert other.appearance == "system"  # fresh defaults, no bleed
+    assert not (tmp_path / "settings" / f"{_OTHER_USER}.json").exists()
+
+
+async def test_settings_corrupt_payload_surfaces_typed_error(tmp_path: Path) -> None:
+    store = SettingsStore(tmp_path)
+    settings_dir = tmp_path / "settings"
+    settings_dir.mkdir(parents=True, exist_ok=True)
+    (settings_dir / f"{_USER}.json").write_text("{not json", encoding="utf-8")
+    from researchx.auth.settings import SettingsStoreError
+
+    with pytest.raises((SettingsStoreError, ValueError)):
+        await store.get(_USER)
+
+
+# ================================================== T-2.8 adversarial extension
+# (security-engineer hat — corrupt-entry surfacing, concurrent-set
+# atomicity, and the opt-in keyed live tier. See STEP 4.)
+
+
+async def test_corrupt_envelope_surfaces_typed_error_never_silent_drop(tmp_path: Path) -> None:
+    """Garbage in keys/<uid>.json → KeyStoreError('unreadable'), never
+    a silent None (which would silently drop the user's tier)."""
+    store = _enabled_store(tmp_path)
+    keys_dir = tmp_path / "keys"
+    keys_dir.mkdir(parents=True, exist_ok=True)
+    (keys_dir / f"{_USER}.json").write_text("this is not json at all", encoding="utf-8")
+    with pytest.raises(KeyStoreError) as exc_info:
+        await store.get_key(_USER)
+    assert exc_info.value.kind == "unreadable"
+
+
+async def test_corrupt_entry_fields_surface_typed_error(tmp_path: Path) -> None:
+    """Structurally-valid JSON with missing/invalid fields — typed error."""
+    store = _enabled_store(tmp_path)
+    keys_dir = tmp_path / "keys"
+    keys_dir.mkdir(parents=True, exist_ok=True)
+    (keys_dir / f"{_USER}.json").write_text(
+        json.dumps({"v": 1, "alg": "AES-256-GCM", "entries": {"OLLAMA_API_KEY": {"nonce": "xx"}}}),
+        encoding="utf-8",
+    )
+    with pytest.raises(KeyStoreError):
+        await store.get_key(_USER)
+
+
+async def test_bit_rot_ciphertext_surfaces_tamper(tmp_path: Path) -> None:
+    """Flipping ciphertext bytes → InvalidTag → typed 'tampered'."""
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, _RAW_KEY)
+    path = tmp_path / "keys" / f"{_USER}.json"
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    ct = base64.urlsafe_b64decode(payload["entries"][KEY_SCOPE]["ct"] + "===")
+    flipped = bytes([ct[0] ^ 0xFF]) + ct[1:]
+    payload["entries"][KEY_SCOPE]["ct"] = base64.urlsafe_b64encode(flipped).decode().rstrip("=")
+    path.write_text(json.dumps(payload), encoding="utf-8")
+    with pytest.raises(KeyStoreError) as exc_info:
+        await store.get_key(_USER)
+    assert exc_info.value.kind == "tampered"
+
+
+async def test_concurrent_set_key_never_tears_the_file(tmp_path: Path) -> None:
+    """Concurrent writes to the same user: every reader (including a
+    second KeyStore handle over the same root) sees a valid envelope —
+    the tmp+replace idiom leaves no torn files."""
+    store = _enabled_store(tmp_path)
+    await asyncio.gather(
+        *(store.set_key(_USER, KEY_SCOPE, f"concurrent-key-{i}") for i in range(16))
+    )
+    # The final file is one of the written keys, decryptable, well-formed.
+    final = await store.get_key(_USER)
+    assert final is not None
+    assert final.startswith("concurrent-key-")
+
+    # A second handle (fresh process view) reads the same valid file.
+    second = KeyStore(_secrets_with({KEK_NAME: _KEK_B64}, tmp_path), tmp_path)
+    again = await second.get_key(_USER)
+    assert again == final
+    payload = json.loads((tmp_path / "keys" / f"{_USER}.json").read_text(encoding="utf-8"))
+    assert payload["v"] == 1  # full envelope, never a partial write
+    # No tmp strays left behind.
+    assert [p.name for p in (tmp_path / "keys").iterdir() if p.name.endswith(".tmp")] == []
+
+
+async def test_set_key_atomic_under_concurrent_reads(tmp_path: Path) -> None:
+    """Reads racing a write never observe a torn file."""
+    store = _enabled_store(tmp_path)
+    await store.set_key(_USER, KEY_SCOPE, "initial-key")
+
+    async def _reader() -> str | None:
+        for _ in range(20):
+            try:
+                key = await store.get_key(_USER)
+                if key is None:
+                    raise AssertionError("envelope vanished mid-race")
+            except KeyStoreError as exc:
+                raise AssertionError(f"torn read surfaced: {exc}") from exc
+        return None
+
+    async def _writer() -> None:
+        for i in range(10):
+            await store.set_key(_USER, KEY_SCOPE, f"racing-key-{i}")
+
+    await asyncio.gather(_reader(), _writer())
+    assert (await store.get_key(_USER)).startswith("racing-key-")
+
+
+def test_keyed_live_tier_marker_registered() -> None:
+    """The opt-in keyed live tier is marked `live` and skipped by
+    default (same pattern as test_live_smoke.py): the marker must be
+    registered in the pytest config so the opt-in test below skips
+    cleanly in zero-key CI."""
+    import tomllib
+
+    config = tomllib.loads((Path(__file__).resolve().parents[1] / "pyproject.toml").read_text())
+    markers = config["tool"]["pytest"]["ini_options"]["markers"]
+    assert any(str(m).startswith("live:") for m in markers)
+
+
+# ------------------------------------------------------- opt-in live tier
+
+
+@pytest.mark.live
+async def test_live_keyed_tier_end_to_end(tmp_path: Path) -> None:
+    """Opt-in keyed tier (skipped by default, like test_live_smoke):
+    with a real RESEARCHX_KEK + OLLAMA_API_KEY in the secrets scope, a
+    keyed user gets real inference through the REQ-74 chain."""
+    secrets_paths = [
+        Path.cwd() / ".ciagent" / ".env.secrets",
+        Path.cwd().parents[1] / ".ciagent" / ".env.secrets",
+    ]
+    env = EnvFileSecretsProvider(paths=secrets_paths)
+    kek = env.resolve(KEK_NAME)
+    model_key = env.resolve("OLLAMA_API_KEY")
+    if not kek or not model_key:
+        pytest.skip("RESEARCHX_KEK/OLLAMA_API_KEY not present — live tier is opt-in")
+
+    store = KeyStore(env, tmp_path)
+    assert store.enabled, "with a configured KEK the store must be enabled"
+    await store.set_key("live0001", KEY_SCOPE, model_key)
+    resolved = await store.get_key("live0001")
+    assert resolved == model_key

backend/tests/test_live_routes.py

@@ -0,0 +1,687 @@
+"""Live-surface route tests (T-3.3, REQ-76..82).
+
+Every new/reworked route over a fixture disk tree: report/ledger
+disk-read with pre-artifact DONE fallback, library/connections/graph/
+tasks/suggestions, refine (200 on fakes, honest 503 on adapter
+failure), profile round-trip, and the FRESH-APP-OVER-EXISTING-DATA-
+ROOT test (P-8 full closure — every read route correct against a
+second create_app with zero in-memory actors).
+"""
+
+import asyncio
+import json
+from pathlib import Path
+
+import httpx
+
+from researchx.adapters.fakes import CORPUS, FakeModelAdapter, FakeSearchAdapter
+from researchx.adapters.types import AdapterError, ChatResult, ModelMessage
+from researchx.api.app import create_app
+from researchx.auth.guard import CSRF_HEADER
+
+_PLAN = json.dumps(
+    {"sub_questions": ["verification passes"], "source_universe": ["web"], "outline": ["intro"]}
+)
+_WRITER = "# Research Memo\n\nClaim [p-1] and claim [p-2].\n"
+
+_HEADERS = {CSRF_HEADER: "1"}
+
+_DEV = "dev00000"  # the synthetic dev admin (auth_enabled=False harness)
+
+
+def _state(run_id: str, question: str, state: str, created_at: str, plan: dict | None = None) -> dict:
+    return {
+        "run_id": run_id,
+        "question": question,
+        "context": "",
+        "methodology_slug": "deep-report",
+        "state": state,
+        "owner_id": _DEV,
+        "plan": plan if plan is not None else {
+            "sub_questions": ["battery density question"],
+            "source_universe": ["web"],
+            "outline": ["intro"],
+        },
+        "depth_cursor": 0,
+        "depth_target": 1,
+        "counters": {},
+        "probe": None,
+        "created_at": created_at,
+        "updated_at": created_at,
+    }
+
+
+def _seed_run(
+    tmp_path: Path,
+    run_id: str,
+    *,
+    state: str,
+    question: str = "What about battery research?",
+    created_at: str = "2026-09-20T10:00:00Z",
+    plan: dict | None = None,
+    report_markdown: str | None = None,
+    report_json: dict | None = None,
+    evidence_json: dict | None = None,
+    ledger_json: dict | None = None,
+    owner: str = _DEV,
+) -> None:
+    run_dir = tmp_path / "runs" / owner / run_id
+    run_dir.mkdir(parents=True, exist_ok=True)
+    (run_dir / "state.json").write_text(
+        json.dumps(_state(run_id, question, state, created_at, plan)), encoding="utf-8"
+    )
+    if report_markdown is not None:
+        (run_dir / "report.md").write_text(report_markdown, encoding="utf-8")
+    if report_json is not None:
+        (run_dir / "report.json").write_text(json.dumps(report_json), encoding="utf-8")
+    if evidence_json is not None:
+        (run_dir / "evidence.json").write_text(json.dumps(evidence_json), encoding="utf-8")
+    if ledger_json is not None:
+        (run_dir / "ledger.json").write_text(json.dumps(ledger_json), encoding="utf-8")
+
+
+_REPORT_JSON = {
+    "v": 1,
+    "run_id": "runaaaa1",
+    "owner_id": _DEV,
+    "title": "Battery Advances",
+    "question": "What about battery research?",
+    "methodology_slug": "deep-report",
+    "generated_at": "2026-09-20T10:05:00Z",
+    "sections": [
+        {"heading": "Research Memo", "body": "The verified core finding [^p1]."}
+    ],
+    "citations": [
+        {
+            "passage_id": "p1",
+            "url": "https://example.org/x",
+            "title": "Verification passes",
+            "quote": "The verified core finding.",
+            "health": "live",
+            "authority_tier": "reference",
+        }
+    ],
+}
+_EVIDENCE_JSON = {
+    "v": 1,
+    "run_id": "runaaaa1",
+    "passages": [
+        {
+            "passage_id": "p1",
+            "url": "https://example.org/x",
+            "title": "Verification passes",
+            "quote": "The verified core finding.",
+            "text": "The verified core finding in full, stored at DONE.",
+        }
+    ],
+}
+_LEDGER_JSON = {
+    "run_id": "runaaaa1",
+    "generated_at": "2026-09-20T10:05:00Z",
+    "entries": [
+        {
+            "url": "https://example.org/x",
+            "visited_at": "2026-09-20T10:04:00Z",
+            "passages": ["p-1"],
+            "claims_supported": 2,
+            "health": "live",
+            "authority_tier": "reference",
+        }
+    ],
+    "checklist": {"run_id": "runaaaa1", "citations_checked": 1},
+}
+
+
+def _seed_tree(tmp_path: Path) -> Path:
+    """The route fixture tree under the dev owner:
+    - runaaaa1: DONE with report.md + report.json + evidence.json + ledger
+    - runbbbb1: DONE pre-artifact (report.md only — no report.json)
+    - runcccc1: non-terminal (SEARCHING) — swept to CANCELLED by create_app
+    """
+    _seed_run(
+        tmp_path,
+        "runaaaa1",
+        state="DONE",
+        report_markdown="# Research Memo\n\nThe verified core finding [p-1].\n",
+        report_json=_REPORT_JSON,
+        evidence_json=_EVIDENCE_JSON,
+        ledger_json=_LEDGER_JSON,
+    )
+    _seed_run(
+        tmp_path,
+        "runbbbb1",
+        state="DONE",
+        question="A pre-artifact done run?",
+        created_at="2026-09-19T10:00:00Z",
+        report_markdown="# Old Report\n\nRaw [p-1] markers only.\n",
+    )
+    _seed_run(
+        tmp_path,
+        "runcccc1",
+        state="SEARCHING",
+        question="Swept mid-flight question?",
+        created_at="2026-09-21T10:00:00Z",
+    )
+    return tmp_path
+
+
+def _fake_app(tmp_path: Path, canned: list[ChatResult] | None = None) -> object:
+    return create_app(
+        storage_dir=tmp_path,
+        model_adapter=FakeModelAdapter(canned=canned or [ChatResult(content=_PLAN, model="p")]),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=False,
+        data_dir=tmp_path,
+    )
+
+
+async def _client(app: object) -> httpx.AsyncClient:
+    return httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app),  # type: ignore[arg-type]
+        base_url="http://testserver",
+    )
+
+
+# --------------------------------------------------------------- report route
+
+
+async def test_report_route_disk_read_returns_full_payload(tmp_path: Path) -> None:
+    _seed_tree(tmp_path)
+    async with await _client(_fake_app(tmp_path)) as client:
+        response = await client.get("/api/runs/runaaaa1/report")
+        assert response.status_code == 200
+        body = response.json()
+        assert body["run_id"] == "runaaaa1"
+        assert "[p-1]" in body["markdown"]  # raw form retained (back-compat)
+        assert body["report"] == _REPORT_JSON
+        assert body["evidence"] == _EVIDENCE_JSON
+
+
+async def test_report_route_pre_artifact_done_fallback(tmp_path: Path) -> None:
+    """A DONE run from before T-3.1 (report.md only): markdown served,
+    null report/evidence — never a 500 (D-106)."""
+    _seed_tree(tmp_path)
+    async with await _client(_fake_app(tmp_path)) as client:
+        response = await client.get("/api/runs/runbbbb1/report")
+        assert response.status_code == 200
+        body = response.json()
+        assert body["run_id"] == "runbbbb1"
+        assert "Raw [p-1] markers" in body["markdown"]
+        assert body["report"] is None
+        assert body["evidence"] is None
+
+
+async def test_report_route_missing_run_404(tmp_path: Path) -> None:
+    _seed_tree(tmp_path)
+    async with await _client(_fake_app(tmp_path)) as client:
+        assert (await client.get("/api/runs/zzzz9999/report")).status_code == 404
+
+
+async def test_ledger_route_disk_read(tmp_path: Path) -> None:
+    _seed_tree(tmp_path)
+    async with await _client(_fake_app(tmp_path)) as client:
+        response = await client.get("/api/runs/runaaaa1/ledger")
+        assert response.status_code == 200
+        assert response.json() == _LEDGER_JSON
+        assert (await client.get("/api/runs/zzzz9999/ledger")).status_code == 404
+
+
+# ------------------------------------------------------------ run list route
+
+
+async def test_runs_route_lists_from_disk_recent_first(tmp_path: Path) -> None:
+    """GET /api/runs from disk state files; the SEARCHING fixture is
+    swept to CANCELLED at create_app — it surfaces cancelled, NOT open
+    (post-sweep honesty)."""
+    _seed_tree(tmp_path)
+    async with await _client(_fake_app(tmp_path)) as client:
+        response = await client.get("/api/runs")
+        assert response.status_code == 200
+        runs = response.json()
+        assert [run["id"] for run in runs] == ["runcccc1", "runaaaa1", "runbbbb1"]
+        statuses = {run["id"]: run["status"] for run in runs}
+        assert statuses["runcccc1"] == "cancelled"  # swept, honest
+        assert statuses["runaaaa1"] == "done"
+        assert statuses["runbbbb1"] == "done"
+        first = runs[1]
+        assert first["question"] == "What about battery research?"
+        assert first["methodology"] == "deep-report"
+        assert first["plan"]["sub_questions"] == ["battery density question"]
+
+
+# ----------------------------------------------------------- library routes
+
+
+async def test_library_route(tmp_path: Path) -> None:
+    _seed_tree(tmp_path)
+    async with await _client(_fake_app(tmp_path)) as client:
+        response = await client.get("/api/library")
+        assert response.status_code == 200
+        body = response.json()
+        assert [folder["id"] for folder in body["folders"]] == ["deep-report-battery"]
+        assert [report["runId"] for report in body["reports"]] == ["runaaaa1", "runbbbb1"]
+        first = body["reports"][0]
+        assert first["title"] == "Battery Advances"
+        assert first["citationCount"] == 1
+        assert first["category"] == "deep-report-battery"
+        # title sort: "Battery Advances" < "Deep Report — A pre-artifact..."
+        titled = await client.get("/api/library?sort=title")
+        assert [r["runId"] for r in titled.json()["reports"]] == ["runaaaa1", "runbbbb1"]
+
+
+async def test_connections_graph_tasks_suggestions_routes(tmp_path: Path) -> None:
+    _seed_tree(tmp_path)
+    async with await _client(_fake_app(tmp_path)) as client:
+        connections = await client.get("/api/library/connections")
+        assert connections.status_code == 200
+        # runaaaa1 has a ledger; runbbbb1 has none -> no shared URL, and
+        # same methodology+category -> related-topic edge.
+        assert connections.json() == [
+            {
+                "fromReportId": "rep-runbbbb1",
+                "toReportId": "rep-runaaaa1",
+                "kind": "related-topic",
+                "label": "Adjacent topic",
+            }
+        ]
+
+        graph = await client.get("/api/graph")
+        assert graph.status_code == 200
+        payload = graph.json()
+        assert {node["id"] for node in payload["nodes"]} == {"runaaaa1", "runbbbb1"}
+        node = next(n for n in payload["nodes"] if n["id"] == "runaaaa1")
+        assert node["topic"] == "Battery Advances"
+        assert node["linkedSources"] == ["https://example.org/x"]
+        assert payload["edges"] == [{"fromId": "runbbbb1", "toId": "runaaaa1", "sharedSourceCount": 0}]
+
+        tasks = await client.get("/api/tasks")
+        assert tasks.status_code == 200
+        items = {item["id"]: item for item in tasks.json()}
+        assert items["runaaaa1#0"]["status"] == "done"
+        assert items["runbbbb1#0"]["status"] == "done"
+        # The swept CANCELLED run's question stays OPEN (D-114).
+        assert items["runcccc1#0"]["status"] == "open"
+        assert items["runcccc1#0"]["question"] == "battery density question"
+
+        suggestions = await client.get("/api/suggestions")
+        assert suggestions.status_code == 200
+        assert suggestions.json() == [
+            {
+                "id": "sug-runcccc1#0",
+                "question": "battery density question",
+                "sourceRunId": "runcccc1",
+                "sourceReportTitle": "Deep Report — Swept mid-flight question?",
+            }
+        ]
+
+
+async def test_fresh_user_empty_states(tmp_path: Path) -> None:
+    """Honest empty states: no synthetic content anywhere."""
+    async with await _client(_fake_app(tmp_path)) as client:
+        assert (await client.get("/api/library")).json() == {"folders": [], "reports": []}
+        assert (await client.get("/api/library/connections")).json() == []
+        assert (await client.get("/api/graph")).json() == {"nodes": [], "edges": []}
+        assert (await client.get("/api/tasks")).json() == []
+        assert (await client.get("/api/suggestions")).json() == []
+        assert (await client.get("/api/runs")).json() == []
+
+
+# ---------------------------------------------------------------- refine
+
+
+class _RefineModel:
+    """Fake model for the refine exchange: answers the questions prompt,
+    then the compose prompt; a second instance answers with an
+    AdapterError to pin the honest 503."""
+
+    def __init__(self, fail: bool = False) -> None:
+        self._fail = fail
+        self._calls = 0
+
+    async def chat(
+        self,
+        messages: list[ModelMessage],
+        *,
+        model: str,
+        temperature: float = 0.2,
+        json_mode: bool = False,
+    ) -> ChatResult:
+        del messages, temperature, model
+        if self._fail:
+            raise AdapterError("no local model reachable")
+        self._calls += 1
+        if self._calls == 1:
+            return ChatResult(
+                content=json.dumps(
+                    {
+                        "questions": [
+                            "What scope matters most?",
+                            "What decision will this inform?",
+                            "How deep should the answer go?",
+                        ]
+                    }
+                ),
+                model="fake-refine",
+            )
+        return ChatResult(
+            content=json.dumps(
+                {
+                    "question": "How do batteries work — focusing on density?",
+                    "context": "Feeds a supplier decision. Depth: executive summary.",
+                }
+            ),
+            model="fake-refine",
+        )
+
+    async def list_models(self) -> list[str]:
+        return ["fake-refine"]
+
+    def roles(self) -> object:
+        from researchx.adapters.model import ModelRoles
+
+        return ModelRoles(planner="fake-refine", writer="fake-refine")
+
+
+async def test_refine_questions_and_compose(tmp_path: Path) -> None:
+    app = create_app(
+        storage_dir=tmp_path,
+        model_adapter=_RefineModel(),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=False,
+        data_dir=tmp_path,
+    )
+    async with await _client(app) as client:
+        asked = await client.post("/api/refine/questions", json={"draft": "how do batteries work?"})
+        assert asked.status_code == 200
+        assert asked.json() == {
+            "questions": [
+                "What scope matters most?",
+                "What decision will this inform?",
+                "How deep should the answer go?",
+            ]
+        }
+        composed = await client.post(
+            "/api/refine/compose",
+            json={"draft": "how do batteries work?", "answers": ["density", "supplier choice"]},
+        )
+        assert composed.status_code == 200
+        assert composed.json() == {
+            "question": "How do batteries work — focusing on density?",
+            "context": "Feeds a supplier decision. Depth: executive summary.",
+        }
+
+
+async def test_refine_honest_503_never_hang(tmp_path: Path) -> None:
+    """A keyless user with no reachable endpoint gets an honest 503 —
+    never a hang, never a silent success."""
+    app = create_app(
+        storage_dir=tmp_path,
+        model_adapter=_RefineModel(fail=True),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=False,
+        data_dir=tmp_path,
+    )
+    async with await _client(app) as client:
+        asked = await asyncio.wait_for(
+            client.post("/api/refine/questions", json={"draft": "q"}), timeout=5.0
+        )
+        assert asked.status_code == 503
+        composed = await asyncio.wait_for(
+            client.post(
+                "/api/refine/compose", json={"draft": "q", "answers": ["a"]}, headers=_HEADERS
+            ),
+            timeout=5.0,
+        )
+        assert composed.status_code == 503
+
+
+async def test_refine_requires_csrf_header_when_authed(tmp_path: Path) -> None:
+    """Refine POSTs are mutations: the CSRF header applies (T-3.6)."""
+    app = create_app(
+        storage_dir=tmp_path,
+        model_adapter=_RefineModel(),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=True,
+        data_dir=tmp_path,
+    )
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+        # register + login (both with the header)
+        await client.post(
+            "/api/auth/register",
+            json={"email": "a@example.org", "password": "long-enough-pass", "display_name": "A"},
+            headers=_HEADERS,
+        )
+        await client.post(
+            "/api/auth/login", json={"email": "a@example.org", "password": "long-enough-pass"}, headers=_HEADERS
+        )
+        no_header = await client.post("/api/refine/questions", json={"draft": "q"})
+        assert no_header.status_code == 403
+        with_header = await client.post("/api/refine/questions", json={"draft": "q"}, headers=_HEADERS)
+        assert with_header.status_code == 200
+
+
+# ---------------------------------------------------------------- profile
+
+
+async def test_profile_round_trip(tmp_path: Path) -> None:
+    app = create_app(
+        storage_dir=tmp_path,
+        model_adapter=_RefineModel(),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=True,
+        data_dir=tmp_path,
+    )
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+        await client.post(
+            "/api/auth/register",
+            json={"email": "first@example.org", "password": "long-enough-pass", "display_name": "First"},
+            headers=_HEADERS,
+        )
+        await client.post(
+            "/api/auth/login",
+            json={"email": "first@example.org", "password": "long-enough-pass"},
+            headers=_HEADERS,
+        )
+        got = await client.get("/api/profile")
+        assert got.status_code == 200
+        assert got.json() == {
+            "user_id": got.json()["user_id"],
+            "display_name": "First",
+            "email": "first@example.org",
+        }
+        put = await client.put(
+            "/api/profile", json={"display_name": "Renamed", "email": "new@example.org"}, headers=_HEADERS
+        )
+        assert put.status_code == 200
+        assert put.json()["display_name"] == "Renamed"
+        assert put.json()["email"] == "new@example.org"
+        again = await client.get("/api/profile")
+        assert again.json() == put.json()
+
+
+async def test_profile_email_unique_across_users(tmp_path: Path) -> None:
+    app = create_app(
+        storage_dir=tmp_path,
+        model_adapter=_RefineModel(),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=True,
+        data_dir=tmp_path,
+    )
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as admin:
+        await admin.post(
+            "/api/auth/register",
+            json={"email": "admin@example.org", "password": "long-enough-pass", "display_name": "A"},
+            headers=_HEADERS,
+        )
+        await admin.post(
+            "/api/auth/login", json={"email": "admin@example.org", "password": "long-enough-pass"}, headers=_HEADERS
+        )
+        created = await admin.post(
+            "/api/admin/users",
+            json={"email": "second@example.org", "password": "long-enough-pass", "role": "user"},
+            headers=_HEADERS,
+        )
+        assert created.status_code == 201
+        # admin tries to steal the second user's email
+        taken = await admin.put(
+            "/api/profile", json={"email": "second@example.org"}, headers=_HEADERS
+        )
+        assert taken.status_code == 409
+
+
+# ---------------------------------------------- cross-user isolation (authed)
+
+
+async def test_cross_user_404_on_run_scoped_routes(tmp_path: Path) -> None:
+    """Owner-scoped disk reads: user 2 requesting user 1's run gets a
+    404 (no existence leak) — the owner dir simply doesn't exist under
+    user 2's storage view."""
+    app = create_app(
+        storage_dir=tmp_path,
+        model_adapter=_RefineModel(),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=True,
+        data_dir=tmp_path,
+    )
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as admin:
+        await admin.post(
+            "/api/auth/register",
+            json={"email": "admin@example.org", "password": "long-enough-pass", "display_name": "A"},
+            headers=_HEADERS,
+        )
+        await admin.post(
+            "/api/auth/login", json={"email": "admin@example.org", "password": "long-enough-pass"}, headers=_HEADERS
+        )
+        admin_id = (await admin.get("/api/auth/me")).json()["user_id"]
+        _seed_run(
+            tmp_path,
+            "runaaaa1",
+            state="DONE",
+            report_markdown="# Mine\n\n[p-1]\n",
+            report_json=_REPORT_JSON,
+            evidence_json=_EVIDENCE_JSON,
+            ledger_json=_LEDGER_JSON,
+            owner=admin_id,
+        )
+        await admin.post(
+            "/api/admin/users",
+            json={"email": "second@example.org", "password": "long-enough-pass", "role": "user"},
+            headers=_HEADERS,
+        )
+
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as second:
+        await second.post(
+            "/api/auth/login", json={"email": "second@example.org", "password": "long-enough-pass"}, headers=_HEADERS
+        )
+        assert (await second.get("/api/runs/runaaaa1/report")).status_code == 404
+        assert (await second.get("/api/runs/runaaaa1/ledger")).status_code == 404
+        # The owner-scoped collections are simply empty for user 2.
+        assert (await second.get("/api/runs")).json() == []
+        assert (await second.get("/api/library")).json() == {"folders": [], "reports": []}
+        assert (await second.get("/api/tasks")).json() == []
+        assert (await second.get("/api/suggestions")).json() == []
+
+
+# ------------------------------------- P-8 full closure: fresh app, same root
+
+
+async def test_full_run_over_http_writes_and_serves_artifacts(tmp_path: Path) -> None:
+    """End-to-end marker contract through the API: a run driven to DONE
+    persists report.json/evidence.json (T-3.1), and the reworked report
+    route serves normalized [^pN] bodies while report.md (via the
+    markdown field) keeps raw [p-N]."""
+    app = _fake_app(
+        tmp_path,
+        canned=[
+            ChatResult(content=_PLAN, model="fake-planner"),
+            ChatResult(content=_WRITER, model="fake-writer"),
+        ],
+    )
+    async with await _client(app) as client:
+        created = await client.post(
+            "/api/runs", json={"question": "How do engines run?", "methodology": "rapid-answer"}
+        )
+        assert created.status_code == 201
+        run_id = created.json()["id"]
+
+        for _ in range(400):  # await AWAITING_APPROVAL
+            status = (await client.get(f"/api/runs/{run_id}")).json()["status"]
+            if status == "awaiting_approval":
+                break
+            await asyncio.sleep(0.01)
+        await client.post(f"/api/runs/{run_id}/approve")
+        for _ in range(400):  # await DONE
+            status = (await client.get(f"/api/runs/{run_id}")).json()["status"]
+            if status == "done":
+                break
+            await asyncio.sleep(0.01)
+        assert status == "done"
+
+        report = (await client.get(f"/api/runs/{run_id}/report")).json()
+        assert report["report"] is not None
+        assert report["evidence"] is not None
+        # C3-10 through the API: bodies normalized, markdown raw.
+        joined = "\n".join(str(s["body"]) for s in report["report"]["sections"])
+        assert "[^p1]" in joined or "[^p2]" in joined
+        assert "[p-1]" not in joined
+        assert "[p-1]" in report["markdown"]
+        # citations + evidence ids are pN-form with real quotes.
+        for citation in report["report"]["citations"]:
+            assert citation["passage_id"].startswith("p")
+            assert "-" not in citation["passage_id"]
+            assert citation["quote"]
+        passages = report["evidence"]["passages"]
+        assert passages, "evidence must carry the full stored passages"
+        assert all(len(str(p["text"])) >= len(str(p["quote"])) for p in passages)
+
+        # The disk read-models see the run too (library/tasks derive).
+        library = (await client.get("/api/library")).json()
+        assert [r["runId"] for r in library["reports"]] == [run_id]
+        tasks = (await client.get("/api/tasks")).json()
+        assert all(item["status"] == "done" for item in tasks)
+
+
+async def test_fresh_app_over_existing_data_root(tmp_path: Path) -> None:
+    """P-8 full closure: a SECOND create_app over the same data root —
+    zero in-memory actors/registry — every read route still correct.
+    (The registry-independence proof; the first app's actor state is
+    unreachable by construction here.)"""
+    _seed_tree(tmp_path)
+    first = _fake_app(tmp_path)
+    del first  # the first app instance is discarded; nothing carries over
+
+    second = create_app(
+        storage_dir=tmp_path,
+        model_adapter=FakeModelAdapter(canned=[ChatResult(content=_PLAN, model="p")]),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=False,
+        data_dir=tmp_path,
+    )
+    async with await _client(second) as client:
+        # report: full payload, disk-read
+        report = (await client.get("/api/runs/runaaaa1/report")).json()
+        assert report["report"] == _REPORT_JSON
+        assert report["evidence"] == _EVIDENCE_JSON
+        assert "[p-1]" in report["markdown"]
+        # pre-artifact fallback survives the restart too
+        legacy = (await client.get("/api/runs/runbbbb1/report")).json()
+        assert legacy["report"] is None and legacy["markdown"]
+        # ledger
+        assert (await client.get("/api/runs/runaaaa1/ledger")).json() == _LEDGER_JSON
+        # run list: swept CANCELLED is cancelled, not open
+        statuses = {run["id"]: run["status"] for run in (await client.get("/api/runs")).json()}
+        assert statuses["runcccc1"] == "cancelled"
+        # library + connections + graph + tasks + suggestions
+        library = (await client.get("/api/library")).json()
+        assert [r["runId"] for r in library["reports"]] == ["runaaaa1", "runbbbb1"]
+        assert (await client.get("/api/library/connections")).status_code == 200
+        assert (await client.get("/api/graph")).status_code == 200
+        tasks = {item["id"]: item for item in (await client.get("/api/tasks")).json()}
+        assert tasks["runcccc1#0"]["status"] == "open"
+        assert (await client.get("/api/suggestions")).status_code == 200
+        # profile (dev harness GET works with zero stored runs)
+        assert (await client.get("/api/profile")).status_code == 200

backend/tests/test_main_entrypoint.py

@@ -0,0 +1,312 @@
+"""Production entrypoint suite (T-2.7 — P-3 backend closure).
+
+The live app built by ``researchx.api.main`` must be structurally
+incapable of serving fakes:
+
+- The per-run model path is the ModelAdapterFactory — a run executes
+  against an ``OllamaModelAdapter`` (resolved per user), never
+  ``FakeModelAdapter``. Pinned by asserting the factory resolves the
+  adapter and that the app instance holds no fake in the model slot.
+- ``auth_enabled=True`` hardwired: every business route 401s without a
+  session; there is no parameter or env that turns auth off.
+- ``cookie_secure=True``: the login cookie carries Secure (behind TLS).
+- The data root + secrets file come from env vars (RESEARCHX_DATA_DIR,
+  RESEARCHX_SECRETS_FILE) — the test seam is the natural runtime
+  config, parameterized not env-gated.
+"""
+
+import base64
+import json
+import os
+from pathlib import Path
+
+import httpx
+import pytest
+
+from researchx.adapters.fakes import FakeModelAdapter
+from researchx.auth.guard import CSRF_HEADER
+
+_HEADERS = {CSRF_HEADER: "1"}
+_KEK = base64.urlsafe_b64encode(os.urandom(32)).decode()
+
+_ADMIN_EMAIL = "admin@example.org"
+_ADMIN_PASSWORD = "correct-horse-battery"
+
+
+def _runtime_env(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, *, secrets: str | None, data_dir: Path
+) -> None:
+    """Point the production entry at test-owned locations.
+
+    This is the parameterization seam: main.py reads the same env vars
+    the container runtime passes (RESEARCHX_SECRETS_FILE via --env-file
+    conventions, RESEARCHX_DATA_DIR for the volume) — no test-only
+    gates exist in the module.
+    """
+    monkeypatch.setenv("RESEARCHX_DATA_DIR", str(data_dir))
+    if secrets is None:
+        monkeypatch.delenv("RESEARCHX_SECRETS_FILE", raising=False)
+    else:
+        env_file = tmp_path / "env.secrets"
+        env_file.write_text(secrets, encoding="utf-8")
+        monkeypatch.setenv("RESEARCHX_SECRETS_FILE", str(env_file))
+
+
+def _live_secrets(kek: bool = True, server_key: bool = True) -> str:
+    lines = []
+    if kek:
+        lines.append(f"RESEARCHX_KEK={_KEK}")
+    if server_key:
+        lines.append("OLLAMA_API_KEY=server-tier-key-value")
+    return "\n".join(lines) + "\n"
+
+
+async def _register_admin(client: httpx.AsyncClient) -> None:
+    await client.post(
+        "/api/auth/register",
+        json={"email": _ADMIN_EMAIL, "password": _ADMIN_PASSWORD, "display_name": "Admin"},
+        headers=_HEADERS,
+    )
+
+
+async def _login_with_secure_cookie(client: httpx.AsyncClient) -> str:
+    """Login and return the session cookie header value.
+
+    The production cookie carries Secure (hardwired, E-4); httpx's
+    cookie jar — like a browser over plain http — will not replay a
+    Secure cookie to a non-TLS origin. The tests therefore forward the
+    cookie explicitly: the ASGI transport is the TLS proxy's interior
+    leg, where the Secure flag does not apply.
+    """
+    login = await client.post(
+        "/api/auth/login",
+        json={"email": _ADMIN_EMAIL, "password": _ADMIN_PASSWORD},
+        headers=_HEADERS,
+    )
+    assert login.status_code == 200
+    return login.headers["set-cookie"].split(";")[0]
+
+
+def _auth_headers(cookie: str) -> dict[str, str]:
+    return {**_HEADERS, "cookie": cookie}
+
+
+# --------------------------------------------------------------- structure
+
+
+async def test_main_factory_resolves_real_adapters(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The P-3 backend closure: main's factory wiring resolves a real
+    OllamaModelAdapter per user — the production app can never serve
+    FakeModelAdapter (no fixed model adapter is even constructed when
+    a factory is wired; pinned structurally in app.py)."""
+    from researchx.api import main as main_module
+
+    _runtime_env(tmp_path, monkeypatch, secrets=_live_secrets(), data_dir=tmp_path / "data")
+    main_module.build_app()  # must import + build cleanly
+
+    from datetime import UTC, datetime
+
+    from researchx.adapters.model_factory import ModelAdapterFactory
+    from researchx.adapters.ollama import OllamaModelAdapter
+    from researchx.adapters.secrets import EnvFileSecretsProvider
+    from researchx.auth.key_store import KeyStore
+    from researchx.auth.models import UserPublic
+    from researchx.auth.settings import UserSettings
+
+    secrets_paths = main_module._secrets_paths()
+    assert secrets_paths, "the runtime env file must be discoverable"
+    secrets = EnvFileSecretsProvider(paths=secrets_paths)
+    factory = ModelAdapterFactory(secrets, KeyStore(secrets, tmp_path / "data"))
+    user = UserPublic(
+        user_id="abcd2345",
+        email="u@example.org",
+        display_name="U",
+        role="user",
+        active=True,
+        created_at=datetime.now(UTC),
+    )
+    adapter, tier = await factory.resolve(user, UserSettings())
+    assert isinstance(adapter, OllamaModelAdapter)
+    assert not isinstance(adapter, FakeModelAdapter)
+    assert tier in ("user", "server", "keyless")
+
+
+# --------------------------------------------------------------- behavior
+
+
+async def test_main_app_auth_hardwired(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """No env, no parameter: every business route 401s without a
+    session (REQ-85 — there is no auth_enabled=False path in main)."""
+    from researchx.api import main as main_module
+
+    _runtime_env(tmp_path, monkeypatch, secrets=_live_secrets(), data_dir=tmp_path / "data")
+    app = main_module.build_app()
+
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        for path in [
+            "/api/config",
+            "/api/config/settings",
+            "/api/config/settings/model-key",
+            "/api/methodologies",
+            "/api/runs/abcd2345",
+        ]:
+            response = await client.get(path)
+            assert response.status_code == 401, f"{path} leaked without auth"
+        # POST-only surface rejects unauthenticated POSTs identically.
+        assert (await client.post("/api/runs", json={}, headers=_HEADERS)).status_code == 401
+        # The public surface stays public (D-103).
+        assert (await client.get("/healthz")).status_code == 200
+
+
+async def test_main_app_cookie_secure(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """cookie_secure=True hardwired (E-4): the session cookie carries
+    Secure because the public surface is behind the TLS proxy."""
+    from researchx.api import main as main_module
+
+    data_dir = tmp_path / "data"
+    _runtime_env(tmp_path, monkeypatch, secrets=_live_secrets(), data_dir=data_dir)
+    app = main_module.build_app()
+
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _register_admin(client)
+        login = await client.post(
+            "/api/auth/login",
+            json={"email": _ADMIN_EMAIL, "password": _ADMIN_PASSWORD},
+            headers=_HEADERS,
+        )
+        assert login.status_code == 200
+        set_cookie = login.headers["set-cookie"].lower()
+        assert "secure" in set_cookie  # hardwired behind TLS
+
+
+async def test_main_app_config_resolves_tier_with_runtime_env(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """End to end through the production wiring: register + login +
+    GET /api/config shows the resolved tier and key-store state from
+    the runtime env file (KEK + server key -> server tier for a
+    keyless user, key_store enabled)."""
+    from researchx.api import main as main_module
+
+    data_dir = tmp_path / "data"
+    _runtime_env(tmp_path, monkeypatch, secrets=_live_secrets(), data_dir=data_dir)
+    app = main_module.build_app()
+
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _register_admin(client)
+        cookie = await _login_with_secure_cookie(client)
+        config = await client.get("/api/config", headers=_auth_headers(cookie))
+        assert config.status_code == 200
+        body = config.json()
+        assert body["resolved_tier"] == "server"  # server key present, no user key
+        assert body["key_store"] == "enabled"
+        assert body["model_adapter"] == "OllamaModelAdapter"  # never the fake
+
+
+async def test_main_app_keyless_without_keys(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """No KEK, no server key: key_store disabled, tier keyless — the
+    honest zero-key posture through the production wiring."""
+    from researchx.api import main as main_module
+
+    data_dir = tmp_path / "data"
+    _runtime_env(tmp_path, monkeypatch, secrets="", data_dir=data_dir)
+    app = main_module.build_app()
+
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _register_admin(client)
+        cookie = await _login_with_secure_cookie(client)
+        config = await client.get("/api/config", headers=_auth_headers(cookie))
+        body = config.json()
+        assert body["resolved_tier"] == "keyless"
+        assert body["key_store"] == "disabled"
+        assert body["key_status"]["disabled"] is True
+
+
+async def test_main_app_key_store_round_trip_with_kek(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """With a runtime KEK the production app accepts a user key and
+    resolves tier 'user' afterwards (REQ-73/74 chain end to end)."""
+    from researchx.api import main as main_module
+
+    data_dir = tmp_path / "data"
+    _runtime_env(tmp_path, monkeypatch, secrets=_live_secrets(), data_dir=data_dir)
+    app = main_module.build_app()
+
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _register_admin(client)
+        cookie = await _login_with_secure_cookie(client)
+        put = await client.put(
+            "/api/config/settings/model-key",
+            json={"key": "user-tier-key-7777"},
+            headers=_auth_headers(cookie),
+        )
+        assert put.status_code == 200
+        assert put.json()["configured"] is True
+
+        config = await client.get("/api/config", headers=_auth_headers(cookie))
+        body = config.json()
+        assert body["resolved_tier"] == "user"
+        assert body["key_status"]["masked"].endswith("7777")
+
+        # The key file lands under the DATA ROOT (not cwd).
+        me = await client.get("/api/auth/me", headers=_auth_headers(cookie))
+        user_id = me.json()["user_id"]
+        key_file = data_dir / "keys" / f"{user_id}.json"
+        assert key_file.is_file()
+        payload = json.loads(key_file.read_text(encoding="utf-8"))
+        assert "user-tier-key-7777" not in json.dumps(payload)  # encrypted at rest
+
+
+async def test_main_app_storage_is_data_root(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The config status storage_dir is the data-root string (D-107) —
+    never cwd-dependent."""
+    from researchx.api import main as main_module
+
+    data_dir = tmp_path / "data-root"
+    _runtime_env(tmp_path, monkeypatch, secrets=_live_secrets(), data_dir=data_dir)
+    app = main_module.build_app()
+
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://testserver"
+    ) as client:
+        await _register_admin(client)
+        cookie = await _login_with_secure_cookie(client)
+        config = await client.get("/api/config", headers=_auth_headers(cookie))
+        assert config.json()["storage_dir"] == str(data_dir)
+
+
+def test_main_module_has_no_auth_disable_surface() -> None:
+    """The main module exposes no auth_enabled parameter and reads no
+    env var that could disable auth (REQ-85 + C3-16)."""
+    import inspect
+
+    from researchx.api import main as main_module
+
+    signature = inspect.signature(main_module.build_app)
+    assert "auth_enabled" not in signature.parameters
+    assert "cookie_secure" not in signature.parameters
+    source = inspect.getsource(main_module)
+    assert "RESEARCHX_AUTH" not in source
+    assert "auth_enabled=False" not in source
+    # build_app passes auth_enabled=True exactly once (hardcoded).
+    build_source = inspect.getsource(main_module.build_app)
+    assert build_source.count("auth_enabled=") == 1
+    assert "auth_enabled=True" in build_source
+    assert "cookie_secure=True" in build_source

backend/tests/test_read_models.py

@@ -0,0 +1,508 @@
+"""Read-model unit tests (T-3.2, D-114/D-115 — REQ-76..79).
+
+A fixture disk tree — two users; DONE, CANCELLED, FAILED runs; a
+dotfile and a .tmp leftover — asserting categorization, sorting,
+shared-source/topic edges, tasks answered-iff DONE, suggestions
+(never synthetic, empty for fresh users), dotfile/tmp skip, and
+cross-user isolation at the read-model level.
+"""
+
+import json
+from pathlib import Path
+
+from researchx.api.read_models import (
+    categorize,
+    connections,
+    graph,
+    library,
+    list_runs,
+    suggestions,
+    tasks,
+    topic_tokens,
+)
+
+_U1 = "aaaa1111"
+_U2 = "bbbb2222"
+
+_PLAN_A = {
+    "sub_questions": ["battery energy density gains", "solid-state pilot production"],
+    "source_universe": ["web"],
+    "outline": ["intro"],
+}
+_PLAN_B = {
+    "sub_questions": ["battery safety testing standards"],
+    "source_universe": ["web"],
+    "outline": ["intro"],
+}
+_PLAN_CANCELLED = {
+    "sub_questions": ["abandoned open question"],
+    "source_universe": ["web"],
+    "outline": ["intro"],
+}
+_PLAN_FAILED = {"sub_questions": ["failed run question"], "source_universe": ["web"], "outline": []}
+_PLAN_INFLIGHT = {"sub_questions": ["still running question"], "source_universe": ["web"], "outline": []}
+
+_REPORT_A = {
+    "v": 1,
+    "run_id": "runaaaa1",
+    "owner_id": _U1,
+    "title": "Battery Advances",
+    "question": "What are the latest advances in solid-state batteries?",
+    "methodology_slug": "deep-report",
+    "generated_at": "2026-09-20T14:32:00Z",
+    "sections": [{"heading": "Report", "body": "Claim [^p1]."}],
+    "citations": [
+        {"passage_id": "p1", "url": "https://example.org/x", "title": "X", "quote": "q", "health": "live", "authority_tier": "reference"}
+    ],
+}
+_LEDGER_A = {
+    "run_id": "runaaaa1",
+    "generated_at": "2026-09-20T14:32:00Z",
+    "entries": [
+        {"url": "https://example.org/x", "visited_at": "2026-09-20T14:00:00Z", "passages": ["p-1"], "claims_supported": 1, "health": "live", "authority_tier": "reference"},
+        {"url": "https://example.org/y", "visited_at": "2026-09-20T14:00:00Z", "passages": ["p-2"], "claims_supported": 1, "health": "live", "authority_tier": "general"},
+    ],
+    "checklist": {},
+}
+
+_LEDGER_B = {
+    "run_id": "runbbbb1",
+    "generated_at": "2026-09-22T09:14:00Z",
+    "entries": [
+        {"url": "https://example.org/x", "visited_at": "2026-09-22T09:00:00Z", "passages": ["p-1"], "claims_supported": 2, "health": "live", "authority_tier": "reference"},
+        {"url": "https://example.org/z", "visited_at": "2026-09-22T09:00:00Z", "passages": ["p-2"], "claims_supported": 1, "health": "stale", "authority_tier": "general"},
+    ],
+    "checklist": {},
+}
+
+
+def _state(
+    run_id: str,
+    question: str,
+    slug: str,
+    state: str,
+    plan: dict | None,
+    created_at: str,
+) -> dict:
+    return {
+        "run_id": run_id,
+        "question": question,
+        "context": "",
+        "methodology_slug": slug,
+        "state": state,
+        "owner_id": _U1,
+        "plan": plan,
+        "depth_cursor": 0,
+        "depth_target": 1,
+        "counters": {},
+        "probe": None,
+        "created_at": created_at,
+        "updated_at": created_at,
+    }
+
+
+def _write_run(
+    base: Path,
+    owner: str,
+    run_id: str,
+    state: dict,
+    report: dict | None = None,
+    ledger: dict | None = None,
+) -> None:
+    run_dir = base / "runs" / owner / run_id
+    run_dir.mkdir(parents=True, exist_ok=True)
+    (run_dir / "state.json").write_text(json.dumps(state), encoding="utf-8")
+    if report is not None:
+        (run_dir / "report.json").write_text(json.dumps(report), encoding="utf-8")
+    if ledger is not None:
+        (run_dir / "ledger.json").write_text(json.dumps(ledger), encoding="utf-8")
+
+
+def _tree(tmp_path: Path) -> Path:
+    """The fixture tree: user 1 has DONE A (deep-report, battery), DONE
+    B (rapid-answer, battery safety), a CANCELLED run, and a FAILED
+    run; user 2 has one DONE run invisible to user 1."""
+    base = tmp_path
+    _write_run(
+        base,
+        _U1,
+        "runaaaa1",
+        _state(
+            "runaaaa1",
+            "What are the latest advances in solid-state batteries?",
+            "deep-report",
+            "DONE",
+            _PLAN_A,
+            "2026-09-20T14:32:00Z",
+        ),
+        report=_REPORT_A,
+        ledger=_LEDGER_A,
+    )
+    _write_run(
+        base,
+        _U1,
+        "runbbbb1",
+        _state(
+            "runbbbb1",
+            "How do battery safety standards evolve?",
+            "rapid-answer",
+            "DONE",
+            _PLAN_B,
+            "2026-09-22T09:14:00Z",
+        ),
+        ledger=_LEDGER_B,
+    )
+    _write_run(
+        base,
+        _U1,
+        "runcanc1",
+        _state(
+            "runcanc1",
+            "abandoned mid-flight",
+            "deep-report",
+            "CANCELLED",
+            _PLAN_CANCELLED,
+            "2026-09-21T10:00:00Z",
+        ),
+    )
+    _write_run(
+        base,
+        _U1,
+        "runfail1",
+        _state(
+            "runfail1",
+            "it broke",
+            "rapid-answer",
+            "FAILED",
+            _PLAN_FAILED,
+            "2026-09-23T10:00:00Z",
+        ),
+    )
+    # Defensive-scan fodder (D-115): dotfile + tmp leftovers + junk.
+    (base / "runs" / _U1 / ".hidden").mkdir(parents=True)
+    (base / "runs" / _U1 / "runbbbb1.tmp").mkdir(parents=True)
+    (base / "runs" / _U1 / "orphan001").mkdir(parents=True)  # no state.json: skipped
+    # An in-flight run (raw, pre-sweep — the read-model sees the state
+    # as written; the sweep happens at create_app in the route layer).
+    _write_run(
+        base,
+        _U1,
+        "runinflg1",
+        _state(
+            "runinflg1",
+            "still running",
+            "deep-report",
+            "SEARCHING",
+            _PLAN_INFLIGHT,
+            "2026-09-25T08:00:00Z",
+        ),
+    )
+    # The other user's run: invisible at every read-model level.
+    _write_run(
+        base,
+        _U2,
+        "runcccc1",
+        _state(
+            "runcccc1",
+            "user two's private research",
+            "deep-report",
+            "DONE",
+            _PLAN_B,
+            "2026-09-24T10:00:00Z",
+        ),
+        ledger=_LEDGER_A,
+    )
+    return base
+
+
+# ------------------------------------------------------------------ scanning
+
+
+def test_list_runs_scans_owner_partition_only(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    ids = [record.run_id for record in list_runs(base, _U1)]
+    # CANCELLED + FAILED + in-flight included; dotfile/tmp/orphan
+    # skipped; user 2's run absent.
+    assert set(ids) == {"runaaaa1", "runbbbb1", "runcanc1", "runfail1", "runinflg1"}
+
+
+def test_list_runs_orders_most_recent_first(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    ids = [record.run_id for record in list_runs(base, _U1)]
+    assert ids[0] == "runinflg1"  # 2026-09-25
+    assert ids[-1] == "runaaaa1"  # 2026-09-20
+
+
+def test_list_runs_skips_dotfiles_and_tmp(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    ids = {record.run_id for record in list_runs(base, _U1)}
+    assert ".hidden" not in ids
+    assert "runbbbb1.tmp" not in ids
+
+
+def test_list_runs_empty_for_fresh_user(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    assert list_runs(base, "cccc3333") == []
+
+
+# ------------------------------------------------------------ categorization
+
+
+def test_categorize_is_methodology_plus_first_topic_token() -> None:
+    record = list_runs  # placeholder to keep import honest
+    del record
+    from researchx.api.read_models import RunDiskRecord
+
+    run = RunDiskRecord(
+        run_id="runaaaa1",
+        state={
+            "run_id": "runaaaa1",
+            "question": "q",
+            "methodology_slug": "deep-report",
+            "state": "DONE",
+            "plan": _PLAN_A,
+            "created_at": "2026-09-20T14:32:00Z",
+        },
+    )
+    assert categorize(run) == "deep-report-battery"
+
+
+def test_topic_tokens_skip_stopwords_and_dedupe() -> None:
+    from researchx.api.read_models import RunDiskRecord
+
+    run = RunDiskRecord(
+        run_id="r",
+        state={
+            "run_id": "r",
+            "question": "q",
+            "methodology_slug": "rapid-answer",
+            "state": "DONE",
+            "plan": {"sub_questions": ["The what of battery battery gains"]},
+            "created_at": "2026-09-20T14:32:00Z",
+        },
+    )
+    assert topic_tokens(run) == ["battery", "gains"]
+
+
+# ------------------------------------------------------------------ library
+
+
+def test_library_folders_and_summaries(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    payload = library(base, _U1)
+    # Folders from the two DONE runs' categories, sorted by id.
+    assert [folder["id"] for folder in payload["folders"]] == [
+        "deep-report-battery",
+        "rapid-answer-battery",
+    ]
+    assert payload["folders"][0]["name"] == "Deep Report: Battery"
+    # Only DONE runs are filed (cancelled/failed produce nothing).
+    assert {report["runId"] for report in payload["reports"]} == {"runaaaa1", "runbbbb1"}
+    first = next(r for r in payload["reports"] if r["runId"] == "runaaaa1")
+    assert first["id"] == "rep-runaaaa1"
+    assert first["title"] == "Battery Advances"
+    assert first["methodologySlug"] == "deep-report"
+    assert first["category"] == "deep-report-battery"
+    assert first["generatedAt"] == "2026-09-20T14:32:00Z"
+    assert first["citationCount"] == 1
+    # Pre-artifact DONE run: falls back to state created_at + methodology title.
+    second = next(r for r in payload["reports"] if r["runId"] == "runbbbb1")
+    assert second["generatedAt"] == "2026-09-22T09:14:00Z"
+    assert second["title"] == "Rapid Answer — How do battery safety standards evolve?"
+
+
+def test_library_sort_recent_and_title(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    recent = [r["runId"] for r in library(base, _U1, sort="recent")["reports"]]
+    title = [r["runId"] for r in library(base, _U1, sort="title")["reports"]]
+    # recent: newest first (created_at desc).
+    assert recent == ["runbbbb1", "runaaaa1"]
+    # title: "Battery Advances" < "Rapid Answer — ..." A-Z.
+    assert title == ["runaaaa1", "runbbbb1"]
+    # unknown sort key falls back to recent.
+    assert library(base, _U1, sort="bogus")["reports"][0]["runId"] == "runbbbb1"
+
+
+def test_library_fresh_user_is_empty(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    payload = library(base, "cccc3333")
+    assert payload == {"folders": [], "reports": []}
+
+
+def test_library_cross_user_isolation(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    payload = library(base, _U1)
+    assert all(report["runId"] != "runcccc1" for report in payload["reports"])
+
+
+# ------------------------------------------------------------- connections
+
+
+def test_connections_shared_source_edge(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    edges = connections(base, _U1)
+    shared = [e for e in edges if e["kind"] == "shared-sources"]
+    # runaaaa1 + runbbbb1 share https://example.org/x (>=1 URL overlap).
+    assert shared == [
+        {
+            "fromReportId": "rep-runaaaa1",
+            "toReportId": "rep-runbbbb1",
+            "kind": "shared-sources",
+            "label": "1 shared source",
+        }
+    ]
+
+
+def test_connections_related_topic_edge_when_no_shared_urls(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    # Strip the shared URL: the two DONE runs then connect only via
+    # category (same methodology + first topic token) — no, they have
+    # DIFFERENT methodologies. Instead verify the pairing rule: with no
+    # shared URL and differing categories there is NO edge.
+    other = base / "runs" / _U1 / "runbbbb1" / "ledger.json"
+    payload = json.loads(other.read_text(encoding="utf-8"))
+    payload["entries"] = [e for e in payload["entries"] if e["url"] != "https://example.org/x"]
+    other.write_text(json.dumps(payload), encoding="utf-8")
+    edges = connections(base, _U1)
+    # deep-report-battery vs rapid-answer-battery: different methodology
+    # folders -> not related-topic, and no shared source -> no edge.
+    assert edges == []
+
+
+def test_connections_related_topic_edge_on_same_category(tmp_path: Path) -> None:
+    base = tmp_path / "iso"
+    _write_run(
+        base,
+        _U1,
+        "runx0011",
+        _state("runx0011", "battery density", "deep-report", "DONE", _PLAN_A, "2026-09-20T10:00:00Z"),
+        ledger={"entries": [{"url": "https://example.org/x"}], "checklist": {}},
+    )
+    _write_run(
+        base,
+        _U1,
+        "runx0022",
+        _state("runx0022", "battery pilots", "deep-report", "DONE", _PLAN_A, "2026-09-21T10:00:00Z"),
+        ledger={"entries": [{"url": "https://example.org/q"}], "checklist": {}},
+    )
+    edges = connections(base, _U1)
+    assert edges == [
+        {
+            "fromReportId": "rep-runx0011",
+            "toReportId": "rep-runx0022",
+            "kind": "related-topic",
+            "label": "Adjacent topic",
+        }
+    ]
+
+
+def test_connections_cross_user_isolation(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    edges = connections(base, _U1)
+    for edge in edges:
+        assert "runcccc1" not in (edge["fromReportId"], edge["toReportId"])
+
+
+# -------------------------------------------------------------------- graph
+
+
+def test_graph_nodes_and_edges(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    payload = graph(base, _U1)
+    node_ids = {node["id"] for node in payload["nodes"]}
+    assert node_ids == {"runaaaa1", "runbbbb1"}  # DONE runs only
+    node = next(n for n in payload["nodes"] if n["id"] == "runaaaa1")
+    assert node["topic"] == "Battery Advances"
+    assert set(node["linkedSources"]) == {"https://example.org/x", "https://example.org/y"}
+    assert node["findings"] == ["Battery Advances"]
+    assert payload["edges"] == [
+        {"fromId": "runaaaa1", "toId": "runbbbb1", "sharedSourceCount": 1}
+    ]
+
+
+def test_graph_fresh_user_is_empty(tmp_path: Path) -> None:
+    assert graph(_tree(tmp_path), "cccc3333") == {"nodes": [], "edges": []}
+
+
+# -------------------------------------------------------------------- tasks
+
+
+def test_tasks_answered_iff_done(tmp_path: Path) -> None:
+    """D-114: a sub-question is done IFF its run reached DONE; the
+    post-sweep CANCELLED run's questions stay open."""
+    base = _tree(tmp_path)
+    items = tasks(base, _U1)
+    by_id = {item["id"]: item for item in items}
+    # DONE runs -> done items with <run_id>#<idx> ids.
+    assert by_id["runaaaa1#0"] == {
+        "id": "runaaaa1#0",
+        "question": "battery energy density gains",
+        "sourceRunId": "runaaaa1",
+        "status": "done",
+    }
+    assert by_id["runbbbb1#0"]["status"] == "done"
+    # CANCELLED + FAILED + in-flight runs -> open items.
+    assert by_id["runcanc1#0"]["status"] == "open"
+    assert by_id["runcanc1#0"]["question"] == "abandoned open question"
+    assert by_id["runfail1#0"]["status"] == "open"
+    assert by_id["runinflg1#0"]["status"] == "open"
+    # user 2's runs absent.
+    assert all("runcccc1" not in item["id"] for item in items)
+
+
+def test_tasks_cross_user_isolation(tmp_path: Path) -> None:
+    items = tasks(_tree(tmp_path), "cccc3333")
+    assert items == []
+
+
+# -------------------------------------------------------------- suggestions
+
+
+def test_suggestions_are_open_items_joined_with_titles(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    payload = suggestions(base, _U1)
+    # Open items from the CANCELLED + FAILED + in-flight runs, most
+    # recent run first, attributed to their source run titles; nothing
+    # synthetic, nothing from DONE runs.
+    assert payload == [
+        {
+            "id": "sug-runinflg1#0",
+            "question": "still running question",
+            "sourceRunId": "runinflg1",
+            "sourceReportTitle": "Deep Report — still running",
+        },
+        {
+            "id": "sug-runfail1#0",
+            "question": "failed run question",
+            "sourceRunId": "runfail1",
+            "sourceReportTitle": "Rapid Answer — it broke",
+        },
+        {
+            "id": "sug-runcanc1#0",
+            "question": "abandoned open question",
+            "sourceRunId": "runcanc1",
+            "sourceReportTitle": "Deep Report — abandoned mid-flight",
+        },
+    ]
+
+
+def test_suggestions_fresh_user_empty_never_synthetic(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    assert suggestions(base, "cccc3333") == []
+
+
+def test_suggestions_exclude_done_runs(tmp_path: Path) -> None:
+    base = _tree(tmp_path)
+    questions = [s["question"] for s in suggestions(base, _U1)]
+    assert "battery energy density gains" not in questions  # DONE run
+
+
+# ------------------------------------------------- defensive scanning extras
+
+
+def test_list_runs_skips_corrupt_state_json(tmp_path: Path) -> None:
+    base = tmp_path
+    run_dir = base / "runs" / _U1 / "corrupt01"
+    run_dir.mkdir(parents=True)
+    (run_dir / "state.json").write_text("{not json", encoding="utf-8")
+    assert list_runs(base, _U1) == []

backend/tests/test_settings_routes_factory.py

@@ -0,0 +1,651 @@
+"""Settings + model-key routes + factory + config-status suite (STEP 2).
+
+Covers T-2.4 (settings/key routes), T-2.5 (per-run model factory
+chain: user → server → keyless), and T-2.6 (config status rework —
+P-1 closure: factory-resolved probe for the CURRENT user, zero runs
+required, no cross-user leak).
+
+Run under the ``auth_enabled=True`` harness (two users prove per-user
+isolation) plus direct factory tests against fake key stores.
+"""
+
+import base64
+import json
+import os
+from pathlib import Path
+
+import httpx
+import pytest
+
+from researchx.adapters.fakes import CORPUS, FakeModelAdapter, FakeSearchAdapter
+from researchx.adapters.model_factory import ModelAdapterFactory
+from researchx.adapters.secrets import EnvFileSecretsProvider
+from researchx.adapters.types import ChatResult
+from researchx.api.app import create_app
+from researchx.auth.guard import CSRF_HEADER
+from researchx.auth.key_store import KEK_NAME, KeyStore
+from researchx.auth.models import UserPublic
+from researchx.auth.settings import UserSettings
+
+_PLAN = json.dumps(
+    {"sub_questions": ["verification passes"], "source_universe": ["web"], "outline": ["intro"]}
+)
+_WRITER = "# Report\n\nClaim [p-1] and claim [p-2].\n"
+
+_ADMIN_EMAIL = "admin@example.org"
+_ADMIN_PASSWORD = "correct-horse-battery"
+_SECOND_EMAIL = "second@example.org"
+_SECOND_PASSWORD = "another-long-password"
+
+_HEADERS = {CSRF_HEADER: "1"}
+
+_KEK = base64.urlsafe_b64encode(os.urandom(32)).decode()
+
+_FAKE_KEY = "sk-user-tier-key-9999"
+
+
+def _env_file(tmp_path: Path, values: dict[str, str]) -> Path:
+    env_file = tmp_path / ".env.secrets"
+    env_file.write_text("".join(f"{k}={v}\n" for k, v in values.items()), encoding="utf-8")
+    return env_file
+
+
+def _user(user_id: str = "abcd2345") -> UserPublic:
+    from datetime import UTC, datetime
+
+    return UserPublic(
+        user_id=user_id,
+        email="user@example.org",
+        display_name="User",
+        role="user",
+        active=True,
+        created_at=datetime.now(UTC),
+    )
+
+
+# ------------------------------------------------------------- harness
+
+
+def _app(
+    tmp_path: Path,
+    *,
+    secrets_values: dict[str, str] | None = None,
+    with_factory: bool = True,
+):
+    """create_app under auth_enabled=True with live per-user stores.
+
+    The model adapter stays the zero-key fake (the fake's chat is what
+    runs execute against); the FACTORY is wired so the tier chain and
+    config-status rework are exercised end to end. The factory's bases
+    point at an unroutable host so config-status probes fail fast and
+    hermetically (no outbound HTTP from the unit tier — the probe
+    contract has its own monkeypatched tests below).
+    """
+    secrets = EnvFileSecretsProvider(
+        paths=[_env_file(tmp_path, secrets_values or {})]
+    )
+    return create_app(
+        storage_dir=tmp_path,
+        model_adapter=FakeModelAdapter(
+            canned=[
+                ChatResult(content=_PLAN, model="fake-planner"),
+                ChatResult(content=_WRITER, model="fake-writer"),
+            ]
+        ),
+        search_adapter=FakeSearchAdapter(CORPUS),
+        auth_enabled=True,
+        data_dir=tmp_path,
+        secrets_provider=secrets,
+        model_factory=ModelAdapterFactory(
+            secrets,
+            KeyStore(secrets, tmp_path),
+            cloud_base_url="http://127.0.0.1:1/v1",
+            local_base_url="http://127.0.0.1:1/v1",
+        )
+        if with_factory
+        else None,
+    )
+
+
+async def _client(tmp_path: Path, **kwargs) -> httpx.AsyncClient:
+    return httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=_app(tmp_path, **kwargs)),
+        base_url="http://testserver",
+    )
+
+
+async def _register_and_login(client: httpx.AsyncClient) -> dict[str, str]:
+    await client.post(
+        "/api/auth/register",
+        json={"email": _ADMIN_EMAIL, "password": _ADMIN_PASSWORD, "display_name": "Admin"},
+        headers=_HEADERS,
+    )
+    login = await client.post(
+        "/api/auth/login", json={"email": _ADMIN_EMAIL, "password": _ADMIN_PASSWORD}, headers=_HEADERS
+    )
+    return login.json()
+
+
+# --------------------------------------------------- settings CRUD routes
+
+
+async def test_settings_get_returns_defaults(tmp_path: Path) -> None:
+    async with await _client(tmp_path) as client:
+        me = await _register_and_login(client)
+        response = await client.get("/api/config/settings")
+        assert response.status_code == 200
+        body = response.json()
+        assert body["planner_model"]
+        assert body["writer_model"]
+        assert body["methodology_defaults"] == {}
+        assert body["appearance"] == "system"
+        # never leaks the user's id/email into the settings payload
+        assert "user_id" not in body
+        assert me["email"] not in json.dumps(body)
+
+
+async def test_settings_put_round_trip(tmp_path: Path) -> None:
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        put = await client.put(
+            "/api/config/settings",
+            json={"planner_model": "qwen-max", "appearance": "dark"},
+            headers=_HEADERS,
+        )
+        assert put.status_code == 200
+        assert put.json()["planner_model"] == "qwen-max"
+        assert put.json()["appearance"] == "dark"
+        # writer_model untouched -> default preserved
+        assert put.json()["writer_model"]
+
+        got = await client.get("/api/config/settings")
+        assert got.json()["planner_model"] == "qwen-max"
+        assert got.json()["appearance"] == "dark"
+
+
+async def test_settings_put_partial_preserves(tmp_path: Path) -> None:
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        await client.put(
+            "/api/config/settings", json={"planner_model": "p-one"}, headers=_HEADERS
+        )
+        put = await client.put(
+            "/api/config/settings", json={"writer_model": "w-two"}, headers=_HEADERS
+        )
+        assert put.json()["planner_model"] == "p-one"
+        assert put.json()["writer_model"] == "w-two"
+
+
+async def test_settings_put_validates_body(tmp_path: Path) -> None:
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        response = await client.put(
+            "/api/config/settings", json={"planner_model": ""}, headers=_HEADERS
+        )
+        assert response.status_code == 422
+
+
+async def test_settings_put_requires_csrf(tmp_path: Path) -> None:
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        response = await client.put("/api/config/settings", json={"appearance": "dark"})
+        assert response.status_code == 403
+
+
+async def test_settings_put_explicit_null_treated_as_absent(tmp_path: Path) -> None:
+    """P2-verify P0 regression: an explicit null field must be treated
+    as absent (partial-merge semantics) — never 200-then-poison the
+    on-disk payload into a corrupt file that 500s every later read."""
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        put = await client.put(
+            "/api/config/settings", json={"planner_model": None}, headers=_HEADERS
+        )
+        assert put.status_code == 200
+        body = put.json()
+        assert body["planner_model"]  # default preserved, not null
+
+        # Every subsequent read + write + run creation stays healthy.
+        got = await client.get("/api/config/settings")
+        assert got.status_code == 200
+        assert got.json()["planner_model"]
+        again = await client.put(
+            "/api/config/settings", json={"planner_model": "qwen-max"}, headers=_HEADERS
+        )
+        assert again.status_code == 200
+        assert again.json()["planner_model"] == "qwen-max"
+        created = await client.post(
+            "/api/runs", json={"question": "q", "methodology": "rapid-answer"}, headers=_HEADERS
+        )
+        assert created.status_code == 201
+
+
+async def test_settings_isolated_per_user(tmp_path: Path) -> None:
+    app = _app(tmp_path)
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as admin:
+        await _register_and_login(admin)
+        await admin.post(
+            "/api/admin/users",
+            json={"email": _SECOND_EMAIL, "password": _SECOND_PASSWORD, "role": "user"},
+            headers=_HEADERS,
+        )
+        await admin.put(
+            "/api/config/settings", json={"appearance": "dark"}, headers=_HEADERS
+        )
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as second:
+        await second.post(
+            "/api/auth/login",
+            json={"email": _SECOND_EMAIL, "password": _SECOND_PASSWORD},
+            headers=_HEADERS,
+        )
+        got = await second.get("/api/config/settings")
+        assert got.json()["appearance"] == "system"  # no bleed
+
+
+# --------------------------------------------------- model-key routes
+
+
+async def test_model_key_put_masked_round_trip(tmp_path: Path) -> None:
+    """PUT the raw key -> 200 with masked status only; the raw key
+    NEVER appears in any response (REQ-73)."""
+    async with await _client(tmp_path, secrets_values={KEK_NAME: _KEK}) as client:
+        me = await _register_and_login(client)
+        put = await client.put(
+            "/api/config/settings/model-key",
+            json={"key": _FAKE_KEY},
+            headers=_HEADERS,
+        )
+        assert put.status_code == 200
+        body = put.json()
+        assert body["configured"] is True
+        assert body["masked"] is not None
+        assert body["masked"].endswith(_FAKE_KEY[-4:])
+        assert _FAKE_KEY not in put.text
+
+        status = await client.get("/api/config/settings/model-key")
+        assert status.json()["configured"] is True
+        assert _FAKE_KEY not in status.text
+        assert me["user_id"] not in status.text
+
+
+async def test_model_key_put_disabled_without_kek_honest_409(tmp_path: Path) -> None:
+    """No KEK -> 409 with the honest {key_store: disabled} payload —
+    never a silent acceptance."""
+    async with await _client(tmp_path) as client:  # no KEK in secrets
+        await _register_and_login(client)
+        put = await client.put(
+            "/api/config/settings/model-key",
+            json={"key": "some-key-value"},
+            headers=_HEADERS,
+        )
+        assert put.status_code == 409
+        detail = put.json()["detail"]
+        assert detail["key_store"] == "disabled"
+        assert "RESEARCHX_KEK" in detail["reason"]
+        # Nothing was written to disk.
+        user_dir = tmp_path / "keys"
+        assert not user_dir.exists() or not any(user_dir.iterdir())
+
+
+async def test_model_key_get_status_disabled_says_so(tmp_path: Path) -> None:
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        status = await client.get("/api/config/settings/model-key")
+        assert status.status_code == 200
+        body = status.json()
+        assert body["disabled"] is True
+        assert "RESEARCHX_KEK" in body["reason"]
+        assert body["configured"] is False
+
+
+async def test_model_key_put_requires_csrf(tmp_path: Path) -> None:
+    async with await _client(tmp_path, secrets_values={KEK_NAME: _KEK}) as client:
+        await _register_and_login(client)
+        response = await client.put(
+            "/api/config/settings/model-key", json={"key": "no-header-key"}
+        )
+        assert response.status_code == 403
+
+
+async def test_model_key_never_in_config_or_settings_responses(tmp_path: Path) -> None:
+    """The raw key must not surface in ANY authenticated response."""
+    async with await _client(tmp_path, secrets_values={KEK_NAME: _KEK}) as client:
+        await _register_and_login(client)
+        await client.put(
+            "/api/config/settings/model-key", json={"key": _FAKE_KEY}, headers=_HEADERS
+        )
+        for path in [
+            "/api/config",
+            "/api/config/settings",
+            "/api/config/settings/model-key",
+            "/api/auth/me",
+            "/api/methodologies",
+        ]:
+            response = await client.get(path)
+            assert _FAKE_KEY not in response.text, f"raw key leaked via {path}"
+
+
+# --------------------------------------------------------- factory chain
+
+
+class _FakeKeyStore:
+    """Test double for KeyStore: enabled with a known key or disabled."""
+
+    def __init__(self, key: str | None = None, enabled: bool = True) -> None:
+        self._key = key
+        self._enabled_flag = enabled
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled_flag
+
+    async def get_key(self, user_id: str) -> str | None:
+        del user_id
+        return self._key
+
+    async def masked_status(self, user_id: str) -> dict[str, object]:
+        del user_id
+        return {
+            "configured": self._key is not None,
+            "masked": f"…{self._key[-4:]}" if self._key else None,
+            "disabled": not self._enabled_flag,
+        }
+
+
+def _factory(tmp_path: Path, secrets_values: dict[str, str], key_store: object) -> ModelAdapterFactory:
+    secrets = EnvFileSecretsProvider(paths=[_env_file(tmp_path, secrets_values)])
+    return ModelAdapterFactory(
+        secrets,
+        key_store,  # type: ignore[arg-type]
+        cloud_base_url="http://127.0.0.1:1/v1",  # unroutable: hermetic unit tier
+        local_base_url="http://127.0.0.1:1/v1",
+    )
+
+
+async def test_factory_user_tier_when_key_present(tmp_path: Path) -> None:
+    factory = _factory(
+        tmp_path,
+        {"OLLAMA_API_KEY": "server-key-value"},
+        _FakeKeyStore(key=_FAKE_KEY),
+    )
+    adapter, tier = await factory.resolve(_user(), UserSettings())
+    assert tier == "user"
+    assert adapter.roles().planner == UserSettings().planner_model
+
+
+async def test_factory_server_tier_when_no_user_key(tmp_path: Path) -> None:
+    factory = _factory(
+        tmp_path,
+        {"OLLAMA_API_KEY": "server-key-value"},
+        _FakeKeyStore(key=None),
+    )
+    _adapter, tier = await factory.resolve(_user(), UserSettings())
+    assert tier == "server"
+
+
+async def test_factory_keyless_when_neither(tmp_path: Path) -> None:
+    factory = _factory(tmp_path, {}, _FakeKeyStore(key=None))
+    _adapter, tier = await factory.resolve(_user(), UserSettings())
+    assert tier == "keyless"
+
+
+async def test_factory_keyless_when_store_disabled(tmp_path: Path) -> None:
+    factory = _factory(
+        tmp_path,
+        {"OLLAMA_API_KEY": "server-key-value"},
+        _FakeKeyStore(key=None, enabled=False),
+    )
+    _adapter, tier = await factory.resolve(_user(), UserSettings())
+    assert tier == "server"  # chain proceeds to server when key store disabled
+
+
+async def test_factory_respects_user_settings_models(tmp_path: Path) -> None:
+    factory = _factory(tmp_path, {}, _FakeKeyStore(key=None))
+    settings = UserSettings(planner_model="my-planner", writer_model="my-writer")
+    adapter, tier = await factory.resolve(_user(), settings)
+    assert tier == "keyless"
+    assert adapter.roles().planner == "my-planner"
+    assert adapter.roles().writer == "my-writer"
+
+
+async def test_factory_never_caches_adapters(tmp_path: Path) -> None:
+    factory = _factory(tmp_path, {}, _FakeKeyStore(key=None))
+    first, _ = await factory.resolve(_user(), UserSettings())
+    second, _ = await factory.resolve(_user(), UserSettings())
+    assert first is not second  # one instance per run (P-2 closure)
+
+
+async def test_factory_user_key_precedence_over_server_secrets(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The resolved user key must be the Authorization the adapter sends
+    — not the server env-file key."""
+    seen_headers: dict[str, str] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen_headers.update(dict(request.headers))
+        return httpx.Response(
+            200, json={"choices": [{"message": {"content": '{"ok": true}'}}]}
+        )
+
+    transport = httpx.MockTransport(handler)
+    original = httpx.AsyncClient
+    monkeypatch.setattr(
+        httpx, "AsyncClient", lambda **kwargs: original(transport=transport, **kwargs)
+    )
+
+    factory = _factory(
+        tmp_path,
+        {"OLLAMA_API_KEY": "server-key-value"},
+        _FakeKeyStore(key=_FAKE_KEY),
+    )
+    adapter, tier = await factory.resolve(_user(), UserSettings())
+    assert tier == "user"
+    await adapter.chat(
+        [__import__("researchx.adapters.types", fromlist=["ModelMessage"]).ModelMessage(
+            role="user", content="hi"
+        )],
+        model="w",
+    )
+    assert seen_headers["authorization"] == f"Bearer {_FAKE_KEY}"
+
+
+# ------------------------------------------------- config status rework
+
+
+async def test_config_status_tier_per_user_no_cross_leak(tmp_path: Path) -> None:
+    """Config status shows the CURRENT user's tier: a keyed user shows
+    'user', a keyless second user shows 'server' — zero runs needed
+    (P-1 closure), zero cross-user bleed."""
+    app = _app(tmp_path, secrets_values={KEK_NAME: _KEK, "OLLAMA_API_KEY": "server-key-value"})
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as admin:
+        await _register_and_login(admin)
+        await admin.put(
+            "/api/config/settings/model-key",
+            json={"key": _FAKE_KEY},
+            headers=_HEADERS,
+        )
+        config = await admin.get("/api/config")
+        assert config.status_code == 200
+        body = config.json()
+        assert body["resolved_tier"] == "user"
+        assert body["key_store"] == "enabled"
+        assert body["key_status"]["configured"] is True
+        assert body["key_status"]["masked"].endswith(_FAKE_KEY[-4:])
+        assert body["cost_counters"] == {"runs_created": 0, "runs_completed": 0}
+
+        await admin.post(
+            "/api/admin/users",
+            json={"email": _SECOND_EMAIL, "password": _SECOND_PASSWORD, "role": "user"},
+            headers=_HEADERS,
+        )
+
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as second:
+        await second.post(
+            "/api/auth/login",
+            json={"email": _SECOND_EMAIL, "password": _SECOND_PASSWORD},
+            headers=_HEADERS,
+        )
+        config = await second.get("/api/config")
+        body = config.json()
+        assert body["resolved_tier"] == "server"  # no user key of their own
+        assert body["key_store"] == "enabled"  # the STORE is enabled; the user has no key
+        assert body["key_status"]["configured"] is False
+        assert _FAKE_KEY not in config.text
+        assert _FAKE_KEY[-4:] not in config.text
+        # Counters owner-keyed: the second user sees zero, not the admin's runs.
+        assert body["cost_counters"] == {"runs_created": 0, "runs_completed": 0}
+
+
+async def test_config_status_keyless_when_no_keys(tmp_path: Path) -> None:
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        config = await client.get("/api/config")
+        body = config.json()
+        assert body["resolved_tier"] == "keyless"
+        assert body["key_store"] == "disabled"
+        assert body["key_status"]["disabled"] is True
+        assert body["model_adapter"] == "OllamaModelAdapter"  # factory-constructed
+
+
+async def test_config_status_works_with_zero_runs(tmp_path: Path) -> None:
+    """P-1: correct config status with zero runs in the registry."""
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        response = await client.get("/api/config")
+        assert response.status_code == 200
+        assert response.json()["resolved_tier"] in ("user", "server", "keyless")
+        assert response.json()["cost_counters"]["runs_created"] == 0
+
+
+async def test_config_status_probe_cached_and_error_safe(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Probe semantics pinned hermetically: a successful probe is
+    cached in-process (second call does not re-probe), and an
+    AdapterError probe yields probe: None (never a 500)."""
+    import researchx.api.app as app_module
+
+    calls: list[int] = []
+    probe_payload = {
+        "endpoint": "http://127.0.0.1:1/v1",
+        "models": ["m"],
+        "context_window": 8192,
+        "embedding_batch": 8,
+        "structured_outputs_supported": True,
+    }
+    from researchx.adapters.probe import CapabilityProbe
+
+    fake_probe = CapabilityProbe(
+        endpoint="http://127.0.0.1:1/v1",
+        models=["m"],
+        context_window=8192,
+        embedding_batch=8,
+        structured_outputs_supported=True,
+    )
+
+    async def _fake_probe(adapter):
+        calls.append(1)
+        return fake_probe
+
+    async def _failing_probe(adapter):
+        from researchx.adapters.types import AdapterError
+
+        raise AdapterError("unreachable")
+
+    monkeypatch.setattr(app_module, "probe_model_adapter", _fake_probe)
+
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        first = await client.get("/api/config")
+        assert first.status_code == 200
+        assert first.json()["probe"]["endpoint"] == probe_payload["endpoint"]
+        assert len(calls) == 1
+        second = await client.get("/api/config")
+        assert len(calls) == 1  # served from the (user, tier, fingerprint) cache
+        assert second.json()["probe"]["endpoint"] == probe_payload["endpoint"]
+
+    # Fresh app: a failing probe yields None, cached — never a 500, and
+    # the route stays healthy on repeat calls.
+    monkeypatch.setattr(app_module, "probe_model_adapter", _failing_probe)
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        first = await client.get("/api/config")
+        assert first.status_code == 200
+        assert first.json()["probe"] is None
+        second = await client.get("/api/config")
+        assert second.status_code == 200
+        assert second.json()["probe"] is None
+
+
+async def test_config_status_uses_factory_adapter_not_fixed_one(tmp_path: Path) -> None:
+    """The rework: model_adapter names the FACTORY-constructed adapter
+    (OllamaModelAdapter), not the fixed injected fake."""
+    async with await _client(tmp_path) as client:
+        await _register_and_login(client)
+        config = await client.get("/api/config")
+        assert config.json()["model_adapter"] == "OllamaModelAdapter"
+
+
+async def test_config_status_without_factory_names_fixed_adapter(tmp_path: Path) -> None:
+    """Back-compat: with no factory wired (pure test harness), the
+    config status still answers with the injected adapter's name."""
+    async with await _client(tmp_path, with_factory=False) as client:
+        await _register_and_login(client)
+        config = await client.get("/api/config")
+        body = config.json()
+        assert body["model_adapter"] == "FakeModelAdapter"
+        assert body["resolved_tier"] == "keyless"
+
+
+# ----------------------------------------------- create_run tier stamping
+
+
+async def test_create_run_stamps_credential_tier(tmp_path: Path) -> None:
+    """create_run resolves the factory and stamps state.credential_tier
+    (REQ-74); the engine contracts are otherwise unchanged."""
+    async with await _client(tmp_path) as client:
+        me = await _register_and_login(client)
+        created = await client.post(
+            "/api/runs", json={"question": "q", "methodology": "rapid-answer"}, headers=_HEADERS
+        )
+        assert created.status_code == 201
+        run_id = created.json()["id"]
+
+        state_path = tmp_path / "runs" / me["user_id"] / run_id / "state.json"
+        import asyncio
+
+        for _ in range(200):
+            if state_path.exists():
+                break
+            await asyncio.sleep(0.01)
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        assert state["credential_tier"] == "keyless"
+        assert state["owner_id"] == me["user_id"]
+
+
+async def test_create_run_user_tier_uses_user_key(tmp_path: Path) -> None:
+    """A keyed user's run executes with THEIR key through the factory
+    chain (fake model still serves the run — zero-key CI)."""
+    async with await _client(tmp_path, secrets_values={KEK_NAME: _KEK}) as client:
+        me = await _register_and_login(client)
+        await client.put(
+            "/api/config/settings/model-key", json={"key": _FAKE_KEY}, headers=_HEADERS
+        )
+        created = await client.post(
+            "/api/runs", json={"question": "q", "methodology": "rapid-answer"}, headers=_HEADERS
+        )
+        assert created.status_code == 201
+        run_id = created.json()["id"]
+
+        import asyncio
+
+        state_path = tmp_path / "runs" / me["user_id"] / run_id / "state.json"
+        for _ in range(200):
+            if state_path.exists():
+                break
+            await asyncio.sleep(0.01)
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        assert state["credential_tier"] == "user"

backend/uv.lock

@@ -260,6 +260,56 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
 ]
 
+[[package]]
+name = "cryptography"
+version = "50.0.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bb/ad/5d6702db60b1e40b41ef513b6967ff5848f307d50f8449baf1634f5908f1/cryptography-50.0.1.tar.gz", hash = "sha256:5dd9bda1c12b4162f6ff568eeb5e0ff956c28d14406e875cfe8a63a2d414ff20", size = 880381, upload-time = "2026-08-25T19:45:45.499Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ba/19/797e2aaac9df6a66f1550f49979dc1b1e39ecd2077501c30efa81e8d5d67/cryptography-50.0.1-cp311-abi3-macosx_11_0_arm64.whl", hash = "sha256:b8f852c65863251b9e3a1b8c150ce21e59b522dbb6a7d4bc80e680d38388e986", size = 4010153, upload-time = "2026-08-25T19:44:03.155Z" },
+    { url = "https://files.pythonhosted.org/packages/90/34/9ce9a62ed9dc82ca9fd6a34445b6904af56e5f38b3eae2ed32e49c36053d/cryptography-50.0.1-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:53e279950892dc102c6b4e52af03ae5ea92fac572a1ddab78ca73a997f62b69f", size = 4723133, upload-time = "2026-08-25T19:44:05.461Z" },
+    { url = "https://files.pythonhosted.org/packages/57/26/e6d4fc8512a51a5f9ee7bfdbfb853bce1197087df40c9ad993ad370b846f/cryptography-50.0.1-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:ff838d62ec1bfce4f9ba7fa16f4a7b554cd8d0c299e6be37502161a660c84eef", size = 4712478, upload-time = "2026-08-25T19:44:07.375Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/de/d3cdc2815697aae84126cbd6a030ca7b6b452e28a88b501b836bd3aa7a86/cryptography-50.0.1-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:e74591e283fe6eb956416c929eb58262a719fe0311fd9054c62c3350ed8760d8", size = 4730726, upload-time = "2026-08-25T19:44:09.294Z" },
+    { url = "https://files.pythonhosted.org/packages/55/32/38c0d344b98c06d34b5df8946565a9c0d6dbf32c8e0730a7f05f0a3c6cab/cryptography-50.0.1-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:5fe002589592ed749ce77fe0695fcbd3500dd61d7d6db5858a7544c612fa8e45", size = 5353524, upload-time = "2026-08-25T19:44:11.96Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/1b/82f0f0d8858d4432be1af790477edf62aef90324041aa07c57e57bef1af7/cryptography-50.0.1-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:51593d180cf6d179bde5c5d065bed81386b1f381656ae7d042b7ffc87a9895ad", size = 4746720, upload-time = "2026-08-25T19:44:14.051Z" },
+    { url = "https://files.pythonhosted.org/packages/29/ba/042ca458b8c64348c768284b5d23e69b92ed53d057ab779fee628564676d/cryptography-50.0.1-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:359e62deae718bce96170e223fdcb6357e4fbd3bb7a3a75f4430763532560e49", size = 4361866, upload-time = "2026-08-25T19:44:16.167Z" },
+    { url = "https://files.pythonhosted.org/packages/39/3b/e96c1ef71edef71057c7e3c3d982ce8fda554e0c52d0cc19c18845cde3eb/cryptography-50.0.1-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:e2ca8fd1b6b4b82a1c4cb02841d0837e3c12336c2e24b520ab8ab3b969733d8f", size = 4730028, upload-time = "2026-08-25T19:44:18.085Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/38/45abd72ef63f2e7d0754a6cacf97bd8b69512ace7f6130d24c39ece65da2/cryptography-50.0.1-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:76de83fbd91ac49c0feaaa983d0748fd7a53176afac5fb3bf7478d244f0eb527", size = 5308405, upload-time = "2026-08-25T19:44:20.197Z" },
+    { url = "https://files.pythonhosted.org/packages/85/66/6ccca4722987ddedaa7fc9c3f4708af7431f5535666c174350830888c6b7/cryptography-50.0.1-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:51afcfceb15597cf2635068e4ac9a56b2abde622edde17f37d85fd7b5306497a", size = 4746230, upload-time = "2026-08-25T19:44:22.376Z" },
+    { url = "https://files.pythonhosted.org/packages/13/0e/b1f92e013228111413f2e6743948b80bc24dfd3c1b87ba98ceea16f5df89/cryptography-50.0.1-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:be224a65493ec5b74a158ff22a5522ce4a5ca1e543c647a3a4730d4a09e5f959", size = 4862596, upload-time = "2026-08-25T19:44:24.472Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/22/c3654cccc856e9d682817b04ac3ee79731cb09ca6f95996a95c904de2883/cryptography-50.0.1-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:9ebcdd5519be9b652a46f507817a74591774fc3d6923ac364e4dfa64e36b291b", size = 5014082, upload-time = "2026-08-25T19:44:26.709Z" },
+    { url = "https://files.pythonhosted.org/packages/42/8b/cb12b1b60c91b074ca6bf0fdd59aa8f10d8bc5f73af8faece86ef0421b37/cryptography-50.0.1-cp311-abi3-win_amd64.whl", hash = "sha256:aed8db4f6d71c51efb89530e12d9464e7bf2923d46c3205dc794a2a93f8c0648", size = 3842826, upload-time = "2026-08-25T19:44:28.784Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/f0/424cb557d99aa86ac55da5e2add02e2882e44047b6264f93ade1b975a993/cryptography-50.0.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:30a125032e5642a21ff816e021152bd4e7e94f03eff3f4b7fca41cd22bc3110f", size = 3973525, upload-time = "2026-08-25T19:44:30.7Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/72/3a2711d967977ab5fc80b782837c7e8d1ac7445e764c20c381a265c57ef3/cryptography-50.0.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:a0b1a59e3a089064a0ec309e9428c8e3ae4e161419d20ac33600767e83fc658a", size = 4708817, upload-time = "2026-08-25T19:44:32.773Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/f2/bb1f56e10815b789df0b409a69fa4992ff3d3fef9c72747f4a6b26fed38e/cryptography-50.0.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:8921d58f426793c5f1b47f0b59575780de9a095214958d0eb37d909593db8367", size = 4697300, upload-time = "2026-08-25T19:44:35.144Z" },
+    { url = "https://files.pythonhosted.org/packages/08/bd/ed5396be499ffcf8807a585bfe38b71a1fbdd1c342b4f9b6d0ef5162a946/cryptography-50.0.1-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:a8f40ea47330e71b594a7e246898f93177c259490c63183dbaf9e571d71ed9a5", size = 4716039, upload-time = "2026-08-25T19:44:37.192Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/6e/1cf405c5c8e8df7545378048e954792f00b7f2367af8863ce8b8f3e10607/cryptography-50.0.1-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:a255449073358275b64b67d3f595f268bbef70e72b6edb65e0c70c735bf739c9", size = 5332388, upload-time = "2026-08-25T19:44:39.16Z" },
+    { url = "https://files.pythonhosted.org/packages/47/92/b4317e8c32c4f47b062f5398bd79106b220a124546f42be83bf32b761e2a/cryptography-50.0.1-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:8df2de9102026855887e4587084f6eabd80ed0f345b8ad8a7ac27ab9bf4723e0", size = 4730293, upload-time = "2026-08-25T19:44:41.298Z" },
+    { url = "https://files.pythonhosted.org/packages/39/0d/a1e7633e2c744d0f2983320a27e924ef2264c79c56e1a58d5fb0a1cfd413/cryptography-50.0.1-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:ac02b07824d4d1001bd4367599f839c19cb171924c796e52c23508ac14c2c0cc", size = 4346031, upload-time = "2026-08-25T19:44:43.245Z" },
+    { url = "https://files.pythonhosted.org/packages/88/dd/b215616f9bab3fc18510c78a4e5c9f362d77838503c363dc747c7d4f5c6f/cryptography-50.0.1-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:cbf74a81765ee67413503ca6e26dcc4f6f5a519822436cc0a1b97aab6c1b8a17", size = 4715344, upload-time = "2026-08-25T19:44:45.291Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/1b/ec3ebd31741d0e963612c4fe43caa39341b9b1e031e469820e42e4c83918/cryptography-50.0.1-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:16c5ecd954b3330ebfb6605eca4fd952da8bef376551d5cc264534e3770a9ee6", size = 5287201, upload-time = "2026-08-25T19:44:47.297Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/01/0127d11a762b31a9ee0221894f540318761783f3fdc4bc5d057698caebd5/cryptography-50.0.1-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:79bf008d1f9af6071c797ad133e39915dfee7614f18f18f4db9072eb715064a3", size = 4730023, upload-time = "2026-08-25T19:44:49.435Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/b9/e7425ebfb599241a0c1d7000f1b466c3062da66c19d9525031315dff7213/cryptography-50.0.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:330fbb252391c596f1ae42c5754449dc924e6ad012dca8efe0d703f9f2d12ec6", size = 4847362, upload-time = "2026-08-25T19:44:51.94Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/fd/60d0ddf4defa12e482c9d5e0f554384d6e8ab25341fd15f060028fd92e6a/cryptography-50.0.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:42be3bb70596b3abe4ac097b75be223e8b3ab614a0e5de068e3dcc54d71d6149", size = 4999247, upload-time = "2026-08-25T19:44:53.876Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/56/bc4f2b209e766c93372cfcd59b781a0b2b59700f62a969580415b699c2b2/cryptography-50.0.1-cp314-cp314t-win_amd64.whl", hash = "sha256:f74455bb086a85d5e81246412602aaa97ed095e504cd40dd261ef50be42205bf", size = 3825806, upload-time = "2026-08-25T19:44:56.209Z" },
+    { url = "https://files.pythonhosted.org/packages/84/a9/ee16a903f13755e914d1eecc482fe64d1f10761c3960e5d8fa6837377aff/cryptography-50.0.1-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:ca83d00d9e69cd5eb63f2e69c3a5a59e0cecae5ae14c6ae0b35830fe3b37bad0", size = 4035307, upload-time = "2026-08-25T19:44:58.305Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/a5/9ec7e81e8526c0d7a387d73386b2daed3f39e10d81a85930bd1b6bfba65c/cryptography-50.0.1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:05ba322c4da95b262a212c345af888ef2c37c88c0509756ea00a0e6d68850f23", size = 4751900, upload-time = "2026-08-25T19:45:00.401Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/3c/0e77bd5ffcf078e9dd27d3074aad6c030d9b10d0bf69329d573c927a188c/cryptography-50.0.1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:e22dfed744bd4002e909464cb23d2f0b05c6f3113a79ef2e9864a53db737c733", size = 4738357, upload-time = "2026-08-25T19:45:02.786Z" },
+    { url = "https://files.pythonhosted.org/packages/27/3a/3c5f80daa4dcd47323c7af8a2fcb90de27a33564d4fcac69846c0972691a/cryptography-50.0.1-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:4c4188f7c0cf655be5c06342b817ed0f9595b69ffa2b12026e5353eed29dea88", size = 4758474, upload-time = "2026-08-25T19:45:04.889Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/2b/214cf0cf93db9628c3c20c896b229f327f6fb1b20e4b3743d8ad3f00af8b/cryptography-50.0.1-cp39-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:2ebbfb0f1fed745e91796e3e1080a1440423fdae8ece1b995a1d80883a409054", size = 5375862, upload-time = "2026-08-25T19:45:07.163Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/51/3f9701867a46b6c1740c9b52fc4d3bed6cbdcfedcc9b6e64305c07f39cff/cryptography-50.0.1-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:407fe2b6db00939c05c0e945e9914238f2f0a430974839429dafc82b1ee6bee5", size = 4772942, upload-time = "2026-08-25T19:45:09.396Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/5c/13ea642e08e2544d0f5396122055f4820cfacb3203562197b5967125ea97/cryptography-50.0.1-cp39-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:2b34d76a652ea2b6faf777c35df230c5637842cd904e04f16230c3f9f03e4361", size = 4383347, upload-time = "2026-08-25T19:45:11.659Z" },
+    { url = "https://files.pythonhosted.org/packages/84/d5/7d1fe1cb93f91c428093ff234e128c89ba8ea61a6f26aab406081f9b996e/cryptography-50.0.1-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:01f41478cf33fc605a6a089cd56d28b45c6c0b45a1928b61797f2621a04bac71", size = 4758050, upload-time = "2026-08-25T19:45:13.745Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/04/557fc5ead96a829e0bc812a3b9dc4a52a2f27e4f7f5950da7ff27653a805/cryptography-50.0.1-cp39-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:fc3ed7ebd2a8c96f5b166de0ab9b624996bef3b07bbeb19364dfb78222c22c80", size = 5332955, upload-time = "2026-08-25T19:45:16.193Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/eb/5d7124083e8d8cda8f5b348f544b71ad6f707ad63193758ef4d8e569da02/cryptography-50.0.1-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:9dde0a357190eb3b1da1bb9ab750e9c85cba82ca5977aa0836cbb94e92611239", size = 4772694, upload-time = "2026-08-25T19:45:18.315Z" },
+    { url = "https://files.pythonhosted.org/packages/63/8e/f1f955e0921dd2b6d22eae7e8d24a4c4b638d10735ffbf6a71f99eb0fcb8/cryptography-50.0.1-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:fd3718b960d0b5dd213cdf03f3bcb7000e69dda0de8b956061947ff6bcff5558", size = 4888413, upload-time = "2026-08-25T19:45:20.4Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/ab/89e2b798d2c3925f82e2bb72d5979f3d2f6da2dd22ef4a8cd8b70d920039/cryptography-50.0.1-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:2a93d05e34d5f67fba6f891fe85d929999baa7195e853923ea6d7576c9e68c5e", size = 5044355, upload-time = "2026-08-25T19:45:22.353Z" },
+    { url = "https://files.pythonhosted.org/packages/99/89/87ef49ffe383ef4e147d27b7bf2088fb0b54ea409dd87b5a89442e5828a5/cryptography-50.0.1-cp39-abi3-win_amd64.whl", hash = "sha256:55d16b1ef3ee0958d893a977b19777887e546c9954ea81b200c3301a864013f2", size = 3875429, upload-time = "2026-08-25T19:45:24.418Z" },
+]
+
 [[package]]
 name = "fastapi"
 version = "0.115.14"
@@ -663,6 +713,7 @@ version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "argon2-cffi" },
+    { name = "cryptography" },
     { name = "fastapi" },
     { name = "httpx" },
     { name = "pydantic" },
@@ -682,6 +733,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "argon2-cffi", specifier = ">=23.1,<26" },
+    { name = "cryptography", specifier = ">=43" },
     { name = "fastapi", specifier = ">=0.115,<0.116" },
     { name = "httpx", specifier = ">=0.27,<1" },
     { name = "pydantic", specifier = ">=2.8,<3" },

frontend/openapi.json

@@ -264,6 +264,7 @@
     "/api/config": {
       "get": {
         "summary": "Config Status",
+        "description": "Current user's resolved credential tier + status (T-2.6).\n\nP-1 closure: the probe is resolved via the factory for the\nCURRENT user \u2014 no run creation, no reads of the private\nregistry dict, correct with zero runs, no cross-user leak.\nA corrupt/tampered stored envelope degrades the tier honestly\n(server/keyless) and surfaces the error in key_status.reason \u2014\nnever a 500, never a silent drop.",
         "operationId": "config_status_api_config_get",
         "responses": {
           "200": {
@@ -279,6 +280,117 @@
         }
       }
     },
+    "/api/config/settings": {
+      "get": {
+        "summary": "Get Settings",
+        "operationId": "get_settings_api_config_settings_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UserSettings"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "summary": "Put Settings",
+        "description": "Persist a partial settings update (REQ-72); returns the\nupdated settings. An explicit null field is treated as absent\n(partial-merge semantics \u2014 the store refuses null-valued\nfields, so a null can never poison the on-disk payload).",
+        "operationId": "put_settings_api_config_settings_put",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SettingsBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UserSettings"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/config/settings/model-key": {
+      "get": {
+        "summary": "Get Model Key Status",
+        "description": "Masked-only key status (never the raw key).",
+        "operationId": "get_model_key_status_api_config_settings_model_key_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/KeyStatus"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "summary": "Put Model Key",
+        "description": "Accept the user's raw model key, encrypt it at rest, return\nONLY the masked status (REQ-73 \u2014 the raw key never appears in\nany response, log, or trace). Without a KEK: honest 409.",
+        "operationId": "put_model_key_api_config_settings_model_key_put",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ModelKeyBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/KeyStatus"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/methodologies": {
       "get": {
         "summary": "Methodologies",
@@ -302,6 +414,27 @@
       }
     },
     "/api/runs": {
+      "get": {
+        "summary": "List Runs Route",
+        "description": "All of this owner's runs from disk state files, most recent\nfirst \u2014 the registry-independent run list (post-sweep\nCANCELLED runs surface cancelled, NOT open).",
+        "operationId": "list_runs_route_api_runs_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "items": {
+                    "$ref": "#/components/schemas/RunSummary"
+                  },
+                  "type": "array",
+                  "title": "Response List Runs Route Api Runs Get"
+                }
+              }
+            }
+          }
+        }
+      },
       "post": {
         "summary": "Create Run",
         "operationId": "create_run_api_runs_post",
@@ -591,6 +724,7 @@
     "/api/runs/{run_id}/report": {
       "get": {
         "summary": "Run Report",
+        "description": "Disk-read, registry-independent (P-8 full closure, T-3.3):\nthe run directory under THIS owner is the existence check \u2014 no\nRunRegistry involvement, correct after a restart with zero\nin-memory actors. Pre-artifact DONE runs (and any run whose\nreport.json was not yet written) fall back to markdown-only\nwith null report/evidence \u2014 never a 500 (D-106: old artifacts\ndisposable).",
         "operationId": "run_report_api_runs__run_id__report_get",
         "parameters": [
           {
@@ -632,6 +766,7 @@
     "/api/runs/{run_id}/ledger": {
       "get": {
         "summary": "Run Ledger",
+        "description": "Disk-read, registry-independent (T-3.3): same owner-dir\nexistence check as the report route.",
         "operationId": "run_ledger_api_runs__run_id__ledger_get",
         "parameters": [
           {
@@ -669,6 +804,286 @@
           }
         }
       }
+    },
+    "/api/library": {
+      "get": {
+        "summary": "Library Route",
+        "operationId": "library_route_api_library_get",
+        "parameters": [
+          {
+            "name": "sort",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "default": "recent",
+              "title": "Sort"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "title": "Response Library Route Api Library Get"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/library/connections": {
+      "get": {
+        "summary": "Connections Route",
+        "operationId": "connections_route_api_library_connections_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "items": {
+                    "additionalProperties": true,
+                    "type": "object"
+                  },
+                  "type": "array",
+                  "title": "Response Connections Route Api Library Connections Get"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/graph": {
+      "get": {
+        "summary": "Graph Route",
+        "operationId": "graph_route_api_graph_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "type": "object",
+                  "title": "Response Graph Route Api Graph Get"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/tasks": {
+      "get": {
+        "summary": "Tasks Route",
+        "operationId": "tasks_route_api_tasks_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "items": {
+                    "additionalProperties": {
+                      "type": "string"
+                    },
+                    "type": "object"
+                  },
+                  "type": "array",
+                  "title": "Response Tasks Route Api Tasks Get"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/suggestions": {
+      "get": {
+        "summary": "Suggestions Route",
+        "operationId": "suggestions_route_api_suggestions_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "items": {
+                    "additionalProperties": {
+                      "type": "string"
+                    },
+                    "type": "object"
+                  },
+                  "type": "array",
+                  "title": "Response Suggestions Route Api Suggestions Get"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/refine/questions": {
+      "post": {
+        "summary": "Refine Questions",
+        "operationId": "refine_questions_api_refine_questions_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RefineDraftBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": true,
+                  "type": "object",
+                  "title": "Response Refine Questions Api Refine Questions Post"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/refine/compose": {
+      "post": {
+        "summary": "Refine Compose",
+        "operationId": "refine_compose_api_refine_compose_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RefineComposeBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "type": "object",
+                  "title": "Response Refine Compose Api Refine Compose Post"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/profile": {
+      "get": {
+        "summary": "Get Profile",
+        "operationId": "get_profile_api_profile_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "type": "object",
+                  "title": "Response Get Profile Api Profile Get"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "summary": "Put Profile",
+        "description": "Update display name and/or email (no deletion, REQ-81).\nThe email stays unique (casefolded) across other users.",
+        "operationId": "put_profile_api_profile_put",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProfileBody"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "type": "object",
+                  "title": "Response Put Profile Api Profile Put"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -726,6 +1141,17 @@
       },
       "ConfigStatus": {
         "properties": {
+          "resolved_tier": {
+            "type": "string",
+            "title": "Resolved Tier"
+          },
+          "key_store": {
+            "type": "string",
+            "title": "Key Store"
+          },
+          "key_status": {
+            "$ref": "#/components/schemas/KeyStatus"
+          },
           "model_adapter": {
             "type": "string",
             "title": "Model Adapter"
@@ -760,6 +1186,9 @@
         },
         "type": "object",
         "required": [
+          "resolved_tier",
+          "key_store",
+          "key_status",
           "model_adapter",
           "search_adapter",
           "storage_dir",
@@ -811,6 +1240,47 @@
         "type": "object",
         "title": "HTTPValidationError"
       },
+      "KeyStatus": {
+        "properties": {
+          "configured": {
+            "type": "boolean",
+            "title": "Configured"
+          },
+          "masked": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Masked"
+          },
+          "disabled": {
+            "type": "boolean",
+            "title": "Disabled",
+            "default": false
+          },
+          "reason": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Reason"
+          }
+        },
+        "type": "object",
+        "required": [
+          "configured"
+        ],
+        "title": "KeyStatus",
+        "description": "Masked-only key status \u2014 the raw key NEVER appears (REQ-73)."
+      },
       "LoginBody": {
         "properties": {
           "email": {
@@ -881,6 +1351,92 @@
         ],
         "title": "MethodologyCard"
       },
+      "ModelKeyBody": {
+        "properties": {
+          "key": {
+            "type": "string",
+            "maxLength": 512,
+            "minLength": 1,
+            "title": "Key"
+          }
+        },
+        "type": "object",
+        "required": [
+          "key"
+        ],
+        "title": "ModelKeyBody",
+        "description": "PUT /api/config/settings/model-key body \u2014 the raw key, accepted,\nnever echoed (REQ-73)."
+      },
+      "ProfileBody": {
+        "properties": {
+          "display_name": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 120,
+                "minLength": 1
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Display Name"
+          },
+          "email": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 254,
+                "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Email"
+          }
+        },
+        "type": "object",
+        "title": "ProfileBody"
+      },
+      "RefineComposeBody": {
+        "properties": {
+          "draft": {
+            "type": "string",
+            "maxLength": 2000,
+            "minLength": 1,
+            "title": "Draft"
+          },
+          "answers": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array",
+            "maxItems": 10,
+            "title": "Answers"
+          }
+        },
+        "type": "object",
+        "required": [
+          "draft"
+        ],
+        "title": "RefineComposeBody"
+      },
+      "RefineDraftBody": {
+        "properties": {
+          "draft": {
+            "type": "string",
+            "maxLength": 2000,
+            "minLength": 1,
+            "title": "Draft"
+          }
+        },
+        "type": "object",
+        "required": [
+          "draft"
+        ],
+        "title": "RefineDraftBody"
+      },
       "RegisterBody": {
         "properties": {
           "email": {
@@ -953,6 +1509,63 @@
         ],
         "title": "RunSummary"
       },
+      "SettingsBody": {
+        "properties": {
+          "planner_model": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 200,
+                "minLength": 1
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Planner Model"
+          },
+          "writer_model": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 200,
+                "minLength": 1
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Writer Model"
+          },
+          "methodology_defaults": {
+            "anyOf": [
+              {
+                "additionalProperties": true,
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Methodology Defaults"
+          },
+          "appearance": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 40
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Appearance"
+          }
+        },
+        "type": "object",
+        "title": "SettingsBody",
+        "description": "PUT /api/config/settings body \u2014 partial update (D-111)."
+      },
       "UserPublic": {
         "properties": {
           "user_id": {
@@ -993,6 +1606,32 @@
         "title": "UserPublic",
         "description": "A user as exposed on the wire \u2014 no password_hash, ever."
       },
+      "UserSettings": {
+        "properties": {
+          "planner_model": {
+            "type": "string",
+            "title": "Planner Model",
+            "default": "gpt-oss:20b"
+          },
+          "writer_model": {
+            "type": "string",
+            "title": "Writer Model",
+            "default": "gpt-oss:20b"
+          },
+          "methodology_defaults": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Methodology Defaults"
+          },
+          "appearance": {
+            "type": "string",
+            "title": "Appearance",
+            "default": "system"
+          }
+        },
+        "type": "object",
+        "title": "UserSettings"
+      },
       "ValidationError": {
         "properties": {
           "loc": {

frontend/src/components/library-view.tsx

@@ -19,6 +19,7 @@ import Link from "next/link";
 import { useEffect, useState } from "react";
 import {
   api,
+  liveMode,
   type InboxItem,
   type ProjectGraph,
   type ReportConnection,
@@ -424,10 +425,19 @@ function ProjectGraphPanel({ graph }: { graph: ProjectGraph }) {
 /* Task inbox panel (REQ-60)                                            */
 /* ------------------------------------------------------------------ */
 
+/**
+ * G-109 (task-inbox honesty): in LIVE mode the status is DERIVED
+ * server-side (answered-iff the source run reached DONE — D-114), so
+ * the checkbox is display-honest — disabled and annotated, never a
+ * free toggle that silently reverts on the next fetch. Persisted
+ * per-question check state is v0.4+ (REQ-45 backlog). MOCK mode keeps
+ * the free toggle byte-for-byte (the dev fixture owns its state).
+ */
 function TaskInboxPanel({ initialItems }: { initialItems: InboxItem[] }) {
   const [items, setItems] = useState(initialItems);
 
   const toggle = (id: string) => {
+    if (liveMode) return; // display-honest: live status is derived, not local
     setItems((current) =>
       current.map((item) =>
         item.id === id
@@ -452,9 +462,16 @@ function TaskInboxPanel({ initialItems }: { initialItems: InboxItem[] }) {
       <p className="mt-1 text-caption text-ink-soft">
         Open questions worth following up · {openCount} open
       </p>
-      <p className="mt-1 text-caption text-ink-faint">
-        Toggles are local-only — the inbox persists in v0.2.
-      </p>
+      {liveMode ? (
+        <p className="mt-1 text-caption text-ink-faint" data-testid="inbox-derived-note">
+          A question is answered when its research run completes — status
+          follows the run.
+        </p>
+      ) : (
+        <p className="mt-1 text-caption text-ink-faint">
+          Toggles are local-only — the inbox persists in v0.2.
+        </p>
+      )}
 
       <ul className="mt-4 space-y-2">
         {items.map((item) => (
@@ -463,7 +480,15 @@ function TaskInboxPanel({ initialItems }: { initialItems: InboxItem[] }) {
               type="checkbox"
               checked={item.status === "done"}
               onChange={() => toggle(item.id)}
+              // G-109: derived status in live mode — disabled, never a
+              // silent revert; mock keeps the free toggle.
+              disabled={liveMode}
               aria-label={item.question}
+              title={
+                liveMode
+                  ? "Follows its research run — answered when the run completes"
+                  : undefined
+              }
               className="mt-1 h-4 w-4 accent-[var(--color-accent)]"
             />
             <span

frontend/src/components/live-mode-surfaces.test.tsx

@@ -0,0 +1,374 @@
+/**
+ * Live-mode component tests (T-3.9, G-109; REQ-68, REQ-80).
+ *
+ * The previously-delegated surfaces driving REAL components in live
+ * mode — no boundary mocks, the ApiClient surface only:
+ *   - G-109: the task-inbox checkbox is DISPLAY-HONEST in live mode —
+ *     derived status (open-iff run not DONE), disabled + annotated;
+ *     a click never flips it; the mock keeps the free toggle (pinned
+ *     by the unchanged library-view suite).
+ *   - Refine honesty: a 503 from the real planner endpoint surfaces
+ *     the error state — never a hang, never synthetic questions.
+ *
+ * House pattern (user-menu-session suite): the module's `api` +
+ * `liveMode` exports are swapped per case through module
+ * interception; the components themselves are UNTOUCHED.
+ */
+
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AskView } from "@/components/ask-view";
+import { LibraryView } from "@/components/library-view";
+import type {
+  InboxItem,
+  ProjectGraph,
+  ReportConnection,
+  ReportLibrary,
+} from "@/lib/api/client";
+
+const pushMock = vi.hoisted(() => vi.fn());
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push: pushMock }),
+}));
+
+const state = vi.hoisted(() => ({
+  api: {} as Record<string, unknown>,
+  liveMode: false,
+}));
+vi.mock("@/lib/api/client", async (importOriginal) => {
+  const actual = await importOriginal<
+    Promise<typeof import("@/lib/api/client")>
+  >();
+  return {
+    ...actual,
+    api: new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          const handler = state.api[prop as string];
+          return typeof handler === "function"
+            ? (handler as (...args: unknown[]) => unknown).bind(state.api)
+            : handler;
+        },
+      },
+    ),
+    get liveMode() {
+      return state.liveMode;
+    },
+  };
+});
+
+/* ------------------------------------------------------------------ */
+/* Live-mode boundary stub — payloads verbatim from the read-models    */
+/* ------------------------------------------------------------------ */
+
+const LIVE_LIBRARY: ReportLibrary = {
+  folders: [
+    {
+      id: "deep-report-battery",
+      name: "Deep Report: Battery",
+      description: "Auto-filed from deep report battery research.",
+    },
+  ],
+  reports: [
+    {
+      id: "rep-runaaaa1",
+      runId: "runaaaa1",
+      title: "Battery Advances",
+      question: "What about battery research?",
+      methodologySlug: "deep-report",
+      category: "deep-report-battery",
+      generatedAt: "2026-09-20T10:05:00Z",
+      citationCount: 1,
+    },
+  ],
+};
+
+const LIVE_CONNECTIONS: ReportConnection[] = [
+  {
+    fromReportId: "rep-runaaaa1",
+    toReportId: "rep-runbbbb1",
+    kind: "shared-sources",
+    label: "2 shared sources",
+  },
+];
+
+const LIVE_GRAPH: ProjectGraph = {
+  nodes: [
+    {
+      id: "runaaaa1",
+      topic: "Battery Advances",
+      linkedSources: ["https://example.org/x"],
+      findings: ["Battery Advances"],
+    },
+  ],
+  edges: [],
+};
+
+const LIVE_INBOX: InboxItem[] = [
+  {
+    id: "runaaaa1#0",
+    question: "What is the research question?",
+    sourceRunId: "runaaaa1",
+    status: "open",
+  },
+  {
+    id: "runbbbb1#0",
+    question: "An answered question",
+    sourceRunId: "runbbbb1",
+    status: "done",
+  },
+];
+
+/** A live-shaped ApiClient surface for the library panels. */
+function liveLibraryApi(): Record<string, unknown> {
+  return {
+    getReportLibrary: vi.fn().mockResolvedValue(LIVE_LIBRARY),
+    getReportConnections: vi.fn().mockResolvedValue(LIVE_CONNECTIONS),
+    getProjectGraph: vi.fn().mockResolvedValue(LIVE_GRAPH),
+    getTaskInbox: vi.fn().mockResolvedValue(LIVE_INBOX),
+  };
+}
+
+beforeEach(() => {
+  pushMock.mockClear();
+});
+
+afterEach(cleanup);
+
+/* ------------------------------------------------------------------ */
+/* G-109 — the task-inbox checkbox is display-honest in live mode      */
+/* ------------------------------------------------------------------ */
+
+describe("LibraryView task inbox — live-mode honesty (G-109)", () => {
+  it("renders every live surface: folders, connections, graph, tasks", async () => {
+    state.api = liveLibraryApi();
+    state.liveMode = true;
+    render(<LibraryView />);
+
+    // Library feeds from the LIVE read-model payload (T-3.9).
+    const card = await screen.findByRole("link", { name: /Battery Advances/i });
+    expect(card).toHaveAttribute("href", "/run/runaaaa1/report");
+    expect(screen.getByRole("button", { name: /Deep Report: Battery/i })).toBeInTheDocument();
+    expect(screen.getByText(/1 citation/i)).toBeInTheDocument();
+    expect(
+      screen.getByText(/Shared sources — 2 shared sources/i),
+    ).toBeInTheDocument();
+    // The graph panel renders the run as a node (topic = report title).
+    const graph = await screen.findByRole("region", { name: "Project graph" });
+    expect(graph.textContent).toContain("Battery Advances");
+  });
+
+  it("live checkboxes are DISABLED and the derived-status note shows", async () => {
+    state.api = liveLibraryApi();
+    state.liveMode = true;
+    render(<LibraryView />);
+
+    await screen.findByRole("region", { name: "Task inbox" });
+    const open = await screen.findByRole("checkbox", {
+      name: "What is the research question?",
+    });
+    const done = await screen.findByRole("checkbox", {
+      name: "An answered question",
+    });
+    // Derived status rendered — open stays open, done stays done.
+    expect(open).not.toBeChecked();
+    expect(done).toBeChecked();
+    // G-109: display-honest — both disabled.
+    expect(open).toBeDisabled();
+    expect(done).toBeDisabled();
+    // Annotated, never silent.
+    expect(
+      screen.getByTestId("inbox-derived-note"),
+    ).toHaveTextContent(/answered when its research run completes/i);
+    // The open count reflects the server-derived statuses.
+    expect(
+      screen.getByText(/open questions worth following up · 1 open/i),
+    ).toBeInTheDocument();
+  });
+
+  it("a click on a live checkbox never flips the derived status", async () => {
+    state.api = liveLibraryApi();
+    state.liveMode = true;
+    const user = userEvent.setup();
+    render(<LibraryView />);
+
+    const open = await screen.findByRole("checkbox", {
+      name: "What is the research question?",
+    });
+    await user.click(open);
+    // Still unchecked — no silent revert because nothing ever changed.
+    expect(open).not.toBeChecked();
+    expect(
+      screen.getByText(/open questions worth following up · 1 open/i),
+    ).toBeInTheDocument();
+  });
+
+  it("mock mode keeps the free toggle byte-for-byte (G-109 dev fixture)", async () => {
+    state.api = liveLibraryApi();
+    state.liveMode = false;
+    const user = userEvent.setup();
+    render(<LibraryView />);
+
+    const open = await screen.findByRole("checkbox", {
+      name: "What is the research question?",
+    });
+    expect(open).toBeEnabled();
+    expect(
+      screen.queryByTestId("inbox-derived-note"),
+    ).toBeNull();
+    await user.click(open);
+    expect(open).toBeChecked();
+    expect(
+      screen.getByText(/open questions worth following up · 0 open/i),
+    ).toBeInTheDocument();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Refine — the real exchange with an honest 503 (T-3.6, REQ-80)        */
+/* ------------------------------------------------------------------ */
+
+describe("RefineDrawer — live-mode 503 honesty", () => {
+  it("surfaces the honest unavailable state — never a hang, never synthetic", async () => {
+    state.api = {
+      getSuggestedQueries: vi.fn().mockResolvedValue([]),
+      getRefinementQuestions: vi
+        .fn()
+        .mockRejectedValue(new Error("live: refine is unavailable — 503")),
+      composeRefinedQuestion: vi.fn(),
+    };
+    state.liveMode = true;
+    const user = userEvent.setup();
+    render(<AskView />);
+
+    await user.type(
+      screen.getByLabelText(/what do you want to know\?/i),
+      "What are the latest advances in solid-state batteries",
+    );
+    await user.click(screen.getByRole("button", { name: /Refine question/i }));
+    expect(
+      await screen.findByRole("region", { name: /Refine your question/i }),
+    ).toBeInTheDocument();
+
+    // The honest error state — the drawer never invents questions.
+    expect(
+      await screen.findByRole("alert"),
+    ).toHaveTextContent(/Refine is unavailable right now/i);
+    expect(
+      screen.queryByLabelText(/matters most to you/i),
+    ).toBeNull();
+
+    // Keep original closes the drawer with the draft untouched.
+    await user.click(screen.getByRole("button", { name: "Keep original" }));
+    expect(
+      screen.queryByRole("region", { name: /Refine your question/i }),
+    ).toBeNull();
+    expect(screen.getByLabelText(/what do you want to know\?/i)).toHaveValue(
+      "What are the latest advances in solid-state batteries",
+    );
+  });
+
+  it("drives the REAL live exchange: model questions → model composition", async () => {
+    state.api = {
+      getSuggestedQueries: vi.fn().mockResolvedValue([]),
+      getRefinementQuestions: vi.fn().mockResolvedValue([
+        {
+          id: "q-1",
+          prompt: "Which application domain matters most?",
+          placeholder: "one short answer",
+          optional: false,
+        },
+        {
+          id: "q-2",
+          prompt: "What decision will this research inform?",
+          placeholder: "one short answer",
+          optional: true,
+        },
+      ]),
+      composeRefinedQuestion: vi
+        .fn()
+        .mockResolvedValue({
+          question: "Solid-state batteries — automotive applications",
+          context: "Feeds a supplier choice.",
+        }),
+    };
+    state.liveMode = true;
+    const user = userEvent.setup();
+    render(<AskView />);
+
+    await user.type(
+      screen.getByLabelText(/what do you want to know\?/i),
+      "What are the latest advances in solid-state batteries",
+    );
+    await user.click(screen.getByRole("button", { name: /Refine question/i }));
+
+    const q1 = await screen.findByLabelText(/Which application domain matters most\?/i);
+    await user.type(q1, "automotive applications");
+    await user.click(screen.getByRole("button", { name: "Next" }));
+
+    const q2 = await screen.findByLabelText(/What decision will this research inform\?/i);
+    await user.type(q2, "choosing a supplier");
+    await user.click(screen.getByRole("button", { name: "Compose question" }));
+
+    // The model-composed refinement arrives and fills the form.
+    expect(
+      await screen.findByText("Solid-state batteries — automotive applications"),
+    ).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Use this" }));
+    expect(screen.getByLabelText(/what do you want to know\?/i)).toHaveValue(
+      "Solid-state batteries — automotive applications",
+    );
+    expect(screen.getByLabelText(/anything else it should know\?/i)).toHaveValue(
+      "Feeds a supplier choice.",
+    );
+  });
+
+  it("live suggestions render with source attribution and never auto-start", async () => {
+    state.api = {
+      getSuggestedQueries: vi.fn().mockResolvedValue([
+        {
+          id: "sug-runcccc1#0",
+          question: "What is the research question?",
+          sourceRunId: "runcccc1",
+          sourceReportTitle: "Deep Report — an in-flight run",
+        },
+      ]),
+      getRefinementQuestions: vi.fn(),
+      composeRefinedQuestion: vi.fn(),
+    };
+    state.liveMode = true;
+    const user = userEvent.setup();
+    render(<AskView />);
+
+    const card = await screen.findByRole("button", {
+      name: /What is the research question\?/i,
+    });
+    expect(
+      screen.getByText(/From your research — Deep Report — an in-flight run/i),
+    ).toBeInTheDocument();
+    await user.click(card);
+    // Click-fills the box — never auto-starts.
+    expect(screen.getByLabelText(/what do you want to know\?/i)).toHaveValue(
+      "What is the research question?",
+    );
+    expect(pushMock).not.toHaveBeenCalled();
+  });
+
+  it("a fresh user sees the honest empty suggestions state in live mode", async () => {
+    state.api = {
+      getSuggestedQueries: vi.fn().mockResolvedValue([]),
+      getRefinementQuestions: vi.fn(),
+      composeRefinedQuestion: vi.fn(),
+    };
+    state.liveMode = true;
+    render(<AskView />);
+
+    await waitFor(() => {
+      expect(
+        screen.getByText(/No open questions yet — they collect here as you run research/i),
+      ).toBeInTheDocument();
+    });
+  });
+});

frontend/src/components/reading-room-live-parity.test.tsx

@@ -0,0 +1,439 @@
+/**
+ * Reading Room live parity + honest exports (T-3.10, REQ-82, REQ-59,
+ * REQ-34 — P-12 closure pins).
+ *
+ * The REAL ReadingRoom component rendering a REAL live payload —
+ * the enriched GET /api/runs/{id}/report envelope (report.json +
+ * evidence.json + markdown + ledger) stubbed at fetch level:
+ *   - structured sections render with [^pN] markers (zero
+ *     report-body.ts changes — C3-10);
+ *   - hover/focus on a marker reveals the EXACT stored quoted passage
+ *     (parity with the mock Reading Room, REQ-82);
+ *   - the ledger panel lists real entries with real quotes;
+ *   - exports carry REAL data: markdown from the served markdown,
+ *     JSON with real claims_supported/health/tier/quotes — the
+ *     fabricated claims_supported:1 and empty quotes are DEAD, and a
+ *     test pins their absence (P-12).
+ *
+ * House pattern (user-menu-session suite): the module's `api` export
+ * is swapped per case through a hoisted module interception backed by
+ * a GeneratedApiClient over a stubbed fetch — the components
+ * themselves are UNTOUCHED, and every call still speaks only the
+ * ApiClient surface.
+ */
+
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ReadingRoom } from "@/components/reading-room";
+import { GeneratedApiClient } from "@/lib/api/live-client";
+
+const state = vi.hoisted(() => ({
+  api: {} as Record<string, unknown>,
+}));
+vi.mock("@/lib/api/client", async (importOriginal) => {
+  const actual = await importOriginal<
+    Promise<typeof import("@/lib/api/client")>
+  >();
+  return {
+    ...actual,
+    api: new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          const handler = state.api[prop as string];
+          return typeof handler === "function"
+            ? (handler as (...args: unknown[]) => unknown).bind(state.api)
+            : handler;
+        },
+      },
+    ),
+  };
+});
+
+/* ------------------------------------------------------------------ */
+/* Fixture live payload — the DONE-run envelope, verbatim shapes        */
+/* ------------------------------------------------------------------ */
+
+const RUN_ID = "runaaaa1";
+
+const FIXTURE_ENVELOPE = {
+  run_id: RUN_ID,
+  markdown:
+    "# Battery Advances\n\nThe verified core finding [p-1]. A second corroborated observation [p-2].\n",
+  report: {
+    v: 1,
+    run_id: RUN_ID,
+    owner_id: "abcd2345",
+    title: "Battery Advances",
+    question: "What about battery research?",
+    methodology_slug: "deep-report",
+    generated_at: "2026-09-20T10:05:00Z",
+    sections: [
+      {
+        heading: "Research Memo",
+        body: "The verified core finding [^p1]. A second corroborated observation [^p2].",
+      },
+    ],
+    citations: [
+      {
+        passage_id: "p1",
+        url: "https://example.org/x",
+        title: "Verification passes",
+        quote: "The verified core finding.",
+        health: "live",
+        authority_tier: "official",
+      },
+      {
+        passage_id: "p2",
+        url: "https://example.com/y",
+        title: "Quote anchoring and auditability",
+        quote: "Anchoring makes auditability real.",
+        health: "stale",
+        authority_tier: "general",
+      },
+    ],
+  },
+  evidence: {
+    v: 1,
+    run_id: RUN_ID,
+    passages: [
+      {
+        passage_id: "p1",
+        url: "https://example.org/x",
+        title: "Verification passes",
+        quote: "The verified core finding.",
+        text: "The verified core finding in full, stored at DONE.",
+      },
+      {
+        passage_id: "p2",
+        url: "https://example.com/y",
+        title: "Quote anchoring and auditability",
+        quote: "Anchoring makes auditability real.",
+        text: "Anchoring is the mechanism that makes auditability real.",
+      },
+    ],
+  },
+};
+
+const FIXTURE_LEDGER = {
+  run_id: RUN_ID,
+  generated_at: "2026-09-20T10:05:00Z",
+  entries: [
+    {
+      url: "https://example.org/x",
+      visited_at: "2026-09-20T10:04:00Z",
+      passages: ["p-1"],
+      claims_supported: 2,
+      health: "live",
+      authority_tier: "official",
+    },
+    {
+      url: "https://example.com/y",
+      visited_at: "2026-09-20T10:04:30Z",
+      passages: ["p-2"],
+      claims_supported: 1,
+      health: "stale",
+      authority_tier: "general",
+    },
+  ],
+  checklist: {
+    run_id: RUN_ID,
+    citations_checked: 2,
+    live: 1,
+    stale: 1,
+    dead: 0,
+  },
+};
+
+/** A fetch stub serving the DONE-run report envelope + ledger. */
+function liveStackFetch(): typeof globalThis.fetch {
+  const routes: Record<string, unknown> = {
+    [`http://127.0.0.1:8000/api/runs/${RUN_ID}/report`]: FIXTURE_ENVELOPE,
+    [`http://127.0.0.1:8000/api/runs/${RUN_ID}/ledger`]: FIXTURE_LEDGER,
+  };
+  return (async (input: RequestInfo | URL) => {
+    const url = input instanceof Request ? input.url : String(input);
+    for (const [prefix, body] of Object.entries(routes)) {
+      if (url.startsWith(prefix)) {
+        return new Response(JSON.stringify(body), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+    }
+    return new Response(JSON.stringify({ detail: "not found" }), { status: 404 });
+  }) as typeof globalThis.fetch;
+}
+
+/** The live client over the stubbed stack — the boundary per case. */
+function liveApi(): Record<string, unknown> {
+  const client = new GeneratedApiClient(liveStackFetch());
+  return client as unknown as Record<string, unknown>;
+}
+
+beforeEach(() => {
+  state.api = liveApi();
+});
+
+afterEach(cleanup);
+
+/* ------------------------------------------------------------------ */
+/* Component parity — the REAL ReadingRoom over the live payload        */
+/* ------------------------------------------------------------------ */
+
+describe("ReadingRoom live parity (T-3.10, REQ-82)", () => {
+  it("renders structured sections + [^pN] markers + the real title", async () => {
+    render(<ReadingRoom id={RUN_ID} />);
+
+    // The REAL report.json title — not a placeholder.
+    expect(await screen.findByText("Battery Advances")).toBeInTheDocument();
+    // Structured section heading from report.json.
+    expect(screen.getByText("Research Memo")).toBeInTheDocument();
+    // Section body text renders around the parsed [^pN] markers —
+    // both text segments of the memo section are present.
+    const memo = screen.getByText("Research Memo").closest("section");
+    expect(memo?.textContent).toContain("The verified core finding ");
+    expect(memo?.textContent).toContain("A second corroborated observation");
+    // Markers render as citation buttons (marker index from pN).
+    expect(
+      screen.getAllByRole("button", { name: /Citation 1:/i }).length,
+    ).toBeGreaterThan(0);
+    expect(
+      screen.getAllByRole("button", { name: /Citation 2:/i }).length,
+    ).toBeGreaterThan(0);
+  });
+
+  it("hover/focus reveals the EXACT stored quoted passage (REQ-82 parity)", async () => {
+    render(<ReadingRoom id={RUN_ID} />);
+
+    const markers = await screen.findAllByRole("button", { name: /Citation 1:/i });
+    markers[0]?.focus();
+    const tooltip = await screen.findByRole("tooltip");
+    // The stored passage quote — exactly what the engine anchored.
+    expect(tooltip.textContent).toContain("The verified core finding.");
+    expect(tooltip.textContent).toContain("Verification passes");
+    expect(tooltip.textContent).toContain("example.org");
+    // Tier map: official → 1.
+    expect(tooltip.textContent).toContain("tier 1");
+  });
+
+  it("the ledger panel lists the REAL entries with quotes + health", async () => {
+    render(<ReadingRoom id={RUN_ID} />);
+
+    expect(await screen.findByText("Citation ledger")).toBeInTheDocument();
+    expect(
+      screen.getByText("2 sources · every claim traceable to a visited passage"),
+    ).toBeInTheDocument();
+    // Real entry titles + real quotes.
+    expect(screen.getByText("Verification passes")).toBeInTheDocument();
+    expect(
+      screen.getByText("Quote anchoring and auditability"),
+    ).toBeInTheDocument();
+    expect(screen.getByText(/“The verified core finding\.”/)).toBeInTheDocument();
+    // Health badges from the real ledger health values.
+    expect(screen.getAllByText(/live/i).length).toBeGreaterThan(0);
+    expect(screen.getByText(/stale/i)).toBeInTheDocument();
+  });
+
+  it("markdown-only fallback renders honestly for a pre-artifact DONE run", async () => {
+    // Swap in a pre-artifact envelope: markdown only, null artifacts —
+    // with a ledger still served (the run reached DONE and the ledger
+    // predates report.json; the route never 500s — D-106).
+    const preArtifact = new GeneratedApiClient(
+      (async (input: RequestInfo | URL) => {
+        const url = input instanceof Request ? input.url : String(input);
+        if (url.includes("/report")) {
+          return new Response(
+            JSON.stringify({
+              run_id: "runbbbb1",
+              markdown: "# Old Report\n\nRaw [p-1] markers only.",
+              report: null,
+              evidence: null,
+            }),
+            { status: 200, headers: { "Content-Type": "application/json" } },
+          );
+        }
+        if (url.includes("/ledger")) {
+          return new Response(
+            JSON.stringify({
+              run_id: "runbbbb1",
+              generated_at: "2026-09-19T10:05:00Z",
+              entries: [],
+              checklist: { run_id: "runbbbb1", citations_checked: 0 },
+            }),
+            { status: 200, headers: { "Content-Type": "application/json" } },
+          );
+        }
+        return new Response(JSON.stringify({ detail: "not found" }), {
+          status: 404,
+        });
+      }) as typeof globalThis.fetch,
+    );
+    state.api = preArtifact as unknown as Record<string, unknown>;
+
+    render(<ReadingRoom id="runbbbb1" />);
+
+    // The served markdown, verbatim — never a 500, never fabricated
+    // sections or citations.
+    expect(await screen.findByText("Report")).toBeInTheDocument();
+    expect(screen.getByText(/Raw \[p-1\] markers only\./i)).toBeInTheDocument();
+    // No citation markers as buttons — there are no citations.
+    expect(screen.queryByRole("button", { name: /Citation/i })).toBeNull();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Honest exports — P-12 closure pins (boundary level)                   */
+/* ------------------------------------------------------------------ */
+
+describe("exportReport — real data, P-12 fabrication dead (T-3.10, REQ-34)", () => {
+  it("markdown export carries the SERVED markdown + a real-quote citation block", async () => {
+    const client = new GeneratedApiClient(liveStackFetch());
+    const markdown = await client.exportReport(RUN_ID, "markdown");
+    expect(markdown.filename).toBe(`researchx-${RUN_ID}.md`);
+    // The served report.md verbatim — raw [p-N] markers intact (C3-10).
+    expect(markdown.content).toContain("# Battery Advances");
+    expect(markdown.content).toContain("The verified core finding [p-1].");
+    // Citations block: real URLs as links + real health/tier.
+    expect(markdown.content).toContain("](https://example.org/x)");
+    expect(markdown.content).toContain("✓ live");
+    expect(markdown.content).toContain("△ stale");
+    // The REAL stored quote appears in the citation block.
+    expect(markdown.content).toContain("The verified core finding.");
+  });
+
+  it("JSON export carries REAL claims_supported/health/tier/quotes per entry", async () => {
+    const client = new GeneratedApiClient(liveStackFetch());
+    const json = await client.exportReport(RUN_ID, "json");
+    expect(json.filename).toBe(`researchx-${RUN_ID}.json`);
+    const parsed = JSON.parse(json.content) as {
+      run_id: string;
+      generated_at: string;
+      entries: Array<{
+        url: string;
+        visited_at: string;
+        passages: string[];
+        claims_supported: number;
+        health: string;
+        authority_tier: string;
+        quote: string;
+      }>;
+      checklist: Record<string, unknown>;
+    };
+    expect(parsed.run_id).toBe(RUN_ID);
+    expect(parsed.entries).toHaveLength(2);
+    // Entry 0: the REAL values from ledger.json — claims_supported 2
+    // (NOT the fabricated 1), live health, official tier.
+    expect(parsed.entries[0]?.url).toBe("https://example.org/x");
+    expect(parsed.entries[0]?.claims_supported).toBe(2);
+    expect(parsed.entries[0]?.health).toBe("live");
+    expect(parsed.entries[0]?.authority_tier).toBe("official");
+    // Entry 1 keeps its own real values — the entries are not clones.
+    expect(parsed.entries[1]?.claims_supported).toBe(1);
+    expect(parsed.entries[1]?.health).toBe("stale");
+    // The REAL stored quotes — never empty strings.
+    expect(parsed.entries[0]?.quote).toBe("The verified core finding.");
+    expect(parsed.entries[1]?.quote).toBe("Anchoring makes auditability real.");
+    // The real checklist from the ledger artifact.
+    expect(parsed.checklist).toEqual(FIXTURE_LEDGER.checklist);
+  });
+
+  it("P-12 pin: the fabricated claims_supported:1 and empty quotes are ABSENT", async () => {
+    const client = new GeneratedApiClient(liveStackFetch());
+    const json = await client.exportReport(RUN_ID, "json");
+    // Every entry carries its OWN claims count — an all-1s dump would
+    // mean the fabrication is back (entry 0's real count is 2).
+    const claims = JSON.parse(json.content) as {
+      entries: Array<{ claims_supported: number; quote: string }>;
+    };
+    expect(claims.entries.map((e) => e.claims_supported)).toEqual([2, 1]);
+    // No empty quotes anywhere.
+    for (const entry of claims.entries) {
+      expect(entry.quote.length).toBeGreaterThan(0);
+    }
+    // And the export never emits the mock-era placeholder title either.
+    expect(json.content).not.toContain('"Research Report"');
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* getReport/getLedger mappings — the boundary contract                  */
+/* ------------------------------------------------------------------ */
+
+describe("getReport/getLedger live mappings (T-3.10)", () => {
+  it("getReport maps report.json → Report with real quotes + the tier map", async () => {
+    const client = new GeneratedApiClient(liveStackFetch());
+    const report = await client.getReport(RUN_ID);
+    expect(report.runId).toBe(RUN_ID);
+    expect(report.title).toBe("Battery Advances");
+    expect(report.sections).toEqual([
+      {
+        heading: "Research Memo",
+        body: "The verified core finding [^p1]. A second corroborated observation [^p2].",
+      },
+    ]);
+    // [^pN] markers survive byte-for-byte — zero report-body.ts changes.
+    expect(report.sections[0]?.body).toMatch(/\[\^p1\]/);
+    expect(report.citations).toHaveLength(2);
+    // Tier map: official→1, general→3.
+    expect(report.citations[0]).toEqual({
+      id: "c-1",
+      url: "https://example.org/x",
+      title: "Verification passes",
+      site: "example.org",
+      passageId: "p1",
+      quote: "The verified core finding.",
+      verification: "live",
+      authorityTier: 1,
+    });
+    expect(report.citations[1]?.authorityTier).toBe(3);
+    expect(report.citations[1]?.site).toBe("example.com");
+    expect(report.citations[1]?.verification).toBe("stale");
+  });
+
+  it("getLedger maps real entries with pN-normalized ids + stored quotes", async () => {
+    const client = new GeneratedApiClient(liveStackFetch());
+    const ledger = await client.getLedger(RUN_ID);
+    expect(ledger.runId).toBe(RUN_ID);
+    expect(ledger.generatedAt).toBe("2026-09-20T10:05:00Z");
+    expect(ledger.citations).toHaveLength(2);
+    // ledger.json ids are p-N; the Citation passageId is the pN form
+    // the [^pN] markers parse to.
+    expect(ledger.citations[0]?.passageId).toBe("p1");
+    expect(ledger.citations[0]?.quote).toBe("The verified core finding.");
+    expect(ledger.citations[0]?.authorityTier).toBe(1);
+    expect(ledger.citations[1]?.passageId).toBe("p2");
+    expect(ledger.citations[1]?.verification).toBe("stale");
+  });
+
+  it("the report + ledger share one network read per DONE run (memoized envelope)", async () => {
+    let reportCalls = 0;
+    const counting = new GeneratedApiClient(
+      (async (input: RequestInfo | URL) => {
+        const url = input instanceof Request ? input.url : String(input);
+        if (url.includes("/report")) {
+          reportCalls += 1;
+          return new Response(JSON.stringify(FIXTURE_ENVELOPE), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          });
+        }
+        if (url.includes("/ledger")) {
+          return new Response(JSON.stringify(FIXTURE_LEDGER), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          });
+        }
+        return new Response(JSON.stringify({ detail: "not found" }), {
+          status: 404,
+        });
+      }) as typeof globalThis.fetch,
+    );
+    await counting.getReport(RUN_ID);
+    await counting.getLedger(RUN_ID);
+    await counting.exportReport(RUN_ID, "markdown");
+    // report route hit exactly ONCE: the envelope is memoized per run
+    // once report.json exists (a terminal run's artifacts are final).
+    expect(reportCalls).toBe(1);
+  });
+});

frontend/src/components/settings-view.tsx

@@ -1,26 +1,32 @@
 "use client";
 
 /**
- * SettingsView (T-5.4, REQ-65) — the /settings screen.
+ * SettingsView (T-5.4, REQ-65; P2 T-2.9, REQ-72/73/74) — /settings.
  *
- * Five sections, all through the ApiClient boundary:
- *  - API keys: masked values (raw keys never reach the UI), endpoint
- *    labels, configured state
- *  - Storage: local directory reports are written to
- *  - Methodology defaults: default methodology + resolved 12-dial
- *    display (the REQ-04 reproducibility vocabulary)
- *  - Appearance: theme slot — preview-marked (paper palette is
- *    light-only today)
- *  - About & version: prototype notice + version
- *
- * Save persists through api.saveSettings; the mock round-trips it.
+ * Mock mode keeps the v0.1 five sections byte-for-byte (component
+ * tests pin them). Live/hosted mode adds the per-user surfaces on
+ * top, all through the ApiClient boundary:
+ *  - Model credentials (REQ-73/74): resolved credential tier badge
+ *    (user | server | keyless), masked model-key entry (password
+ *    input → setModelKey; masked display "…1234"; the raw key is
+ *    never echoed), honest disabled state when the key store is off
+ *    (409 KeyStoreDisabledError → the reason is shown)
+ *  - Model names (REQ-72): planner/writer inputs bound to
+ *    getUserSettings/saveUserSettings
+ *  - Usage (P-13): per-user cost counters (runs created/completed)
+ *  - Storage: display-only in live mode (D-111) — the server manages
+ *    the directory; no path picker
  */
 
 import { useEffect, useState } from "react";
 import {
   api,
+  liveMode,
+  type ConfigStatus,
   type Methodology,
+  type ModelKeyStatus,
   type Settings,
+  type UserSettings,
 } from "@/lib/api/client";
 import { formatDialValue } from "@/lib/dials";
 
@@ -29,6 +35,19 @@ type SettingsState =
   | { kind: "error"; message: string }
   | { kind: "ready"; settings: Settings; methodologies: Methodology[] };
 
+/** Live-mode per-user panel state (T-2.9) — keyed to the boundary. */
+type UserSettingsState =
+  | { kind: "loading" }
+  | { kind: "error"; message: string }
+  | { kind: "ready"; settings: UserSettings };
+
+/** Resolved credential tier (REQ-74) — badge copy per tier. */
+const TIER_COPY: Record<ConfigStatus["resolved_tier"], string> = {
+  user: "Your key",
+  server: "Server key",
+  keyless: "Keyless (localhost)",
+};
+
 export function SettingsView() {
   const [state, setState] = useState<SettingsState>({ kind: "loading" });
   const [storage, setStorage] = useState("");
@@ -37,6 +56,19 @@ export function SettingsView() {
     "idle",
   );
 
+  // ---- live-only per-user surface (T-2.9) --------------------------
+  const [userSettings, setUserSettings] = useState<UserSettingsState>({
+    kind: "loading",
+  });
+  const [configStatus, setConfigStatus] = useState<ConfigStatus | null>(null);
+  const [keyDraft, setKeyDraft] = useState("");
+  const [keyState, setKeyState] = useState<
+    { kind: "idle" } | { kind: "saving" } | { kind: "saved" } | { kind: "error"; message: string }
+  >({ kind: "idle" });
+  const [modelsSaveState, setModelsSaveState] = useState<"idle" | "saving" | "saved" | "error">(
+    "idle",
+  );
+
   useEffect(() => {
     let cancelled = false;
     (async () => {
@@ -64,6 +96,34 @@ export function SettingsView() {
     };
   }, []);
 
+  // Live mode only: per-user settings + credential/usage status.
+  useEffect(() => {
+    if (!liveMode) return;
+    let cancelled = false;
+    (async () => {
+      try {
+        const [user, status] = await Promise.all([
+          api.getUserSettings(),
+          api.getConfigStatus(),
+        ]);
+        if (!cancelled) {
+          setUserSettings({ kind: "ready", settings: user });
+          setConfigStatus(status);
+        }
+      } catch (cause) {
+        if (!cancelled) {
+          setUserSettings({
+            kind: "error",
+            message: cause instanceof Error ? cause.message : "Account settings unavailable",
+          });
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
   if (state.kind === "loading") {
     return <p className="mt-8 text-small text-ink-faint">Loading settings…</p>;
   }
@@ -94,6 +154,49 @@ export function SettingsView() {
     }
   };
 
+  // ---- live per-user handlers ---------------------------------------
+
+  const userReady = userSettings.kind === "ready" ? userSettings.settings : null;
+
+  const saveModels = async (planner: string, writer: string) => {
+    setModelsSaveState("saving");
+    try {
+      const saved = await api.saveUserSettings({
+        planner_model: planner,
+        writer_model: writer,
+      });
+      if (userSettings.kind === "ready") {
+        setUserSettings({ kind: "ready", settings: saved });
+      }
+      setModelsSaveState("saved");
+    } catch {
+      setModelsSaveState("error");
+    }
+  };
+
+  const submitModelKey = async () => {
+    const raw = keyDraft.trim();
+    if (!raw) return;
+    setKeyState({ kind: "saving" });
+    try {
+      const status = await api.setModelKey(raw);
+      // The raw key NEVER survives this handler — clear the field and
+      // keep only the masked status the boundary returned.
+      setKeyDraft("");
+      setKeyState({ kind: "saved" });
+      if (configStatus) {
+        setConfigStatus({ ...configStatus, key_status: status, resolved_tier: "user" });
+      }
+    } catch (cause) {
+      setKeyDraft("");
+      setKeyState({
+        kind: "error",
+        message:
+          cause instanceof Error ? cause.message : "Could not store the key",
+      });
+    }
+  };
+
   return (
     <div>
       <h1 className="text-display font-semibold text-ink">Settings</h1>
@@ -103,6 +206,48 @@ export function SettingsView() {
       </p>
 
       <div className="mt-block space-y-8">
+        {/* ---- Model credentials (live only, T-2.9) ----------------- */}
+        {liveMode && (
+          <ModelCredentialsSection
+            configStatus={configStatus}
+            keyDraft={keyDraft}
+            onKeyDraft={setKeyDraft}
+            keyState={keyState}
+            onSubmit={submitModelKey}
+          />
+        )}
+
+        {/* ---- Model names (live only, T-2.9) ------------------------ */}
+        {liveMode && (
+          <section
+            aria-label="Model names"
+            className="rounded-card border border-hairline bg-paper-raised px-5 py-5"
+          >
+            <h2 className="text-small font-semibold uppercase tracking-wide text-ink-faint">
+              Model names
+            </h2>
+            <p className="mt-1 text-caption text-ink-soft">
+              The models your runs use — saved to your account and applied
+              to every new run.
+            </p>
+            {userSettings.kind === "loading" && (
+              <p className="mt-4 text-caption text-ink-faint">Loading…</p>
+            )}
+            {userSettings.kind === "error" && (
+              <p role="alert" className="mt-4 text-caption text-danger">
+                {userSettings.message}
+              </p>
+            )}
+            {userReady && (
+              <ModelNamesForm
+                initial={userReady}
+                saveState={modelsSaveState}
+                onSave={saveModels}
+              />
+            )}
+          </section>
+        )}
+
         {/* ---- API keys --------------------------------------------- */}
         <section
           aria-label="API keys"
@@ -154,20 +299,62 @@ export function SettingsView() {
             Local directory finished reports are written to — no upload
             quotas, plain Markdown and JSON on disk.
           </p>
-          <label className="mt-4 block">
-            <span className="text-small font-medium text-ink">Reports directory</span>
-            <input
-              type="text"
-              value={storage}
-              onChange={(event) => {
-                setStorage(event.target.value);
-                setSaveState("idle");
-              }}
-              className="mt-1 w-full max-w-md rounded-card border border-hairline bg-paper-sunken px-3 py-2 text-body text-ink"
-            />
-          </label>
+          {liveMode && configStatus ? (
+            // D-111: server-managed, display-only in live mode — no picker.
+            <p
+              data-testid="storage-display"
+              className="mt-4 rounded-card border border-hairline bg-paper-sunken px-3 py-2 font-mono text-small text-ink"
+            >
+              {configStatus.storage_dir}
+              <span className="ml-2 text-caption text-ink-faint">
+                (server-managed — read only)
+              </span>
+            </p>
+          ) : (
+            <label className="mt-4 block">
+              <span className="text-small font-medium text-ink">Reports directory</span>
+              <input
+                type="text"
+                value={storage}
+                onChange={(event) => {
+                  setStorage(event.target.value);
+                  setSaveState("idle");
+                }}
+                className="mt-1 w-full max-w-md rounded-card border border-hairline bg-paper-sunken px-3 py-2 text-body text-ink"
+              />
+            </label>
+          )}
         </section>
 
+        {/* ---- Usage (live only, P-13) -------------------------------- */}
+        {liveMode && configStatus && (
+          <section
+            aria-label="Usage"
+            className="rounded-card border border-hairline bg-paper-raised px-5 py-5"
+          >
+            <h2 className="text-small font-semibold uppercase tracking-wide text-ink-faint">
+              Usage
+            </h2>
+            <p className="mt-1 text-caption text-ink-soft">
+              Your research activity on this server.
+            </p>
+            <dl className="mt-4 grid grid-cols-2 gap-4 rounded-card border border-hairline bg-paper px-4 py-4">
+              <div>
+                <dt className="text-caption text-ink-faint">Runs created</dt>
+                <dd className="text-body font-medium text-ink">
+                  {configStatus.cost_counters.runs_created}
+                </dd>
+              </div>
+              <div>
+                <dt className="text-caption text-ink-faint">Runs completed</dt>
+                <dd className="text-body font-medium text-ink">
+                  {configStatus.cost_counters.runs_completed}
+                </dd>
+              </div>
+            </dl>
+          </section>
+        )}
+
         {/* ---- Methodology defaults ---------------------------------- */}
         <section
           aria-label="Methodology defaults"
@@ -276,6 +463,220 @@ export function SettingsView() {
   );
 }
 
+/* -------------------------------------------------------------------- */
+/* Live-mode per-user subcomponents (T-2.9)                              */
+/* -------------------------------------------------------------------- */
+
+/**
+ * Model credentials (REQ-73/74): the resolved credential tier badge,
+ * the masked key status, and the password-shaped key entry. The raw
+ * key lives in the input only until submit; the response is masked
+ * ("…1234"). A disabled key store (409) shows the honest reason.
+ */
+function ModelCredentialsSection({
+  configStatus,
+  keyDraft,
+  onKeyDraft,
+  keyState,
+  onSubmit,
+}: {
+  configStatus: ConfigStatus | null;
+  keyDraft: string;
+  onKeyDraft: (next: string) => void;
+  keyState:
+    | { kind: "idle" }
+    | { kind: "saving" }
+    | { kind: "saved" }
+    | { kind: "error"; message: string };
+  onSubmit: () => void;
+}) {
+  const tier = configStatus?.resolved_tier ?? "keyless";
+  const keyStatus: ModelKeyStatus | undefined = configStatus?.key_status;
+  const keyStoreEnabled = configStatus?.key_store === "enabled";
+
+  return (
+    <section
+      aria-label="Model credentials"
+      className="rounded-card border border-hairline bg-paper-raised px-5 py-5"
+    >
+      <h2 className="text-small font-semibold uppercase tracking-wide text-ink-faint">
+        Model credentials
+      </h2>
+      <p className="mt-1 text-caption text-ink-soft">
+        Your key is encrypted at rest and shown masked — never displayed raw.
+      </p>
+
+      {/* Resolved credential tier (REQ-74) — badge + honest copy. */}
+      <div className="mt-4 flex flex-wrap items-center gap-2">
+        <span className="text-small font-medium text-ink">Credential tier</span>
+        <span
+          data-testid="credential-tier"
+          className={`rounded-pill px-2.5 py-0.5 text-caption ${
+            tier === "user"
+              ? "bg-success-wash text-success"
+              : tier === "server"
+                ? "bg-accent-wash text-accent-ink"
+                : "bg-warn-wash text-warn"
+          }`}
+        >
+          {TIER_COPY[tier]}
+        </span>
+        <span className="text-caption text-ink-faint">
+          {tier === "user"
+            ? "Your runs use your stored key."
+            : tier === "server"
+              ? "Your runs use the server's key."
+              : "No key stored — runs fall back to keyless localhost."}
+        </span>
+      </div>
+
+      {/* Masked key status (REQ-73). */}
+      {keyStatus && (
+        <p
+          data-testid="key-status"
+          className="mt-3 rounded-card border border-hairline bg-paper px-4 py-3 text-caption text-ink-soft"
+        >
+          {keyStatus.configured ? (
+            <>
+              Model key stored —{" "}
+              <span data-testid="key-masked" className="font-medium text-ink">
+                {keyStatus.masked}
+              </span>
+            </>
+          ) : (
+            "No model key stored."
+          )}
+          {keyStatus.reason && (
+            <span data-testid="key-reason" className="mt-1 block text-warn">
+              {keyStatus.reason}
+            </span>
+          )}
+        </p>
+      )}
+
+      {/* Key entry — disabled honestly when the store is off (409 class). */}
+      <label className="mt-4 block">
+        <span className="text-small font-medium text-ink">
+          {keyStatus?.configured ? "Replace model key" : "Add model key"}
+        </span>
+        <div className="mt-1 flex max-w-md gap-2">
+          <input
+            type="password"
+            // A disabled key store refuses with 409 — the input reflects
+            // the honest server state instead of pretending to accept.
+            disabled={!keyStoreEnabled}
+            autoComplete="off"
+            value={keyDraft}
+            onChange={(event) => onKeyDraft(event.target.value)}
+            placeholder="sk-…"
+            aria-label="Model key"
+            className="w-full rounded-card border border-hairline bg-paper-sunken px-3 py-2 text-body text-ink disabled:cursor-not-allowed disabled:opacity-40"
+          />
+          <button
+            type="button"
+            onClick={onSubmit}
+            disabled={!keyStoreEnabled || keyDraft.trim() === "" || keyState.kind === "saving"}
+            className="shrink-0 rounded-pill bg-accent px-4 py-2 text-small font-medium text-paper-raised transition-colors hover:bg-accent-strong disabled:cursor-not-allowed disabled:opacity-40"
+          >
+            {keyState.kind === "saving" ? "Storing…" : "Store key"}
+          </button>
+        </div>
+        {!keyStoreEnabled && (
+          <p data-testid="key-store-disabled" className="mt-2 text-caption text-warn">
+            Key storage is disabled on this server —{" "}
+            {keyStatus?.reason ?? "the key store is not configured."}{" "}
+            Runs use the server tier or keyless localhost.
+          </p>
+        )}
+        {keyState.kind === "saved" && (
+          <p role="status" data-testid="key-saved" className="mt-2 text-caption text-success">
+            Key stored — shown masked above.
+          </p>
+        )}
+        {keyState.kind === "error" && (
+          <p role="alert" data-testid="key-error" className="mt-2 text-caption text-danger">
+            {keyState.message}
+          </p>
+        )}
+      </label>
+    </section>
+  );
+}
+
+/**
+ * Planner/writer model-name form (REQ-72) — bound to getUserSettings /
+ * saveUserSettings. Editing either field enables Save; a save
+ * round-trips and re-renders from the returned payload.
+ */
+function ModelNamesForm({
+  initial,
+  saveState,
+  onSave,
+}: {
+  initial: UserSettings;
+  saveState: "idle" | "saving" | "saved" | "error";
+  onSave: (planner: string, writer: string) => void;
+}) {
+  const [planner, setPlanner] = useState(initial.planner_model);
+  const [writer, setWriter] = useState(initial.writer_model);
+  const [touched, setTouched] = useState(false);
+
+  const dirty = touched && (planner !== initial.planner_model || writer !== initial.writer_model);
+
+  return (
+    <div className="mt-4 space-y-3">
+      <label className="block">
+        <span className="text-small font-medium text-ink">Planner model</span>
+        <input
+          type="text"
+          value={planner}
+          onChange={(event) => {
+            setPlanner(event.target.value);
+            setTouched(true);
+          }}
+          placeholder="gpt-oss:20b"
+          aria-label="Planner model"
+          className="mt-1 w-full max-w-md rounded-card border border-hairline bg-paper-sunken px-3 py-2 text-body text-ink"
+        />
+      </label>
+      <label className="block">
+        <span className="text-small font-medium text-ink">Writer model</span>
+        <input
+          type="text"
+          value={writer}
+          onChange={(event) => {
+            setWriter(event.target.value);
+            setTouched(true);
+          }}
+          placeholder="gpt-oss:20b"
+          aria-label="Writer model"
+          className="mt-1 w-full max-w-md rounded-card border border-hairline bg-paper-sunken px-3 py-2 text-body text-ink"
+        />
+      </label>
+      <div className="flex items-center gap-3">
+        <button
+          type="button"
+          disabled={!dirty || saveState === "saving"}
+          onClick={() => onSave(planner, writer)}
+          className="rounded-pill bg-accent px-5 py-2 text-small font-medium text-paper-raised transition-colors hover:bg-accent-strong disabled:cursor-not-allowed disabled:opacity-40"
+        >
+          {saveState === "saving" ? "Saving…" : "Save models"}
+        </button>
+        {saveState === "saved" && (
+          <p role="status" className="text-caption text-success">
+            Saved — applied to your next runs.
+          </p>
+        )}
+        {saveState === "error" && (
+          <p role="alert" className="text-caption text-danger">
+            Save failed — try again.
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+
 /**
  * The resolved default-dial display — labels from the DIALS registry.
  * Previews the currently selected methodology (live), falling back to

frontend/src/lib/api/client.ts

@@ -4,17 +4,21 @@
  * Components consume ONLY this interface via the `api` singleton. In
  * v0.1 the singleton is bound to MockApiClient; in v0.2 phase 3 the
  * binding swaps to the OpenAPI-generated client with no component
- * rewrites. This is the ONLY module allowed to import MockApiClient.
+ * rewrites. Since v0.3 P3 (D-112) the live client is standalone —
+ * this boundary module selects the binding, and it is the ONLY module
+ * allowed to import MockApiClient.
  */
 
 import type {
   CitationLedger,
+  ConfigStatus,
   ConnectionSlot,
   CreateUserInput,
   DialValues,
   DisplayProfile,
   InboxItem,
   Methodology,
+  ModelKeyStatus,
   ProjectGraph,
   RefinementQuestion,
   RefinedQuestion,
@@ -25,6 +29,7 @@ import type {
   Settings,
   SuggestedQuery,
   TraceEvent,
+  UserSettings,
   UserProfile,
 } from "@/lib/types";
 import { MockApiClient } from "@/lib/api/mock/mock-client";
@@ -34,6 +39,7 @@ export type { Report, ReportSection } from "@/lib/types";
 export type {
   Citation,
   CitationLedger,
+  ConfigStatus,
   ConnectionSlot,
   CreateUserInput,
   DialValues,
@@ -42,6 +48,7 @@ export type {
   GraphNode,
   InboxItem,
   Methodology,
+  ModelKeyStatus,
   ProjectGraph,
   RefinementQuestion,
   RefinedQuestion,
@@ -58,8 +65,16 @@ export type {
   SuggestedQuery,
   Task,
   TraceEvent,
+  UserSettings,
   UserProfile,
 } from "@/lib/types";
+/**
+ * Typed key-store refusal (P2, REQ-73) — thrown by setModelKey when
+ * the backend answers 409 (key store disabled / no KEK). Exported as
+ * a VALUE through the boundary so consumers catch it the same way
+ * they catch AuthError.
+ */
+export { KeyStoreDisabledError } from "@/lib/types";
 
 /** Input to createRun — the Ask + Choose screens' combined payload. */
 export interface CreateRunInput {
@@ -176,6 +191,44 @@ export interface ApiClient {
    */
   saveSettings(update: Partial<Settings>): Promise<Settings>;
 
+  /* ---------------------------------------------------------------- */
+  /* v0.3 P2 per-user settings + model keys (T-2.9 — REQ-72/73/74).    */
+  /* C3-18-adjacent extension: the exhaustive P2 additions. The        */
+  /* v0.1 Settings surface stays untouched (mock-mode screens keep      */
+  /* their behavior byte-for-byte); the per-user surface binds to       */
+  /* GET/PUT /api/config/settings and the model-key routes.             */
+  /* ---------------------------------------------------------------- */
+
+  /**
+   * The current user's per-user settings (REQ-72 — GET
+   * /api/config/settings). Fresh users get the server defaults
+   * (planner/writer "gpt-oss:20b", appearance "system").
+   */
+  getUserSettings(): Promise<UserSettings>;
+
+  /**
+   * Persist a partial per-user settings update (REQ-72 — PUT
+   * /api/config/settings, CSRF header in live mode); returns the
+   * merged UserSettings.
+   */
+  saveUserSettings(update: Partial<UserSettings>): Promise<UserSettings>;
+
+  /**
+   * Store the user's raw model key (REQ-73 — PUT
+   * /api/config/settings/model-key). The raw key is sent once and
+   * NEVER echoed: the resolved value is masked-only. A disabled
+   * server-side key store rejects with a typed KeyStoreDisabledError
+   * carrying the honest reason (409) — never a silent no-op.
+   */
+  setModelKey(key: string): Promise<ModelKeyStatus>;
+
+  /**
+   * The current user's credential/usage status (REQ-74 — GET
+   * /api/config): resolved tier, key-store state, masked key status,
+   * adapters, storage dir (display-only), probe, cost counters.
+   */
+  getConfigStatus(): Promise<ConfigStatus>;
+
   /**
    * Follow-up query suggestions for the New Research view —
    * derived from unanswered open questions of past runs
@@ -264,8 +317,9 @@ export const liveMode: boolean =
  * The app-wide singleton. v0.1: MockApiClient (fixture data + scripted
  * event replay, zero API keys). v0.2 P3 (REQ-26/REQ-54): the binding
  * switches to the OpenAPI-generated client in live mode — selected by
- * NEXT_PUBLIC_RESEARCHX_API_MODE=live (mock stays the default). Live mode covers
- * the core research loop only (G-002); other surfaces stay mock-backed.
+ * NEXT_PUBLIC_RESEARCHX_API_MODE=live (mock stays the default). Since
+ * v0.3 P3 (D-112) the live client is STANDALONE — every surface
+ * live-bound, zero delegation to the mock.
  */
 class MockApiClientWithLifecycle extends MockApiClient implements RunLifecycle {
   async pauseRun(id: string): Promise<ResearchRun> {
@@ -282,7 +336,7 @@ function resolveBinding(): ApiClient & RunLifecycle {
     process.env.RESEARCHX_API_MODE ??
     "mock";
   if (mode === "live") {
-    return new GeneratedApiClient() as unknown as ApiClient & RunLifecycle;
+    return new GeneratedApiClient();
   }
   return new MockApiClientWithLifecycle();
 }

frontend/src/lib/api/generated/schema.d.ts

@@ -131,7 +131,17 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Config Status */
+        /**
+         * Config Status
+         * @description Current user's resolved credential tier + status (T-2.6).
+         *
+         *     P-1 closure: the probe is resolved via the factory for the
+         *     CURRENT user — no run creation, no reads of the private
+         *     registry dict, correct with zero runs, no cross-user leak.
+         *     A corrupt/tampered stored envelope degrades the tier honestly
+         *     (server/keyless) and surfaces the error in key_status.reason —
+         *     never a 500, never a silent drop.
+         */
         get: operations["config_status_api_config_get"];
         put?: never;
         post?: never;
@@ -141,6 +151,56 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/config/settings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get Settings */
+        get: operations["get_settings_api_config_settings_get"];
+        /**
+         * Put Settings
+         * @description Persist a partial settings update (REQ-72); returns the
+         *     updated settings. An explicit null field is treated as absent
+         *     (partial-merge semantics — the store refuses null-valued
+         *     fields, so a null can never poison the on-disk payload).
+         */
+        put: operations["put_settings_api_config_settings_put"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/config/settings/model-key": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get Model Key Status
+         * @description Masked-only key status (never the raw key).
+         */
+        get: operations["get_model_key_status_api_config_settings_model_key_get"];
+        /**
+         * Put Model Key
+         * @description Accept the user's raw model key, encrypt it at rest, return
+         *     ONLY the masked status (REQ-73 — the raw key never appears in
+         *     any response, log, or trace). Without a KEK: honest 409.
+         */
+        put: operations["put_model_key_api_config_settings_model_key_put"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/methodologies": {
         parameters: {
             query?: never;
@@ -165,7 +225,13 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /**
+         * List Runs Route
+         * @description All of this owner's runs from disk state files, most recent
+         *     first — the registry-independent run list (post-sweep
+         *     CANCELLED runs surface cancelled, NOT open).
+         */
+        get: operations["list_runs_route_api_runs_get"];
         put?: never;
         /** Create Run */
         post: operations["create_run_api_runs_post"];
@@ -284,7 +350,16 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Run Report */
+        /**
+         * Run Report
+         * @description Disk-read, registry-independent (P-8 full closure, T-3.3):
+         *     the run directory under THIS owner is the existence check — no
+         *     RunRegistry involvement, correct after a restart with zero
+         *     in-memory actors. Pre-artifact DONE runs (and any run whose
+         *     report.json was not yet written) fall back to markdown-only
+         *     with null report/evidence — never a 500 (D-106: old artifacts
+         *     disposable).
+         */
         get: operations["run_report_api_runs__run_id__report_get"];
         put?: never;
         post?: never;
@@ -301,7 +376,11 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Run Ledger */
+        /**
+         * Run Ledger
+         * @description Disk-read, registry-independent (T-3.3): same owner-dir
+         *     existence check as the report route.
+         */
         get: operations["run_ledger_api_runs__run_id__ledger_get"];
         put?: never;
         post?: never;
@@ -311,6 +390,147 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/library": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Library Route */
+        get: operations["library_route_api_library_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/library/connections": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Connections Route */
+        get: operations["connections_route_api_library_connections_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/graph": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Graph Route */
+        get: operations["graph_route_api_graph_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/tasks": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Tasks Route */
+        get: operations["tasks_route_api_tasks_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/suggestions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Suggestions Route */
+        get: operations["suggestions_route_api_suggestions_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/refine/questions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Refine Questions */
+        post: operations["refine_questions_api_refine_questions_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/refine/compose": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Refine Compose */
+        post: operations["refine_compose_api_refine_compose_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/profile": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get Profile */
+        get: operations["get_profile_api_profile_get"];
+        /**
+         * Put Profile
+         * @description Update display name and/or email (no deletion, REQ-81).
+         *     The email stays unique (casefolded) across other users.
+         */
+        put: operations["put_profile_api_profile_put"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -341,6 +561,11 @@ export interface components {
         };
         /** ConfigStatus */
         ConfigStatus: {
+            /** Resolved Tier */
+            resolved_tier: string;
+            /** Key Store */
+            key_store: string;
+            key_status: components["schemas"]["KeyStatus"];
             /** Model Adapter */
             model_adapter: string;
             /** Search Adapter */
@@ -377,6 +602,23 @@ export interface components {
             /** Detail */
             detail?: components["schemas"]["ValidationError"][];
         };
+        /**
+         * KeyStatus
+         * @description Masked-only key status — the raw key NEVER appears (REQ-73).
+         */
+        KeyStatus: {
+            /** Configured */
+            configured: boolean;
+            /** Masked */
+            masked?: string | null;
+            /**
+             * Disabled
+             * @default false
+             */
+            disabled: boolean;
+            /** Reason */
+            reason?: string | null;
+        };
         /** LoginBody */
         LoginBody: {
             /** Email */
@@ -405,6 +647,34 @@ export interface components {
                 [key: string]: unknown;
             };
         };
+        /**
+         * ModelKeyBody
+         * @description PUT /api/config/settings/model-key body — the raw key, accepted,
+         *     never echoed (REQ-73).
+         */
+        ModelKeyBody: {
+            /** Key */
+            key: string;
+        };
+        /** ProfileBody */
+        ProfileBody: {
+            /** Display Name */
+            display_name?: string | null;
+            /** Email */
+            email?: string | null;
+        };
+        /** RefineComposeBody */
+        RefineComposeBody: {
+            /** Draft */
+            draft: string;
+            /** Answers */
+            answers?: string[];
+        };
+        /** RefineDraftBody */
+        RefineDraftBody: {
+            /** Draft */
+            draft: string;
+        };
         /** RegisterBody */
         RegisterBody: {
             /** Email */
@@ -434,6 +704,22 @@ export interface components {
             /** Started At */
             started_at: string;
         };
+        /**
+         * SettingsBody
+         * @description PUT /api/config/settings body — partial update (D-111).
+         */
+        SettingsBody: {
+            /** Planner Model */
+            planner_model?: string | null;
+            /** Writer Model */
+            writer_model?: string | null;
+            /** Methodology Defaults */
+            methodology_defaults?: {
+                [key: string]: unknown;
+            } | null;
+            /** Appearance */
+            appearance?: string | null;
+        };
         /**
          * UserPublic
          * @description A user as exposed on the wire — no password_hash, ever.
@@ -455,6 +741,28 @@ export interface components {
              */
             created_at: string;
         };
+        /** UserSettings */
+        UserSettings: {
+            /**
+             * Planner Model
+             * @default gpt-oss:20b
+             */
+            planner_model: string;
+            /**
+             * Writer Model
+             * @default gpt-oss:20b
+             */
+            writer_model: string;
+            /** Methodology Defaults */
+            methodology_defaults?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Appearance
+             * @default system
+             */
+            appearance: string;
+        };
         /** ValidationError */
         ValidationError: {
             /** Location */
@@ -707,6 +1015,112 @@ export interface operations {
             };
         };
     };
+    get_settings_api_config_settings_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UserSettings"];
+                };
+            };
+        };
+    };
+    put_settings_api_config_settings_put: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SettingsBody"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UserSettings"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    get_model_key_status_api_config_settings_model_key_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["KeyStatus"];
+                };
+            };
+        };
+    };
+    put_model_key_api_config_settings_model_key_put: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ModelKeyBody"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["KeyStatus"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     methodologies_api_methodologies_get: {
         parameters: {
             query?: never;
@@ -727,6 +1141,26 @@ export interface operations {
             };
         };
     };
+    list_runs_route_api_runs_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RunSummary"][];
+                };
+            };
+        };
+    };
     create_run_api_runs_post: {
         parameters: {
             query?: never;
@@ -1016,4 +1450,252 @@ export interface operations {
             };
         };
     };
+    library_route_api_library_get: {
+        parameters: {
+            query?: {
+                sort?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    connections_route_api_library_connections_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    }[];
+                };
+            };
+        };
+    };
+    graph_route_api_graph_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+        };
+    };
+    tasks_route_api_tasks_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: string;
+                    }[];
+                };
+            };
+        };
+    };
+    suggestions_route_api_suggestions_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: string;
+                    }[];
+                };
+            };
+        };
+    };
+    refine_questions_api_refine_questions_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RefineDraftBody"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    refine_compose_api_refine_compose_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RefineComposeBody"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: string;
+                    };
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    get_profile_api_profile_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: string;
+                    };
+                };
+            };
+        };
+    };
+    put_profile_api_profile_put: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ProfileBody"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        [key: string]: string;
+                    };
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
 }

frontend/src/lib/api/live-client.test.ts

@@ -9,15 +9,35 @@ import { describe, expect, it } from "vitest";
 import { GeneratedApiClient } from "@/lib/api/live-client";
 import type { BackendRun } from "@/lib/api/test-helpers";
 
-type RouteHandler = (url: string, init?: RequestInit) => { status: number; body: unknown };
+type RouteHandler = (
+  url: string,
+  init?: RequestInit,
+  body?: string,
+) => { status: number; body: unknown };
 
 function stubRoutes(routes: Record<string, RouteHandler>): typeof globalThis.fetch {
   return (async (input: RequestInfo | URL, init?: RequestInit) => {
-    const url = input instanceof Request ? input.url : String(input);
+    const request = input instanceof Request ? input : undefined;
+    const url = request ? request.url : String(input);
+    // openapi-fetch serializes the body onto the Request — surface it
+    // (plus credentials/headers) back to the route handler so tests
+    // can assert the CSRF header and cookie discipline per call.
+    let body: string | undefined;
+    let sentInit: RequestInit | undefined = init;
+    if (request) {
+      const cloned = request.clone();
+      body = cloned.body ? await cloned.text() : undefined;
+      sentInit = {
+        ...init,
+        method: request.method,
+        credentials: request.credentials,
+        headers: request.headers,
+      };
+    }
     for (const [prefix, handler] of Object.entries(routes)) {
       if (url.startsWith(prefix)) {
-        const { status, body } = handler(url, init);
-        return new Response(JSON.stringify(body), {
+        const { status, body: responseBody } = handler(url, sentInit, body);
+        return new Response(JSON.stringify(responseBody), {
           status,
           headers: { "Content-Type": "application/json" },
         });
@@ -27,6 +47,26 @@ function stubRoutes(routes: Record<string, RouteHandler>): typeof globalThis.fet
   }) as typeof globalThis.fetch;
 }
 
+/** Headers actually sent on a call (CSRF + cookie assertions). */
+function headersOf(init?: RequestInit): Record<string, string> {
+  const raw = init?.headers;
+  const record: Record<string, string> = {};
+  if (
+    typeof raw === "object" &&
+    raw !== null &&
+    typeof (raw as Headers).forEach === "function"
+  ) {
+    (raw as Headers).forEach((v, k) => {
+      record[k] = v;
+    });
+  } else if (Array.isArray(raw)) {
+    for (const [k, v] of raw) record[String(k)] = String(v);
+  } else if (raw) {
+    Object.assign(record, raw);
+  }
+  return record;
+}
+
 const backendRun: BackendRun = {
   id: "abcd2345",
   status: "awaiting_approval",
@@ -54,7 +94,20 @@ describe("GeneratedApiClient (live binding)", () => {
             cost_estimate: "~5k tokens (estimate)",
             why_recommended: "Fastest path to a confident cited answer.",
             output_shape: "memo",
-            dials: { depth: 1, breadth: 1 },
+            dials: {
+              source_universe: "web",
+              search_routing: "single",
+              query_strategy: "decomposed",
+              breadth: 1,
+              depth: 1,
+              quality_gates: "standard",
+              citation_rigor: "per-claim",
+              verification_passes: 1,
+              synthesis_style: "memo",
+              output_structure: "brief",
+              memory_scope: "none",
+              checkpoints: false,
+            },
           },
         ],
       }),
@@ -65,18 +118,41 @@ describe("GeneratedApiClient (live binding)", () => {
     expect(cards[0]?.slug).toBe("rapid-answer");
     expect(cards[0]?.etaMinutes).toBe(2);
     expect(cards[0]?.costEstimate).toContain("estimate");
-    expect(cards[0]?.defaultDials).toEqual({ depth: 1, breadth: 1 });
+    // Snake_case dials map into the full 12-key frontend DialValues
+    // shape (T-3.8): the Advanced drawer reads every key.
+    expect(cards[0]?.defaultDials).toEqual({
+      sourceUniverse: "web",
+      searchRouting: "single",
+      queryStrategy: "decomposed",
+      breadth: 1,
+      depth: 1,
+      qualityGates: "standard",
+      citationRigor: "per-claim",
+      verificationPasses: 1,
+      synthesisStyle: "memo",
+      outputStructure: "brief",
+      memoryScope: "none",
+      checkpoints: "plan-only",
+    });
   });
 
   it("creates runs through the backend contract", async () => {
     const routes = {
-      "http://127.0.0.1:8000/api/runs": (url: string, init?: RequestInit) => {
-        const method =
-          init?.method ?? (url.endsWith("/api/runs") ? "POST" : undefined);
-        return {
-          status: 201,
-          body: method === "POST" ? backendRun : { detail: "wrong method" },
-        };
+      "http://127.0.0.1:8000/api/runs": (
+        _url: string,
+        init?: RequestInit,
+        body?: string,
+      ) => {
+        expect(init?.method).toBe("POST");
+        // T-3.8 — the P1-verify flag stays closed: EVERY core-loop
+        // mutation rides credentials + the CSRF header (C3-05).
+        expect(init?.credentials).toBe("include");
+        expect(headersOf(init)["x-researchx-request"]).toBe("1");
+        expect(JSON.parse(body ?? "null")).toMatchObject({
+          question: "How do engines run?",
+          methodology: "rapid-answer",
+        });
+        return { status: 201, body: backendRun };
       },
     };
     const client = new GeneratedApiClient(stubRoutes(routes));
@@ -91,29 +167,29 @@ describe("GeneratedApiClient (live binding)", () => {
   });
 
   it("approves, cancels, pauses, resumes via lifecycle routes", async () => {
+    // The discipline holds on EVERY lifecycle mutation, not just the
+    // create — the wrapper is the single injection point (T-3.8).
+    const seen: Array<Record<string, unknown>> = [];
+    const capture =
+      (status: string) =>
+      (_url: string, init?: RequestInit): { status: number; body: unknown } => {
+        expect(init?.credentials).toBe("include");
+        expect(headersOf(init)["x-researchx-request"]).toBe("1");
+        seen.push({ method: init?.method, status });
+        return { status: 200, body: { ...backendRun, status } };
+      };
     const routes = {
-      "http://127.0.0.1:8000/api/runs/abcd2345/approve": () => ({
-        status: 200,
-        body: { ...backendRun, status: "searching" },
-      }),
-      "http://127.0.0.1:8000/api/runs/abcd2345/cancel": () => ({
-        status: 200,
-        body: { ...backendRun, status: "cancelled" },
-      }),
-      "http://127.0.0.1:8000/api/runs/abcd2345/pause": () => ({
-        status: 200,
-        body: { ...backendRun, status: "searching" },
-      }),
-      "http://127.0.0.1:8000/api/runs/abcd2345/resume": () => ({
-        status: 200,
-        body: { ...backendRun, status: "verifying" },
-      }),
+      "http://127.0.0.1:8000/api/runs/abcd2345/approve": capture("searching"),
+      "http://127.0.0.1:8000/api/runs/abcd2345/cancel": capture("cancelled"),
+      "http://127.0.0.1:8000/api/runs/abcd2345/pause": capture("searching"),
+      "http://127.0.0.1:8000/api/runs/abcd2345/resume": capture("verifying"),
     };
     const client = new GeneratedApiClient(stubRoutes(routes));
     expect((await client.approvePlan("abcd2345")).status).toBe("searching");
     expect((await client.cancelRun("abcd2345")).status).toBe("cancelled");
     expect((await client.pauseRun("abcd2345")).status).toBe("searching");
     expect((await client.resumeRun("abcd2345")).status).toBe("verifying");
+    expect(seen.map((s) => s.method)).toEqual(["POST", "POST", "POST", "POST"]);
   });
 
   it("maps the ledger to frontend citations with health + tier", async () => {

frontend/src/lib/api/live-surfaces.test.ts

@@ -0,0 +1,564 @@
+/**
+ * Live-surface boundary tests (T-3.9, REQ-76..81 — the surface swaps).
+ *
+ * Every previously-delegated surface, contract-tested against a
+ * stubbed global fetch (no network, no keys): real routes, cookie
+ * discipline on every call, CSRF header on every mutation (C3-05),
+ * payloads mapped through the SAME frontend types the components
+ * consume (zero rewrites proven — REQ-54).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { GeneratedApiClient } from "@/lib/api/live-client";
+import { MockApiClient } from "@/lib/api/mock/mock-client";
+
+type RouteHandler = (
+  url: string,
+  init?: RequestInit,
+  body?: string,
+) => { status: number; body: unknown };
+
+function stubRoutes(routes: Record<string, RouteHandler>): typeof globalThis.fetch {
+  return (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const request = input instanceof Request ? input : undefined;
+    const url = request ? request.url : String(input);
+    // openapi-fetch serializes the body onto the Request — surface it
+    // (plus credentials/headers) back to the route handler.
+    let body: string | undefined;
+    let sentInit: RequestInit | undefined = init;
+    if (request) {
+      const cloned = request.clone();
+      body = cloned.body ? await cloned.text() : undefined;
+      sentInit = {
+        ...init,
+        method: request.method,
+        credentials: request.credentials,
+        headers: request.headers,
+      };
+    }
+    for (const [prefix, handler] of Object.entries(routes)) {
+      if (url.startsWith(prefix)) {
+        const { status, body: responseBody } = handler(url, sentInit, body);
+        return new Response(JSON.stringify(responseBody), {
+          status,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+    }
+    return new Response(JSON.stringify({ detail: "not found" }), { status: 404 });
+  }) as typeof globalThis.fetch;
+}
+
+/** Headers actually sent on a call (CSRF + cookie assertions). */
+function headersOf(init?: RequestInit): Record<string, string> {
+  const raw = init?.headers;
+  const record: Record<string, string> = {};
+  if (
+    typeof raw === "object" &&
+    raw !== null &&
+    typeof (raw as Headers).forEach === "function"
+  ) {
+    (raw as Headers).forEach((v, k) => {
+      record[k] = v;
+    });
+  } else if (Array.isArray(raw)) {
+    for (const [k, v] of raw) record[String(k)] = String(v);
+  } else if (raw) {
+    Object.assign(record, raw);
+  }
+  return record;
+}
+
+const BASE = "http://127.0.0.1:8000";
+
+/* ------------------------------------------------------------------ */
+/* Read-model payloads (verbatim shapes from the live app)             */
+/* ------------------------------------------------------------------ */
+
+const LIBRARY_PAYLOAD = {
+  folders: [
+    {
+      id: "deep-report-battery",
+      name: "Deep Report: Battery",
+      description: "Auto-filed from deep report battery research.",
+    },
+  ],
+  reports: [
+    {
+      id: "rep-runaaaa1",
+      runId: "runaaaa1",
+      title: "Battery Advances",
+      question: "What about battery research?",
+      methodologySlug: "deep-report",
+      category: "deep-report-battery",
+      generatedAt: "2026-09-20T10:05:00Z",
+      citationCount: 1,
+    },
+  ],
+};
+
+const CONNECTIONS_PAYLOAD = [
+  {
+    fromReportId: "rep-runaaaa1",
+    toReportId: "rep-runbbbb1",
+    kind: "shared-sources",
+    label: "2 shared sources",
+  },
+  {
+    fromReportId: "rep-runaaaa1",
+    toReportId: "rep-runcccc1",
+    kind: "related-topic",
+    label: "Adjacent topic",
+  },
+];
+
+const GRAPH_PAYLOAD = {
+  nodes: [
+    {
+      id: "runaaaa1",
+      topic: "Battery Advances",
+      linkedSources: ["https://example.org/x"],
+      findings: ["Battery Advances"],
+    },
+  ],
+  edges: [{ fromId: "runaaaa1", toId: "runbbbb1", sharedSourceCount: 2 }],
+};
+
+const TASKS_PAYLOAD = [
+  {
+    id: "runaaaa1#0",
+    question: "What is the research question?",
+    sourceRunId: "runaaaa1",
+    status: "open",
+  },
+  {
+    id: "runbbbb1#0",
+    question: "An answered question",
+    sourceRunId: "runbbbb1",
+    status: "done",
+  },
+];
+
+const SUGGESTIONS_PAYLOAD = [
+  {
+    id: "sug-runcccc1#0",
+    question: "What is the research question?",
+    sourceRunId: "runcccc1",
+    sourceReportTitle: "Deep Report — an in-flight run",
+  },
+];
+
+const PROFILE_PAYLOAD = {
+  user_id: "abcd2345",
+  display_name: "Ada Owner",
+  email: "owner@example.org",
+};
+
+const CONFIG_PAYLOAD = {
+  resolved_tier: "user",
+  key_store: "enabled",
+  key_status: {
+    configured: true,
+    masked: "…7f2a",
+    disabled: false,
+    reason: null,
+  },
+  model_adapter: "OllamaModelAdapter",
+  search_adapter: "TavilySearchAdapter",
+  storage_dir: "/var/lib/researchx/runs",
+  probe: null,
+  cost_counters: { runs_created: 4, runs_completed: 3 },
+};
+
+/** One stub serving every read-model surface at once. */
+function surfaceRoutes(): Record<string, RouteHandler> {
+  return {
+    [`${BASE}/api/library/connections`]: () => ({
+      status: 200,
+      body: CONNECTIONS_PAYLOAD,
+    }),
+    [`${BASE}/api/library`]: (_url: string, init?: RequestInit) => {
+      expect(init?.credentials).toBe("include");
+      return { status: 200, body: LIBRARY_PAYLOAD };
+    },
+    [`${BASE}/api/graph`]: () => ({ status: 200, body: GRAPH_PAYLOAD }),
+    [`${BASE}/api/tasks`]: () => ({ status: 200, body: TASKS_PAYLOAD }),
+    [`${BASE}/api/suggestions`]: () => ({
+      status: 200,
+      body: SUGGESTIONS_PAYLOAD,
+    }),
+    [`${BASE}/api/profile`]: () => ({ status: 200, body: PROFILE_PAYLOAD }),
+    [`${BASE}/api/config`]: () => ({ status: 200, body: CONFIG_PAYLOAD }),
+  };
+}
+
+describe("GeneratedApiClient live surfaces (T-3.9)", () => {
+  it("getReportLibrary maps the camelCase read-model payload 1:1", async () => {
+    const client = new GeneratedApiClient(stubRoutes(surfaceRoutes()));
+    const library = await client.getReportLibrary();
+    expect(library.folders).toHaveLength(1);
+    expect(library.folders[0]?.id).toBe("deep-report-battery");
+    expect(library.reports).toHaveLength(1);
+    expect(library.reports[0]).toEqual({
+      id: "rep-runaaaa1",
+      runId: "runaaaa1",
+      title: "Battery Advances",
+      question: "What about battery research?",
+      methodologySlug: "deep-report",
+      category: "deep-report-battery",
+      generatedAt: "2026-09-20T10:05:00Z",
+      citationCount: 1,
+    });
+  });
+
+  it("getReportConnections maps kind + label edges", async () => {
+    const client = new GeneratedApiClient(stubRoutes(surfaceRoutes()));
+    const edges = await client.getReportConnections();
+    expect(edges).toEqual([
+      {
+        fromReportId: "rep-runaaaa1",
+        toReportId: "rep-runbbbb1",
+        kind: "shared-sources",
+        label: "2 shared sources",
+      },
+      {
+        fromReportId: "rep-runaaaa1",
+        toReportId: "rep-runcccc1",
+        kind: "related-topic",
+        label: "Adjacent topic",
+      },
+    ]);
+  });
+
+  it("getProjectGraph maps nodes + edges", async () => {
+    const client = new GeneratedApiClient(stubRoutes(surfaceRoutes()));
+    const graph = await client.getProjectGraph();
+    expect(graph.nodes[0]?.topic).toBe("Battery Advances");
+    expect(graph.nodes[0]?.linkedSources).toEqual(["https://example.org/x"]);
+    expect(graph.edges[0]?.sharedSourceCount).toBe(2);
+  });
+
+  it("getTaskInbox maps derived statuses (G-109: open|done only)", async () => {
+    const client = new GeneratedApiClient(stubRoutes(surfaceRoutes()));
+    const inbox = await client.getTaskInbox();
+    expect(inbox).toEqual([
+      {
+        id: "runaaaa1#0",
+        question: "What is the research question?",
+        sourceRunId: "runaaaa1",
+        status: "open",
+      },
+      {
+        id: "runbbbb1#0",
+        question: "An answered question",
+        sourceRunId: "runbbbb1",
+        status: "done",
+      },
+    ]);
+  });
+
+  it("getSuggestedQueries maps open items with source titles; honest empty", async () => {
+    const withItems = new GeneratedApiClient(stubRoutes(surfaceRoutes()));
+    const suggestions = await withItems.getSuggestedQueries();
+    expect(suggestions[0]?.sourceReportTitle).toBe("Deep Report — an in-flight run");
+    expect(suggestions[0]?.id).toBe("sug-runcccc1#0");
+
+    // A fresh user gets an honest empty array — never synthetic content.
+    const empty = new GeneratedApiClient(
+      stubRoutes({
+        [`${BASE}/api/suggestions`]: () => ({ status: 200, body: [] }),
+      }),
+    );
+    expect(await empty.getSuggestedQueries()).toEqual([]);
+  });
+
+  it("getUserProfile maps GET /api/profile into the DisplayProfile", async () => {
+    const client = new GeneratedApiClient(stubRoutes(surfaceRoutes()));
+    const profile = await client.getUserProfile();
+    expect(profile.name).toBe("Ada Owner");
+    expect(profile.initials).toBe("AO");
+    expect(profile.tagline).toBe("owner@example.org");
+  });
+
+  it("getConnectionStatus maps GET /api/config through the five slots (P2-verify closure)", async () => {
+    const client = new GeneratedApiClient(stubRoutes(surfaceRoutes()));
+    const slots = await client.getConnectionStatus();
+    expect(slots.map((s) => s.slot)).toEqual([
+      "model",
+      "search",
+      "storage",
+      "memory",
+      "secrets",
+    ]);
+    const model = slots[0];
+    expect(model?.status).toBe("connected"); // tier "user" — not keyless
+    expect(model?.resolvedTier).toBe("user");
+    expect(model?.keyStore).toBe("enabled");
+    expect(model?.keyStatus?.masked).toBe("…7f2a");
+    expect(model?.detail).toContain("OllamaModelAdapter");
+    // Storage is server-managed, display-only (D-111).
+    expect(slots[2]?.detail).toContain("/var/lib/researchx/runs");
+  });
+
+  it("getSettings composes the v0.1 shape live from config + catalog", async () => {
+    const client = new GeneratedApiClient(
+      stubRoutes({
+        ...surfaceRoutes(),
+        [`${BASE}/api/methodologies`]: () => ({
+          status: 200,
+          body: [
+            {
+              slug: "rapid-answer",
+              name: "Rapid Answer",
+              description: "One pass, one memo.",
+              eta_minutes: 2,
+              cost_estimate: "~5k tokens (estimate)",
+              why_recommended: "Fastest.",
+              output_shape: "memo",
+              dials: {
+                source_universe: "web",
+                search_routing: "single",
+                query_strategy: "decomposed",
+                breadth: 1,
+                depth: 1,
+                quality_gates: "standard",
+                citation_rigor: "per-claim",
+                verification_passes: 1,
+                synthesis_style: "memo",
+                output_structure: "brief",
+                memory_scope: "none",
+                checkpoints: false,
+              },
+            },
+            {
+              slug: "deep-report",
+              name: "Deep Report",
+              description: "Full depth.",
+              eta_minutes: 12,
+              cost_estimate: "~25k tokens (estimate)",
+              why_recommended: "Thorough.",
+              output_shape: "report",
+              dials: {
+                source_universe: "web+academic",
+                search_routing: "adaptive",
+                query_strategy: "decomposed",
+                breadth: 2,
+                depth: 3,
+                quality_gates: "strict",
+                citation_rigor: "per-claim",
+                verification_passes: 2,
+                synthesis_style: "executive",
+                output_structure: "report",
+                memory_scope: "none",
+                checkpoints: true,
+              },
+            },
+          ],
+        }),
+      }),
+    );
+    const settings = await client.getSettings();
+    // The recommended card is the first in catalog order here — deep-report
+    // drives the resolved default (index 0 = recommended per the mapping).
+    expect(settings.defaultMethodologySlug).toBe("rapid-answer");
+    expect(settings.storageDirectory).toBe("/var/lib/researchx/runs");
+    // Masked-only key status — never the raw key.
+    expect(settings.apiKeys[0]?.configured).toBe(true);
+    expect(settings.apiKeys[0]?.maskedValue).toBe("…7f2a");
+    expect(settings.theme).toBe("paper");
+  });
+
+  it("saveSettings answers with the authoritative server read (D-111)", async () => {
+    const client = new GeneratedApiClient(
+      stubRoutes({
+        ...surfaceRoutes(),
+        [`${BASE}/api/methodologies`]: () => ({
+          status: 200,
+          body: [
+            {
+              slug: "rapid-answer",
+              name: "Rapid Answer",
+              description: "One pass, one memo.",
+              eta_minutes: 2,
+              cost_estimate: "~5k tokens (estimate)",
+              why_recommended: "Fastest.",
+              output_shape: "memo",
+              dials: {
+                source_universe: "web",
+                search_routing: "single",
+                query_strategy: "decomposed",
+                breadth: 1,
+                depth: 1,
+                quality_gates: "standard",
+                citation_rigor: "per-claim",
+                verification_passes: 1,
+                synthesis_style: "memo",
+                output_structure: "brief",
+                memory_scope: "none",
+                checkpoints: false,
+              },
+            },
+          ],
+        }),
+      }),
+    );
+    // The server owns every v0.1 field live — a save is a re-read,
+    // never a client-side pretend-persist.
+    const saved = await client.saveSettings({ storageDirectory: "~/elsewhere" });
+    expect(saved.storageDirectory).toBe("/var/lib/researchx/runs");
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Refine — real POSTs, honest 503 (T-3.6/T-3.9)                        */
+/* ------------------------------------------------------------------ */
+
+describe("GeneratedApiClient refine (live binding, REQ-80)", () => {
+  it("getRefinementQuestions POSTs the draft with CSRF + credentials", async () => {
+    const client = new GeneratedApiClient(
+      stubRoutes({
+        [`${BASE}/api/refine/questions`]: (
+          _url: string,
+          init?: RequestInit,
+          body?: string,
+        ) => {
+          expect(init?.method).toBe("POST");
+          expect(headersOf(init)["x-researchx-request"]).toBe("1");
+          expect(init?.credentials).toBe("include");
+          const parsed = JSON.parse(body ?? "null") as { draft: string };
+          expect(parsed.draft).toBe("How do batteries work?");
+          return { status: 200, body: { questions: ["Which scope?", "What decision?"] } };
+        },
+      }),
+    );
+    const questions = await client.getRefinementQuestions("How do batteries work?");
+    expect(questions).toHaveLength(2);
+    expect(questions[0]?.prompt).toBe("Which scope?");
+    expect(questions[0]?.optional).toBe(false); // the first question is required
+    expect(questions[1]?.optional).toBe(true); // the rest are skippable
+  });
+
+  it("getRefinementQuestions 503 → honest error, never a hang, never synthetic", async () => {
+    const client = new GeneratedApiClient(
+      stubRoutes({
+        [`${BASE}/api/refine/questions`]: () => ({
+          status: 503,
+          body: { detail: "no local endpoint and no key — tier unavailable" },
+        }),
+      }),
+    );
+    await expect(client.getRefinementQuestions("draft")).rejects.toThrow(
+      /refine is unavailable/i,
+    );
+  });
+
+  it("composeRefinedQuestion POSTs ordered answers with CSRF + credentials", async () => {
+    const client = new GeneratedApiClient(
+      stubRoutes({
+        [`${BASE}/api/refine/compose`]: (
+          _url: string,
+          init?: RequestInit,
+          body?: string,
+        ) => {
+          expect(headersOf(init)["x-researchx-request"]).toBe("1");
+          expect(init?.credentials).toBe("include");
+          const parsed = JSON.parse(body ?? "null") as {
+            draft: string;
+            answers: string[];
+          };
+          // Answers travel in exchange order, trimmed.
+          expect(parsed.draft).toBe("How do batteries work?");
+          expect(parsed.answers).toEqual(["automotive", "supplier choice", ""]);
+          return {
+            status: 200,
+            body: {
+              question: "How do batteries work? — automotive focus",
+              context: "Feeds a supplier choice.",
+            },
+          };
+        },
+      }),
+    );
+    const refined = await client.composeRefinedQuestion("How do batteries work?", {
+      "q-1": "automotive",
+      "q-2": "supplier choice",
+      "q-3": "",
+    });
+    expect(refined.question).toBe("How do batteries work? — automotive focus");
+    expect(refined.context).toBe("Feeds a supplier choice.");
+  });
+
+  it("composeRefinedQuestion 503 → honest error", async () => {
+    const client = new GeneratedApiClient(
+      stubRoutes({
+        [`${BASE}/api/refine/compose`]: () => ({
+          status: 503,
+          body: { detail: "planner unreachable" },
+        }),
+      }),
+    );
+    await expect(
+      client.composeRefinedQuestion("draft", { "q-1": "answer" }),
+    ).rejects.toThrow(/refine is unavailable/i);
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* D-112: the delegation is DEAD — structural proof                     */
+/* ------------------------------------------------------------------ */
+
+describe("GeneratedApiClient standalone (D-112)", () => {
+  it("has no MockApiClient in its prototype chain — the delegation is gone", () => {
+    const client = new GeneratedApiClient();
+    expect(client).not.toBeInstanceOf(MockApiClient);
+    let proto = Object.getPrototypeOf(client);
+    while (proto !== null) {
+      expect(proto.constructor.name).not.toBe("MockApiClient");
+      proto = Object.getPrototypeOf(proto);
+    }
+  });
+
+  it("implements every ApiClient surface as its own methods", () => {
+    const client = new GeneratedApiClient();
+    const required = [
+      "getMethodologies",
+      "createRun",
+      "getRun",
+      "approvePlan",
+      "cancelRun",
+      "pauseRun",
+      "resumeRun",
+      "getRunEvents",
+      "getReport",
+      "getLedger",
+      "exportReport",
+      "getProjectGraph",
+      "getTaskInbox",
+      "getReportLibrary",
+      "getReportConnections",
+      "getUserProfile",
+      "getConnectionStatus",
+      "getSettings",
+      "saveSettings",
+      "getUserSettings",
+      "saveUserSettings",
+      "setModelKey",
+      "getConfigStatus",
+      "getSuggestedQueries",
+      "getRefinementQuestions",
+      "composeRefinedQuestion",
+      "login",
+      "logout",
+      "getSession",
+      "listUsers",
+      "createUser",
+      "deactivateUser",
+    ] as const;
+    for (const method of required) {
+      expect(
+        typeof (client as unknown as Record<string, unknown>)[method],
+      ).toBe("function");
+    }
+  });
+});

frontend/src/lib/api/mock/mock-client.ts

@@ -23,6 +23,7 @@ import {
   reportConnectionsFixture,
   reportLibraryFixture,
   settingsFixture,
+  userSettingsFixture,
   userProfileFixture,
 } from "@/lib/api/mock/shell-fixtures";
 import {
@@ -33,11 +34,13 @@ import {
 } from "@/lib/api/mock/scripted-run";
 import type {
   CitationLedger,
+  ConfigStatus,
   ConnectionSlot,
   CreateUserInput,
   DisplayProfile,
   InboxItem,
   Methodology,
+  ModelKeyStatus,
   ProjectGraph,
   RefinementQuestion,
   RefinedQuestion,
@@ -48,6 +51,7 @@ import type {
   Settings,
   SuggestedQuery,
   TraceEvent,
+  UserSettings,
   UserProfile,
 } from "@/lib/types";
 
@@ -311,6 +315,74 @@ export class MockApiClient implements ApiClient {
   /** Session-persisted settings (mock-local). */
   #settings: Settings = structuredClone(settingsFixture);
 
+  /* ---------------------------------------------------------------- */
+  /* v0.3 P2 per-user settings + model keys (T-2.9, REQ-72..74).        */
+  /* The mock is an honest zero-backend fixture: it mirrors the        */
+  /* backend's DEFAULT-disabled key store (no KEK in mock mode) so     */
+  /* the UI's degraded states are exercised, not hidden.               */
+  /* ---------------------------------------------------------------- */
+
+  /** Per-user settings — starts from the backend's fresh-user defaults. */
+  #userSettings: UserSettings = structuredClone(userSettingsFixture);
+
+  /** In-memory masked key state — the raw key is NEVER stored. */
+  #modelKey: ModelKeyStatus = {
+    configured: false,
+    masked: null,
+    disabled: false,
+    reason: null,
+  };
+
+  /** Per-user settings (REQ-72) — session-local, defaults for fresh users. */
+  async getUserSettings(): Promise<UserSettings> {
+    return structuredClone(this.#userSettings);
+  }
+
+  /** Persist a partial per-user settings update (REQ-72) — in-memory. */
+  async saveUserSettings(update: Partial<UserSettings>): Promise<UserSettings> {
+    const next: UserSettings = {
+      ...this.#userSettings,
+      ...structuredClone(update),
+    };
+    this.#userSettings = next;
+    return structuredClone(next);
+  }
+
+  /**
+   * Store the raw model key (REQ-73): the mock keeps ONLY the masked
+   * tail in memory — the raw value is accepted, masked, and dropped.
+   * Mirrors the backend's mask shape ("…" + last 4).
+   */
+  async setModelKey(key: string): Promise<ModelKeyStatus> {
+    const masked = `…${key.slice(-4)}`;
+    this.#modelKey = {
+      configured: true,
+      masked: key.length >= 4 ? masked : "…",
+      disabled: false,
+      reason: null,
+    };
+    return structuredClone(this.#modelKey);
+  }
+
+  /**
+   * Honest mock config status (REQ-74): the mock has no per-user key
+   * store (zero-backend fixture), so resolved_tier degrades to
+   * "keyless" — the documented keyless-localhost tier — and key_store
+   * reports "disabled" exactly like a backend without a KEK.
+   */
+  async getConfigStatus(): Promise<ConfigStatus> {
+    return {
+      resolved_tier: "keyless",
+      key_store: "disabled",
+      key_status: structuredClone(this.#modelKey),
+      model_adapter: "FakeModelAdapter",
+      search_adapter: "FakeSearchAdapter",
+      storage_dir: settingsFixture.storageDirectory,
+      probe: null,
+      cost_counters: { runs_created: 0, runs_completed: 0 },
+    };
+  }
+
   /**
    * Follow-up suggestions from unanswered open questions (REQ-67).
    * Derived live from the inbox fixtures — a completed item drops

frontend/src/lib/api/mock/shell-fixtures.ts

@@ -5,9 +5,15 @@
  * masked API-key settings, adapter-slot connection status, and the local
  * single-user profile. Clearly example content, consistent with the
  * battery-research domain used across the prototype fixtures.
+ *
+ * v0.3 P2 (T-2.9): adds the per-user settings fixture (the backend's
+ * fresh-user defaults — planner/writer "gpt-oss:20b", appearance
+ * "system") and the honest keyless/degraded credential fields on the
+ * model connection slot (resolvedTier "keyless", keyStore "disabled" —
+ * the mock has no key store, exactly like a backend without a KEK).
  */
 
-import type { Settings } from "@/lib/types";
+import type { Settings, UserSettings } from "@/lib/types";
 import type {
   DisplayProfile,
   ReportConnection,
@@ -157,6 +163,19 @@ export const settingsFixture: Settings = {
   theme: "paper",
 };
 
+/**
+ * Per-user settings fixture (P2, REQ-72) — mirrors the backend's
+ * fresh-user defaults exactly (auth/settings.py: planner/writer
+ * "gpt-oss:20b", appearance "system"). The mock has no per-user
+ * persistence across sessions; this is the starting payload.
+ */
+export const userSettingsFixture: UserSettings = {
+  planner_model: "gpt-oss:20b",
+  writer_model: "gpt-oss:20b",
+  methodology_defaults: {},
+  appearance: "system",
+};
+
 /* ------------------------------------------------------------------ */
 /* Connection status (REQ-65 — adapter-slot health)                     */
 /* ------------------------------------------------------------------ */
@@ -169,6 +188,18 @@ export const connectionStatusFixture: ConnectionSlot[] = [
     label: "Model",
     status: "connected",
     detail: "Ollama cloud — key detected",
+    // P2 (REQ-74) honest mock: the zero-backend fixture has no
+    // per-user key store and no server key, so the tier degrades to
+    // keyless localhost — the documented keyless path, not a lie.
+    resolvedTier: "keyless",
+    keyStore: "disabled",
+    keyStatus: {
+      configured: false,
+      masked: null,
+      disabled: true,
+      reason:
+        "mock fixture: no key store (zero-backend mode) — the credential chain stays keyless",
+    },
   },
   {
     slot: "search",

frontend/src/lib/api/user-settings-boundary.test.ts

@@ -0,0 +1,313 @@
+/**
+ * Per-user settings + model-key boundary tests (T-2.9, REQ-72/73/74).
+ *
+ * The v0.3 P2 ApiClient additions — getUserSettings / saveUserSettings /
+ * setModelKey / getConfigStatus — contract-tested against BOTH bindings:
+ *   - the mock binding: honest zero-backend fixture (fresh-user defaults,
+ *     in-memory masked key state, keyless tier, key store "disabled"), and
+ *   - the live binding against a stubbed global fetch (no network, no
+ *     keys): real routes, CSRF header on every mutation (C3-05),
+ *     credentials:"include" cookie discipline, masked-only key echo,
+ *     and the honest 409 KeyStoreDisabledError refusal.
+ */
+
+import { describe, expect, it } from "vitest";
+
+// client.ts first (runtime import — it binds MockApiClient before the
+// live client extends it); KeyStoreDisabledError is consumed through
+// the boundary like AuthError in the session tests.
+import { KeyStoreDisabledError, type ApiClient } from "@/lib/api/client";
+import { MockApiClient } from "@/lib/api/mock/mock-client";
+import { GeneratedApiClient } from "@/lib/api/live-client";
+
+/* ------------------------------------------------------------------ */
+/* Mock binding — standalone per-user fixture                           */
+/* ------------------------------------------------------------------ */
+
+describe("MockApiClient per-user settings surface (T-2.9)", () => {
+  it("getUserSettings returns the fresh-user defaults (planner/writer gpt-oss:20b)", async () => {
+    const client: ApiClient = new MockApiClient();
+    const settings = await client.getUserSettings();
+    expect(settings.planner_model).toBe("gpt-oss:20b");
+    expect(settings.writer_model).toBe("gpt-oss:20b");
+    expect(settings.methodology_defaults).toEqual({});
+    expect(settings.appearance).toBe("system");
+  });
+
+  it("saveUserSettings updates in-memory state and round-trips", async () => {
+    const client: ApiClient = new MockApiClient();
+    const saved = await client.saveUserSettings({
+      planner_model: "gpt-oss:120b",
+      writer_model: "llama3.1:70b",
+    });
+    expect(saved.planner_model).toBe("gpt-oss:120b");
+    expect(saved.writer_model).toBe("llama3.1:70b");
+    // Fresh read sees the persisted payload.
+    const reread = await client.getUserSettings();
+    expect(reread.planner_model).toBe("gpt-oss:120b");
+    expect(reread.writer_model).toBe("llama3.1:70b");
+  });
+
+  it("saveUserSettings keeps unset fields (partial update semantics)", async () => {
+    const client: ApiClient = new MockApiClient();
+    const saved = await client.saveUserSettings({ planner_model: "mistral:small" });
+    // writer_model was not in the update — the default survives.
+    expect(saved.planner_model).toBe("mistral:small");
+    expect(saved.writer_model).toBe("gpt-oss:20b");
+  });
+
+  it("setModelKey stores ONLY the masked tail in memory — never the raw key", async () => {
+    const client: ApiClient = new MockApiClient();
+    const status = await client.setModelKey("sk-live-raw-secret-7f2a");
+    expect(status.configured).toBe(true);
+    expect(status.masked).toBe("…7f2a");
+    expect(status.disabled).toBe(false);
+    // getConfigStatus reflects the stored masked state — the raw key
+    // never appears in ANY response the boundary produces.
+    const config = await client.getConfigStatus();
+    expect(config.key_status.configured).toBe(true);
+    expect(config.key_status.masked).toBe("…7f2a");
+    expect(JSON.stringify(config)).not.toContain("sk-live-raw-secret-7f2a");
+  });
+
+  it("getConfigStatus is honest: keyless tier, disabled key store", async () => {
+    const client: ApiClient = new MockApiClient();
+    const config = await client.getConfigStatus();
+    // The mock has no key store and no server key — the honest fixture.
+    expect(config.resolved_tier).toBe("keyless");
+    expect(config.key_store).toBe("disabled");
+    expect(config.cost_counters).toEqual({ runs_created: 0, runs_completed: 0 });
+    expect(config.storage_dir).toBeTruthy();
+  });
+
+  it("connection status carries the per-user tier extension on the model slot", async () => {
+    const client: ApiClient = new MockApiClient();
+    const slots = await client.getConnectionStatus();
+    const model = slots.find((s) => s.slot === "model");
+    expect(model?.resolvedTier).toBe("keyless");
+    expect(model?.keyStore).toBe("disabled");
+    expect(model?.keyStatus?.disabled).toBe(true);
+    expect(model?.keyStatus?.reason).toBeTruthy();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Live binding — real routes against a stubbed fetch                   */
+/* ------------------------------------------------------------------ */
+
+type RouteHandler = (
+  url: string,
+  init?: RequestInit,
+  body?: string,
+) => { status: number; body: unknown };
+
+function stubRoutes(routes: Record<string, RouteHandler>): typeof globalThis.fetch {
+  return (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const request = input instanceof Request ? input : undefined;
+    const url = request ? request.url : String(input);
+    // openapi-fetch serializes the body onto the Request object —
+    // surface it (plus credentials/headers) back to the route handler
+    // so the assertions see exactly what went over the wire.
+    // request.body is a ReadableStream — read it back out.
+    let body: string | undefined;
+    let sentInit: RequestInit | undefined = init;
+    if (request) {
+      const cloned = request.clone();
+      body = cloned.body ? await cloned.text() : undefined;
+      sentInit = {
+        ...init,
+        method: request.method,
+        credentials: request.credentials,
+        headers: request.headers,
+      };
+    }
+    for (const [prefix, handler] of Object.entries(routes)) {
+      if (url.startsWith(prefix)) {
+        const { status, body: responseBody } = handler(url, sentInit, body);
+        return new Response(JSON.stringify(responseBody), {
+          status,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+    }
+    return new Response(JSON.stringify({ detail: "not found" }), { status: 404 });
+  }) as typeof globalThis.fetch;
+}
+
+/** Headers actually sent on a call (CSRF + cookie assertions). */
+function headersOf(init?: RequestInit): Record<string, string> {
+  const raw = init?.headers;
+  const record: Record<string, string> = {};
+  if (
+    typeof raw === "object" &&
+    raw !== null &&
+    typeof (raw as Headers).forEach === "function"
+  ) {
+    (raw as Headers).forEach((v, k) => {
+      record[k] = v;
+    });
+  } else if (Array.isArray(raw)) {
+    for (const [k, v] of raw) record[String(k)] = String(v);
+  } else if (raw) {
+    Object.assign(record, raw);
+  }
+  return record;
+}
+
+const backendUserSettings = {
+  planner_model: "gpt-oss:20b",
+  writer_model: "gpt-oss:20b",
+  methodology_defaults: {},
+  appearance: "system",
+};
+
+const backendKeyStatus = {
+  configured: true,
+  masked: "…7f2a",
+  disabled: false,
+  reason: null,
+};
+
+const backendConfigStatus = {
+  resolved_tier: "user",
+  key_store: "enabled",
+  key_status: backendKeyStatus,
+  model_adapter: "OllamaModelAdapter",
+  search_adapter: "TavilySearchAdapter",
+  storage_dir: "/var/lib/researchx/runs",
+  probe: { endpoint: "https://ollama.com/v1", structured_outputs_supported: true },
+  cost_counters: { runs_created: 4, runs_completed: 3 },
+};
+
+describe("GeneratedApiClient per-user settings surface (live binding, T-2.9)", () => {
+  it("getUserSettings hits GET /api/config/settings with cookie discipline", async () => {
+    const routes = {
+      "http://127.0.0.1:8000/api/config/settings": (_url: string, init?: RequestInit) => {
+        // GET, never a mutation — but the cookie still rides along.
+        expect(init?.credentials).toBe("include");
+        return { status: 200, body: backendUserSettings };
+      },
+    };
+    const client = new GeneratedApiClient(stubRoutes(routes));
+    const settings = await client.getUserSettings();
+    expect(settings.planner_model).toBe("gpt-oss:20b");
+    expect(settings.appearance).toBe("system");
+  });
+
+  it("saveUserSettings PUTs a partial body with the CSRF header", async () => {
+    const routes = {
+      "http://127.0.0.1:8000/api/config/settings": (
+        _url: string,
+        init?: RequestInit,
+        body?: string,
+      ) => {
+        expect(headersOf(init)["x-researchx-request"]).toBe("1");
+        expect(init?.credentials).toBe("include");
+        // Partial body: ONLY the field the caller set travels.
+        const parsed = JSON.parse(body ?? "null") as Record<string, unknown>;
+        expect(Object.keys(parsed)).toEqual(["planner_model"]);
+        return {
+          status: 200,
+          body: { ...backendUserSettings, planner_model: "gpt-oss:120b" },
+        };
+      },
+    };
+    const client = new GeneratedApiClient(stubRoutes(routes));
+    const saved = await client.saveUserSettings({ planner_model: "gpt-oss:120b" });
+    expect(saved.planner_model).toBe("gpt-oss:120b");
+  });
+
+  it("setModelKey PUTs the raw key once and resolves ONLY the masked status", async () => {
+    const routes = {
+      "http://127.0.0.1:8000/api/config/settings/model-key": (
+        _url: string,
+        init?: RequestInit,
+        body?: string,
+      ) => {
+        expect(headersOf(init)["x-researchx-request"]).toBe("1");
+        expect(init?.credentials).toBe("include");
+        const parsed = JSON.parse(body ?? "null") as { key: string };
+        expect(parsed.key).toBe("sk-live-raw-secret-7f2a");
+        // The response is masked-only — the raw key never echoes.
+        return { status: 200, body: backendKeyStatus };
+      },
+    };
+    const client = new GeneratedApiClient(stubRoutes(routes));
+    const status = await client.setModelKey("sk-live-raw-secret-7f2a");
+    expect(status.configured).toBe(true);
+    expect(status.masked).toBe("…7f2a");
+    expect(JSON.stringify(status)).not.toContain("sk-live-raw-secret-7f2a");
+  });
+
+  it("setModelKey surfaces a disabled key store as a typed 409 with the honest reason", async () => {
+    const routes = {
+      "http://127.0.0.1:8000/api/config/settings/model-key": () => ({
+        status: 409,
+        body: {
+          detail: {
+            key_store: "disabled",
+            reason:
+              "no RESEARCHX_KEK configured (env-file secrets 'keys' scope); per-user model keys cannot be stored",
+          },
+        },
+      }),
+    };
+    const client = new GeneratedApiClient(stubRoutes(routes));
+    const error = await client
+      .setModelKey("sk-anything")
+      .catch((cause: unknown) => cause);
+    expect(error).toBeInstanceOf(KeyStoreDisabledError);
+    const typed = error as KeyStoreDisabledError;
+    expect(typed.reason).toContain("RESEARCHX_KEK");
+    // Honest refusal — never a silent no-op, never the raw key.
+    expect(JSON.stringify(typed)).not.toContain("sk-anything");
+  });
+
+  it("getConfigStatus maps the full config payload to the frontend shape", async () => {
+    const routes = {
+      "http://127.0.0.1:8000/api/config": (_url: string, init?: RequestInit) => {
+        expect(init?.credentials).toBe("include");
+        return { status: 200, body: backendConfigStatus };
+      },
+    };
+    const client = new GeneratedApiClient(stubRoutes(routes));
+    const config = await client.getConfigStatus();
+    expect(config.resolved_tier).toBe("user");
+    expect(config.key_store).toBe("enabled");
+    expect(config.key_status.masked).toBe("…7f2a");
+    expect(config.model_adapter).toBe("OllamaModelAdapter");
+    expect(config.storage_dir).toBe("/var/lib/researchx/runs");
+    expect(config.probe).not.toBeNull();
+    expect(config.cost_counters).toEqual({ runs_created: 4, runs_completed: 3 });
+  });
+
+  it("getConfigStatus tolerates a keyless degraded backend honestly", async () => {
+    const routes = {
+      "http://127.0.0.1:8000/api/config": () => ({
+        status: 200,
+        body: {
+          resolved_tier: "keyless",
+          key_store: "disabled",
+          key_status: {
+            configured: false,
+            masked: null,
+            disabled: true,
+            reason: "no RESEARCHX_KEK configured",
+          },
+          model_adapter: "OllamaModelAdapter",
+          search_adapter: "DuckDuckGoSearchAdapter",
+          storage_dir: "/var/lib/researchx/runs",
+          probe: null,
+          cost_counters: { runs_created: 0, runs_completed: 0 },
+        },
+      }),
+    };
+    const client = new GeneratedApiClient(stubRoutes(routes));
+    const config = await client.getConfigStatus();
+    expect(config.resolved_tier).toBe("keyless");
+    expect(config.key_store).toBe("disabled");
+    expect(config.key_status.disabled).toBe(true);
+    expect(config.key_status.reason).toContain("RESEARCHX_KEK");
+    expect(config.cost_counters).toEqual({ runs_created: 0, runs_completed: 0 });
+  });
+});

frontend/src/lib/types.ts

@@ -382,6 +382,34 @@ export interface ConnectionSlot {
   status: "connected" | "fallback" | "preview";
   /** Human detail, e.g. "Ollama cloud — key detected" or "Preview until v0.2". */
   detail: string;
+  /* ------------------------------------------------------------------ */
+  /* v0.3 P2 per-user credential fields (T-2.9, REQ-74). The resolved  */
+  /* tier applies to the "model" slot; the key fields mirror the       */
+  /* backend's GET /api/config. Mock mode fills honest fixture values   */
+  /* (keyless / key store disabled). Older consumers that only read    */
+  /* slot/label/status/detail stay source-compatible.                  */
+  /* ------------------------------------------------------------------ */
+  /** Credential tier this user's runs resolve to (model slot only). */
+  resolvedTier?: "user" | "server" | "keyless";
+  /** Whether the per-user key store is enabled server-side. */
+  keyStore?: "enabled" | "disabled";
+  /** Masked-only per-user model-key status — never the raw key. */
+  keyStatus?: ModelKeyStatus;
+}
+
+/**
+ * Masked-only model-key status (P2, REQ-73 — mirrors the backend's
+ * KeyStatus). The raw key NEVER appears in any field.
+ */
+export interface ModelKeyStatus {
+  /** True when a key is stored for the current user. */
+  configured: boolean;
+  /** Masked tail — "…7f2a" shape; null when nothing is stored. */
+  masked: string | null;
+  /** True when the key store is disabled server-side (no KEK). */
+  disabled: boolean;
+  /** Honest reason for a disabled/unreadable store — surfaced to the UI. */
+  reason: string | null;
 }
 
 /** The whole settings payload (maps to GET/PUT /api/config in v0.2). */
@@ -397,6 +425,64 @@ export interface Settings {
   theme: "paper";
 }
 
+/**
+ * Per-user settings (P2, REQ-72 — mirrors the backend's UserSettings
+ * from GET/PUT /api/config/settings). Model names + methodology
+ * defaults + appearance, one payload per user; fresh users get the
+ * server defaults (planner/writer "gpt-oss:20b", appearance "system").
+ */
+export interface UserSettings {
+  /** Model name the planner role runs (e.g. "gpt-oss:20b"). */
+  planner_model: string;
+  /** Model name the writer role runs. */
+  writer_model: string;
+  /** Resolved dial overrides per methodology — free-form, validated at use. */
+  methodology_defaults: Record<string, unknown>;
+  /** Appearance slot — "system" (the light palette is the only render today). */
+  appearance: string;
+}
+
+/**
+ * The per-user credential/usage status from GET /api/config (P2,
+ * REQ-74) — the live-mode settings surface. Every field is
+ * display-only except keyStatus, which drives the masked key entry.
+ */
+export interface ConfigStatus {
+  /** Credential tier the CURRENT user's runs resolve to. */
+  resolved_tier: "user" | "server" | "keyless";
+  /** Whether the server's per-user key store is enabled. */
+  key_store: "enabled" | "disabled";
+  /** Masked-only key status — never the raw key. */
+  key_status: ModelKeyStatus;
+  /** Adapter class names (display-only). */
+  model_adapter: string;
+  search_adapter: string;
+  /** Server-managed storage directory (display-only — D-111, no picker). */
+  storage_dir: string;
+  /** Capability-probe snapshot, when the adapter supports probing. */
+  probe: Record<string, unknown> | null;
+  /** Per-user usage counters (P-13). */
+  cost_counters: {
+    runs_created: number;
+    runs_completed: number;
+  };
+}
+
+/**
+ * A typed key-store refusal (P2, REQ-73): PUT model-key answered 409
+ * because the server's key store is disabled (no KEK). Carries the
+ * honest reason so the settings UI can say WHY, never a silent no-op.
+ */
+export class KeyStoreDisabledError extends Error {
+  readonly reason: string;
+
+  constructor(reason: string) {
+    super(reason);
+    this.name = "KeyStoreDisabledError";
+    this.reason = reason;
+  }
+}
+
 /**
  * The menu/display profile behind the avatar button (REQ-66).
  * v0.2 prototype shape — name + initials + tagline for the local